Полезные кастомизации itgrix_bx (Битрикс24)

Начиная с версии 3.0.0.
Дополнительные кастомизации описаны в разделе Полезные кастомизации (любая CRM).
Обновление кастомизаций, начиная с версии 3.0.0
Звонки регистрируются через API телефонии Битрикс24, что позволяет использовать сквозную аналитику.​
По сравнению кастомизациями в версиях 2.15.0–2.15.6:
Выделена кастомизация need_registration, в которой можно реализовать черные и белые списки.
Разделена кастомизация process_phone_number на два метода:
process_user_phone – кастомизация внутреннего номера пользователя;
process_client_phone – кастомизация номера клиента.
Кастомизация get_updated_entity_fields переименована в customize_entity.
Кастомизация get_updated_activity_fields переименована в customize_activity.
Схема обработки звонка модулем интеграции Itgrix
(Схема для версий начиная с 3.10.0)
Кастомизации версий 3.10+
“Сущность” – это контакт или лид.
Запрос разговора – это начало звонка на внутреннем номере.
В одном звонке может быть несколько разговоров (в случае перевода звонка).
Краткое описание кастомизаций
№
Файл кастомизации
(по алфавиту)
Описание
1
​customize_activity.php​
Обновление полей дела (в конце звонка).
2
​customize_entity.php​
Обновление полей сущности (в конце звонка).
3
​need_registration.php​
Нужна ли регистрация звонка?
Можно сделать черные/белые списки по внутреннему номеру/транку.
4
​process_client_phone.php​
Изменение номера телефона перед регистрацией в CRM:
Можно сменить формат телефонного номера (+7, 8...).
5
​process_final_params.php​
Изменение данных завершения звонка.
6
​process_originate_params.php​
Изменение параметров при инициализации звонка из CRM.
Можно позвонить через другой транк, через другой контекст, сменить формат номера и прочее.
7
​process_record_file_path.php​
Кастомизация пути до файла записи разговора.
8
​process_registration_params.php​
Изменение параметров регистрации звонка.
9
​process_task_creation_params.php​
Кастомизация создания задач по пропущенным звонкам.
10
​process_user_phone.php​
Изменение номера пользователя перед поиском пользователя в Б24.
11
​customize_autodistribution.php​
Изменение внутреннего номера при автораспределении входящего звонка.
12
​post_registration.php​
Действие после регистрации звонка.
13
​customize_show_call_card.php​
Изменение параметров отображения карточки звонка.
14
​customize_attach_record_url.php​
Изменение параметров прикрепления записи.
Входные и выходные параметры кастомизаций
1) customize_activity
Обновление полей дела в конце звонка.
Если настроено прикрепление ссылки на запись вместо самой записи, ссылка добавляется в описание дела.
Начиная с версии 3.10.0 при прикреплении ссылки на запись звонка добавлена отдельная кастомизация customize_attach_record_url, которая запускается ДО кастомизации дела.
Примеры: Обновление полей дела.
Вход:
{
  <Набор данных о разговоре (conversation, сохранен для обратной совместимости)>,
  "activity": {
    "id": "<ID дела>",
    "is_new": <Всегда false>,
    "name": "<Название дела (из поля SUBJECT)>",
    "phones": [<Всегда пустой массив>],
    "raw": {Поля дела как в Битрикс24},
    "responsible": {<Данные ответственного пользователя>},
    "responsible_id": "<ID ответственного пользователя>",
    "type": "activity"
  },
  "call_full": {<Полный набор данных о звонке>}
}
Набор данных о разговоре (conversation) описан в статье Параметры звонка (call) и разговора (conversation) в кастомизациях.
В версии 3.10.0 добавлен полный набор данных о звонке (call_full): Данные о звонке (call_full) в кастомизациях.
В объекте raw присутствуют только поля с непустым/ненулевым значением.
Вернуть:
{
  "data": {
    "<Название поля дела в Битрикс>": "<Значение этого поля>",
    ...
  },
  "state": "success"
}
Подробное описание полей дела в документации REST API Битрикс24.
2) customize_entity
До версии 3.10.0 обновление полей лида/контакта в конце входящего звонка запускалось только для сущностей, которые созданы в результате регистрации звонка модулем.
Начиная с версии 3.10.0 кастомизация запускается для всех сущностей.
Примеры: Обновление полей сущности.
Вход:
{
  "call": {<Набор данных о звонке (сохранен для обратной совместимости)>}
  "call_full": {<Полный набор данных о звонке>},
  "call_registration": {<Набор данных о регистрации звонка (сохранен для обратной совместимости)>},
  "entity": {<Данные сущности>}
  "entity_type": "<Тип сущности текстом, например lead, contact (сохранен для обратной совместимости)>",
  "entity_id": "<ID сущности, в которую будет записан звонок (сохранен для обратной совместимости)>",
  "entity_new": <true/false создана ли сущность на этом звонке (сохранено для обратной совместимости)>,
}
Набор данных о звонке (call) описан в статье Параметры звонка (call) и разговора (conversation) в кастомизациях.
В версии 3.10.0 добавлен полный набор данных о звонке (call_full): Данные о звонке (call_full) в кастомизациях.
Формат данных сущности в поле entity описан в соответствующем разделе статьи Данные о звонке (call_full) в кастомизациях.
Вернуть:
{
  "data": {
    "<Название поля сущности в Битрикс>": "<Значение этого поля>",
    ...
  },
  "state": "success"
}
Подробное описание полей лида в документации REST API Битрикс24.
Подробное описание полей контакта в документации REST API Битрикс24.
3) need_registration
Используется для реализации функционала чёрных/белых список по номерам, транкам и прочим более сложным условиям.
Начиная с версии 3.0.7 настройка черного/белого списка для внутренних номеров доступна сразу из админки (интерфейса настройки) модуля.
Примеры: Черный/белый список для транков.
Вход:
{
  "call_full": {<Полный набор данных о звонке>},
  "call_stage": "<Стадия звонка. Для данной кастомизации один из вариантов:
     conversation_requested - запрос разговора;
     conversation_accepted  - ответ;
     conversation_ended     - завершение разговора;
     call_ended             - завершение звонка>"
  <Остальные поля - набор данных о единичном разговоре (conversation) в звонке>
}
Набор данных о разговоре (conversation) описан в статье Параметры звонка (call) и разговора (conversation) в кастомизациях.
В версии 3.10.0 добавлена стадия звонка (call_stage) и полный набор данных о звонке (call_full): Данные о звонке (call_full) в кастомизациях.
Вернуть:
{
  "data": {
    "result": <true - регистрируем; false - игнорируем>
  },
  "state": "success"
}
4) process_client_phone
Преобразование телефонных номеров клиентов перед отправкой запросов в Битрикс24.
Начиная с версии 3.0.0 кастомизация номера разделена на две:
process_user_phone – кастомизация внутреннего номера пользователя;
process_client_phone – кастомизация номера клиента.
Начиная с версии 3.7.0 доступна автозамена номеров, она запускается ДО выполнения кастомизации.
Примеры в статье Изменение номера телефона перед отправкой данных в CRM.
Вход:
{
  "phone": "<номер>",
  
  "call_full": {<Полный набор данных о звонке>},
  "call_stage": "<Стадия звонка. Для данной кастомизации один из вариантов:
     conversation_requested - запрос разговора;
     conversation_accepted  - ответ;
     conversation_ended     - завершение разговора;
     call_ended             - завершение звонка>"
}
В версии 3.10.0 добавлена стадия звонка (call_stage) и полный набор данных о звонке (call_full): Данные о звонке (call_full) в кастомизациях.
Вернуть:
{
  "data": {
    "phone": “<Кастомизированный номер>”
  },
  "state": "success"
}
5) process_final_params
Кастомизация параметров завершения регистрации звонка.
Примеры: Разные ответственные за пропущенные за разные транки.
Черные/белые списки начиная с версии 2.15.0 настраиваются в кастомизации need_registration.
Начиная с версии 3.0.7 настройка черного/белого списка для внутренних номеров доступна сразу из админки (интерфейса настройки) модуля.
Подробнее в статье Черные и белые списки. Как настроить?​
Вход:
{
  "params": {
    "ADD_TO_CHAT": <[0/1] Добавить ли сообщение о звонке в бизнес чат.
                    По умолчанию 1>,
    "CALL_ID": "<ID звонка в Битрикс24. Не рекомендуется изменять!>",
    "DURATION": <Длительность звонка в секундах>,
    "STATUS_CODE": "<Статус звонка в Битрикс24>",
    "USER_ID": <ID пользователя Битрикс24, ответственного за разговор>,
    
    "call": {<Набор данных о звонке (сохранен для обратной совместимости)>},
    "entity_type": "<Тип сущности текстом, например lead, contact (сохранен для обратной совместимости)>",
    "entity_id": "<ID сущности, в которую будет записан звонок (сохранен для обратной совместимости)>",
    "entity_new": <true/false создана ли сущность на этом звонке (сохранено для обратной совместимости)>,
    "call_full": {<Полный набор данных о звонке>},
    "call_registration": { (сохранено для обратной совместимости)
      "id": "<ID звонка в Битрикс24 (совпадает с CALL_ID)>",
      "created_lead_id": "<ID созданного лида (или пустая строка)>",
      "created_contact_id": "<ID созданного контакта (или пустая строка)>",
      "created_deal_id": "<ID созданной сделки (или пустая строка)>",
      "created_company_id": "<ID созданной компании (или пустая строка)>",
      "activity_id": "<ID созданного дела (или пустая строка)>",
      "entity_id": "<ID сущности (совпадает с полем entity_id выше)>",
      "entity_type": "<Тип сущности (совпадает с полем entity_type выше)>",
      "responsible_id": "<ID ответственного за звонок пользователя (совпадает с USER_ID)>"
    }
  }
}
Статусы звонка в Битрикс24 описаны в статье Детальные статусы звонка.
Набор данных о звонке (call) описан в статье Параметры звонка (call) и разговора (conversation) в кастомизациях.
В версии 3.10.0 добавлен полный набор данных о звонке (call_full): Данные о звонке (call_full) в кастомизациях.
Вернуть:
{
  "data": {
    "ADD_TO_CHAT": <[0/1] Добавить ли сообщение о звонке в бизнес чат>,
    "CALL_ID": "<ID звонка в Битрикс24. Не рекомендуется изменять!>",
    "DURATION": <Длительность звонка в секундах>,
    "STATUS_CODE": "<Статус звонка>",
    "USER_ID": <ID пользователя Битрикс24, ответственного за разговор>
  },
  "state": "success"
}
Подробное описание параметров завершения звонка в документации REST API Битрикс24.
6) process_originate_params
Изменение параметров при инициализации звонка из Битрикс24.
Подробное описание с примерами в статье Изменение параметров при click-to-call.
7) process_record_file_path
Преобразование пути до файла записи разговора.
Подробное описание с примерами в статье Кастомизация имени файла аудиозаписи.
При установке Itgrix_bx по умолчанию уже включена конвертация файлов записей разговоров в формат mp3 перед отправкой в Битрикс24. Это позволяет вам:
1.Сэкономить место на диске Битрикс24 (mp3 занимает меньше, чем wav);
2.Прослушивать записи при помощи встроенного в CRM плеера.
Поскольку конвертация записей может занимать значительное время, у этой кастомизации особый, фиксированный таймаут 10 секунд, который не зависит от настроек кастомизаций.
Если запись не успеет сконвертироваться до истечения таймаута, будет использован исходный файл.
8) process_registration_params
Используется для кастомизации параметров регистрации начала звонка.
Примеры:
​Добавление кода города в зависимости от города оператора​
​Изменение первого ответственного за лид/контакт​
​Создавать лид для каждого входящего звонка​
Вход:
{
  "params": {
    "CALL_START_DATE": "<Дата-время начала звонка>",
    "CRM_CREATE": <[0/1] Создавать или нет новый лид (если номер не найден в CRM)>,
    "CRM_SOURCE": "<STATUS_ID источника из справочника источников>",
    "LINE_NUMBER": "<Номер внешней линии в Битрикс24, через который совершался звонок>",
    "PHONE_NUMBER": "<Номер для поиска сущности в битрикс>",
    "SHOW": <[0/1] Показывать ли карточку звонка при регистрации>,
    "TYPE": <Направление звонка: 1 - исходящий, 2 - входящий>,
    "USER_ID": <ID пользователя>,
    
    "call_full": {<Полный набор данных о звонке>},
    "call_stage": "<Стадия звонка. Для данной кастомизации один из вариантов:
      conversation_requested - запрос разговора;
      call_ended             - завершение звонка>",
    "conversation": {<Набор данных о разговоре (сохранен для обратной совместимости)>}
  }
}
Набор данных о разговоре (conversation) описан в статье Параметры звонка (call) и разговора (conversation) в кастомизациях.
В версии 3.10.0 добавлен полный набор данных о звонке (call_full): Данные о звонке (call_full) в кастомизациях.
Номера внешних линий в Битрикс24 (LINE_NUMBER) соответствуют транкам в настройках коннектора Itgrix.
Коннектор регистрирует номера транков как внешние линии в Битрикс24 при запуске, при этом каждой линии можно задать название в настройках.
В версии 3.10.0 показ карточки звонка вынесен в отдельный запрос, и кастомизируется отдельной кастомизацией customize_show_call_card, поэтому параметр SHOW всегда равен 0.
Это связано с тем, что теперь можно настроить, показывать карточку звонка в момент дозвона или при ответе.
Вернуть:
{
  "data": { 
    "CALL_START_DATE": "<Дата-время начала звонка>",
    "CRM_CREATE": <[0/1] Создавать или нет новый лид (если номер не найден в CRM)>,
    "CRM_SOURCE": "<STATUS_ID источника из справочника источников>",
    "LINE_NUMBER": "<Номер внешней линии в Битрикс24, через который совершался звонок>",
    "PHONE_NUMBER": "<Номер для поиска сущности в битрикс>",
    "SHOW": <[0/1] Показывать ли карточку звонка при регистрации>,
    "TYPE": <Направление звонка: 1 - исходящий, 2 - входящий>,
    "USER_ID": <ID пользователя>
  },
  "state": "success"
}
Подробное описание параметров регистрации звонка в документации REST API Битрикс24.
9) process_task_creation_params
Кастомизация параметров создания задачи (при пропущенном входящем звонке или неотвеченном исходящем).
Данная кастомизация работает, только если создание задач включено в настройках коннектора: Настройка задачи по пропущенному через админку.
При этом сначала применяются настройки, описанные в статье, а затем выполняется данная кастомизация.
Пример: Кастомизация задач по пропущенным звонкам (начиная с версии 3.4.0 это можно делать через веб-интерфейс настройки модуля).
Вход:
{
  "fields": {
    "CREATED_BY": <ID постановщика>,
    "DEADLINE": "<Крайний срок исполнения>",
    "RESPONSIBLE_ID": <ID сотрудника, ответственного за задачу>,
    "TITLE": "<Заголовок задачи>",
    "UF_CRM_TASK": ["<ID сущности в специальном формате:
                      <Тип сущности>_<ID>.
                      Типы сущности:
                        лид      - L
                        контакт  - C,
                        компания - CO,
                        дело     - D.
                      Пример: L_11201 для лида с ID 11201 >"]
  },
​
  "call_full": {<Полный набор данных о звонке>},
  "conversation": {<Набор данных о разговоре (сохранен для обратной совместимости)>}
}
В версии 2.15.0 добавлен блок данных о разговоре (conversation). Набор данных о разговоре (conversation) описан в статье Параметры звонка (call) и разговора (conversation) в кастомизациях.
В версии 3.10.0 добавлен полный набор данных о звонке (call_full): Данные о звонке (call_full) в кастомизациях.
Вернуть:
{
  "data": {
    "fields": {
      "<Название поля задачи в Битрикс>": "<Значение этого поля>"
      ...
    }
  },
  "state": "success"
}
Подробное описание полей задачи в документации REST API Битрикс24.
10) process_user_phone
Изменение номера пользователя перед поиском пользователя Битрикс24.
Начиная с версии 3.0.0 кастомизация номера разделена на две:
process_user_phone – кастомизация внутреннего номера пользователя;
process_client_phone – кастомизация номера клиента.
Начиная с версии 3.7.0 доступна автозамена номеров, она запускается ДО выполнения кастомизации.
Пример: Несколько внутренних номеров у сотрудника.
Вход:
{
  "phone": "<номер>",
  
  "call_full": {<Полный набор данных о звонке>},
  "call_stage": "<Стадия звонка. Для данной кастомизации один из вариантов:
    conversation_requested - запрос разговора;
    conversation_accepted  - ответ;
    conversation_ended     - завершение разговора;
    call_ended             - завершение звонка>"
}
В версии 3.10.0 добавлена стадия звонка (call_stage) и полный набор данных о звонке (call_full): Данные о звонке (call_full) в кастомизациях.
Вернуть:
{
  "data": {
    "phone": "<кастомизированный_номер>"
  },
  "state": "success"
}
11) customize_autodistribution
Вход:
{
  "number": "<номер пользователя на которого распределять звонок>",
  "name":   "<имя пользователя на которого распределять звонок>",
​
  "from": "<номер с которого пришёл звонок>",
  "user": {
    "id":       <ID пользователя числом>,
    "phones":   ["<список номеров пользователя>"],
    "name":     "<Полное имя пользователя>",
    "email":    "<email пользователя>",
    "position": "<должность пользователя>"
  },
  "entity": {
    "type":           "<Тип сущности текстом, например lead, contact>",
    "id":             <ID сущности числом>,
    "name":           "<Имя сущности>",
    "responsible_id": <ID ответственного пользователя числом>
  },
  "error": "<текст ошибки>"
}
Вернуть:
{
  "data": {
    "number": "<Номер пользователя, на которого распределять звонок>",
    "name":   "<Имя пользователя, на которого распределять звонок>"
  },
  "state": "success"
}
name - текст который появится в CallerID и будет отображен в телефоне (или софтфоне) оператора.
Должен быть не более 20 символов (ограничение Asterisk)!
Поля from, user, entity и error - только для чтения и присутствуют только когда не пустые.
Они будут автоматически удалены, даже если вернуть их в объекте data.
12) post_registration
Кастомизация добавлена в версии 3.10.0.
Данная кастомизация дает возможность выполнить какие-либо действия после регистрации звонка.
Может быть вызвана в разные моменты в зависимости от типа звонка:
Для звонков кликом (click-to-call, c2c) кастомизация будет вызвана в начале обработки стадии Запрос разговора (Conversation requested).
При звонках кликом Битрикс24 сам регистрирует звонок в момент клика и передает данные о регистрации коннектору, т.е. ещё до инициализации звонка в Asterisk. 
Поэтому звонки кликом коннектор сам НЕ регистрирует, а только заканчивает как и все остальные звонки.
Пропущенные звонки на IVR регистрируются и завершаются на стадии Завершение звонка (Call ended).
Для всех остальных звонков кастомизация будет вызвана после выполнения запроса регистрации звонка в Битрикс24 на стадии Запрос разговора (Conversation requested).
Вход:
{
  "call_full": {<Полный набор данных о звонке>},
  "call_stage": "<Стадия звонка. Для данной кастомизации один из вариантов:
    conversation_requested - запрос разговора;
    call_ended             - завершение звонка>",
}
Полный набор данных о звонке описан в статье Данные о звонке (call_full) в кастомизациях.
Вернуть:
Нужно вернуть только state, остальное игнорируется:
{
  "state": "success"
}
13) customize_show_call_card
Кастомизация добавлена в версии 3.10.0.
Используется для кастомизации параметров отображения карточки звонка.
Вход:
{
  "CALL_ID": <ID зарегистрированного звонка в Битрикс24>,
  "USER_ID": <ID пользователя>,
  
  "call_full": {<Полный набор данных о звонке>},
  "call_stage": "<Стадия звонка. Для данной кастомизации один из вариантов:
    conversation_requested - запрос разговора;
    conversation_accepted  - ответ;
    conversation_ended     - завершение разговора;
    call_ended             - завершение звонка>"
 }
Полный набор данных о звонке описан в статье Данные о звонке (call_full) в кастомизациях.
Вернуть:
{
  "data": { 
    "CALL_ID": <ID зарегистрированного звонка в Битрикс24>,
    "USER_ID": <ID пользователя>
  },
  "state": "success"
}
Подробное описание параметров показа карточки в документации REST API Битрикс24.
14) customize_attach_record_url
Кастомизация добавлена в версии 3.10.0.
Кастомизация прикрепления ссылки на запись звонка. Запускается только если настроено прикрепление ссылки на запись вместо файла записи звонка.
По умолчанию в описание дела записывается HTML-код аудиоплеера (тег audio) со ссылкой на запись звонка.
Вход:
{
  "DESCRIPTION": "<Описание дела с аудиоплеером и ссылкой на запись звонка>",
  "DESCRIPTION_TYPE": <Тип содержания в виде целого числа, по умолчанию 3, т.е. HTML>,
​
  "activity": {
    "id": "<ID дела>",
    "is_new": <Всегда false>,
    "name": "<Название дела (из поля SUBJECT)>",
    "phones": [<Всегда пустой массив>],
    "raw": {Поля дела как в Битрикс24},
    "responsible": {<Данные ответственного пользователя>},
    "responsible_id": "<ID ответственного пользователя>",
    "type": "activity"
  },
  "call_full": {<Полный набор данных о звонке>}
 }
Полный набор данных о звонке описан в статье Данные о звонке (call_full) в кастомизациях.
В объекте raw присутствуют только поля с непустым/ненулевым значением.
Вернуть:
{
  "data": {
    "<Название поля дела в Битрикс>": "<Значение этого поля>",
      ...
  },
  "state": "success"
}
Подробное описание полей дела в документации REST API Битрикс24.
Параметры звонка (call) и разговора (conversation) в кастомизациях
Несколько внутренних номеров у сотрудника
Last modified 2mo ago
№	Файл кастомизации (по алфавиту)	Описание
1	customize_activity.php	Обновление полей дела (в конце звонка).
2	customize_entity.php	Обновление полей сущности (в конце звонка).
3	need_registration.php	Нужна ли регистрация звонка? Можно сделать черные/белые списки по внутреннему номеру/транку.
4	process_client_phone.php	Изменение номера телефона перед регистрацией в CRM: Можно сменить формат телефонного номера (+7, 8...).
5	process_final_params.php	Изменение данных завершения звонка.
6	process_originate_params.php	Изменение параметров при инициализации звонка из CRM. Можно позвонить через другой транк, через другой контекст, сменить формат номера и прочее.
7	process_record_file_path.php	Кастомизация пути до файла записи разговора.
8	process_registration_params.php	Изменение параметров регистрации звонка.
9	process_task_creation_params.php	Кастомизация создания задач по пропущенным звонкам.
10	process_user_phone.php	Изменение номера пользователя перед поиском пользователя в Б24.
11	customize_autodistribution.php	Изменение внутреннего номера при автораспределении входящего звонка.
12	post_registration.php	Действие после регистрации звонка.
13	customize_show_call_card.php	Изменение параметров отображения карточки звонка.
14	customize_attach_record_url.php	Изменение параметров прикрепления записи.