Данная статья актуальна для версий коннектора 3.10.*
Для предыдущих версий можно воспользоваться "исторической" версией статьи:
Дополнительные кастомизации описаны в разделе .
Схема обработки звонка модулем интеграции Itgrix
"Сущность" в логике коннектора – это контакт или лид.
Запрос разговора – это начало звонка на внутреннем номере.
В одном звонке может быть несколько разговоров (в случае перевода звонка).
Краткое описание кастомизаций
№
Файл кастомизации
(по алфавиту)
Описание
1
Обновление полей дела (в конце звонка).
2
Обновление полей сущности (в конце звонка).
3
Нужна ли регистрация звонка?
Можно сделать черные/белые списки по внутреннему номеру/транку.
4
Изменение номера телефона перед регистрацией в CRM:
Можно сменить формат телефонного номера (+7, 8...).
5
Изменение данных завершения звонка.
6
Изменение параметров при инициализации звонка из CRM.
Можно позвонить через другой транк, через другой контекст, сменить формат номера и прочее.
7
Кастомизация пути до файла записи разговора.
8
Изменение параметров регистрации звонка.
9
Кастомизация создания задач по пропущенным звонкам.
10
Изменение номера пользователя перед поиском пользователя в Б24.
11
Изменение внутреннего номера при автораспределении входящего звонка.
12
Действие после регистрации звонка.
13
Изменение параметров отображения карточки звонка.
14
Изменение параметров прикрепления записи.
Входные и выходные параметры кастомизаций
1) customize_activity
Обновление полей дела в конце звонка.
Вход:
{
<Набор данных о разговоре (conversation, сохранен для обратной совместимости)>,
"activity": {
"id": "<ID дела>",
"is_new": <Всегда false>,
"name": "<Название дела (из поля SUBJECT)>",
"phones": [<Всегда пустой массив>],
"raw": {Поля дела как в Битрикс24},
"responsible": {<Данные ответственного пользователя>},
"responsible_id": "<ID ответственного пользователя>",
"type": "activity"
},
"call_full": {<Полный набор данных о звонке>}
}
В объекте raw присутствуют только поля с непустым/ненулевым значением.
Вернуть:
{
"data": {
"<Название поля дела в Битрикс>": "<Значение этого поля>",
...
},
"state": "success"
}
2) customize_entity
Вход:
{
"call_full": {<Полный набор данных о звонке>},
<Остальные поля сохранены для обратной совместимости>
}
Вернуть:
{
"data": {
"<Название поля сущности в Битрикс>": "<Значение этого поля>",
...
},
"state": "success"
}
3) need_registration
Используется для реализации функционала чёрных/белых списков по номерам, транкам и прочим более сложным условиям.
Вход:
{
"call_full": {<Полный набор данных о звонке>},
"call_stage": "<Стадия звонка. Для данной кастомизации один из вариантов:
conversation_requested - запрос разговора;
conversation_accepted - ответ;
conversation_ended - завершение разговора;
call_ended - завершение звонка>"
<Остальные поля сохранены для обратной совместимости>
}
Преобразование телефонных номеров клиентов перед отправкой запросов в Битрикс24.
Вход:
{
"phone": "<номер>",
"call_full": {<Полный набор данных о звонке>},
"call_stage": "<Стадия звонка. Для данной кастомизации один из вариантов:
conversation_requested - запрос разговора;
conversation_accepted - ответ;
conversation_ended - завершение разговора;
call_ended - завершение звонка>"
}
Кастомизация параметров завершения регистрации звонка.
Вход:
{
"ADD_TO_CHAT": <[0/1] Добавить ли сообщение о звонке в бизнес чат.
По умолчанию 1>,
"CALL_ID": "<ID звонка в Битрикс24. Не рекомендуется изменять!>",
"DURATION": <Длительность звонка в секундах>,
"STATUS_CODE": "<Статус звонка в Битрикс24>",
"USER_ID": <ID пользователя Битрикс24, ответственного за разговор>,
"call_full": {<Полный набор данных о звонке>},
<Остальные поля сохранены для обратной совместимости>
}
Вернуть:
{
"data": {
"ADD_TO_CHAT": <[0/1] Добавить ли сообщение о звонке в бизнес чат>,
"CALL_ID": "<ID звонка в Битрикс24. Не рекомендуется изменять!>",
"DURATION": <Длительность звонка в секундах>,
"STATUS_CODE": "<Статус звонка>",
"USER_ID": <ID пользователя Битрикс24, ответственного за разговор>
},
"state": "success"
}
6) process_originate_params
Изменение параметров при инициализации звонка из Битрикс24.
7) process_record_file_path
Преобразование пути до файла записи разговора.
Сэкономить место на диске Битрикс24 (mp3 занимает меньше, чем wav);
Прослушивать записи при помощи встроенного в CRM плеера.
Поскольку конвертация записей может занимать значительное время, у этой кастомизации особый, фиксированный таймаут 10 секунд, который не зависит от настроек кастомизаций.
Если запись не успеет сконвертироваться до истечения таймаута, будет использован исходный файл.
8) process_registration_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 - завершение звонка>",
<Остальные поля сохранены для обратной совместимости>
}
Номера внешних линий в Битрикс24 (LINE_NUMBER) соответствуют транкам в настройках коннектора Itgrix.
Коннектор регистрирует номера транков как внешние линии в Битрикс24 при запуске, при этом каждой линии можно задать название в настройках.
Это связано с тем, что можно настроить, показывать карточку звонка в момент дозвона или при ответе.
Вернуть:
{
"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"
}
9) process_task_creation_params
Кастомизация параметров создания задачи (при пропущенном входящем звонке или неотвеченном исходящем).
При этом сначала применяются настройки, описанные в статье, а затем выполняется данная кастомизация.
Вход:
{
"fields": {
"CREATED_BY": <ID постановщика>,
"DEADLINE": "<Крайний срок исполнения>",
"RESPONSIBLE_ID": <ID сотрудника, ответственного за задачу>,
"TITLE": "<Заголовок задачи>",
"UF_CRM_TASK": ["<ID сущности в специальном формате:
<Тип сущности>_<ID>.
Типы сущности:
лид - L
контакт - C,
компания - CO,
дело - D.
Пример: L_11201 для лида с ID 11201 >"]
},
"call_full": {<Полный набор данных о звонке>},
<Остальные поля сохранены для обратной совместимости>
}
Вернуть:
{
"data": {
"fields": {
"<Название поля задачи в Битрикс>": "<Значение этого поля>"
...
}
},
"state": "success"
}
10) process_user_phone
Изменение номера пользователя перед поиском пользователя Битрикс24.
Вход:
{
"phone": "<номер>",
"call_full": {<Полный набор данных о звонке>},
"call_stage": "<Стадия звонка. Для данной кастомизации один из вариантов:
conversation_requested - запрос разговора;
conversation_accepted - ответ;
conversation_ended - завершение разговора;
call_ended - завершение звонка>"
}
{
"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
Данная кастомизация дает возможность выполнить какие-либо действия после регистрации звонка.
Может быть вызвана в разные моменты в зависимости от типа звонка:
Для звонков кликом (click-to-call, c2c) кастомизация будет вызвана в начале обработки стадии Запрос разговора (Conversation requested).
При звонках кликом Битрикс24 сам регистрирует звонок в момент клика и передает данные о регистрации коннектору, т.е. ещё до инициализации звонка в Asterisk.
Поэтому звонки кликом коннектор сам НЕ регистрирует, а только заканчивает как и все остальные звонки.
Пропущенные звонки на IVR регистрируются и завершаются на стадии Завершение звонка (Call ended).
Для всех остальных звонков кастомизация будет вызвана после выполнения запроса регистрации звонка в Битрикс24 на стадии Запрос разговора (Conversation requested).
Вход:
{
"call_full": {<Полный набор данных о звонке>},
"call_stage": "<Стадия звонка. Для данной кастомизации один из вариантов:
conversation_requested - запрос разговора;
call_ended - завершение звонка>",
}
Вернуть:
Нужно вернуть только state, остальное игнорируется:
{
"state": "success"
}
13) customize_show_call_card
Используется для кастомизации параметров отображения карточки звонка.
Вход:
{
"CALL_ID": <ID зарегистрированного звонка в Битрикс24>,
"USER_ID": <ID пользователя>,
"call_full": {<Полный набор данных о звонке>},
"call_stage": "<Стадия звонка. Для данной кастомизации один из вариантов:
conversation_requested - запрос разговора;
conversation_accepted - ответ;
conversation_ended - завершение разговора;
call_ended - завершение звонка>"
}
Кастомизация прикрепления ссылки на запись звонка. Запускается только если настроено прикрепление ссылки на запись вместо файла записи звонка.
По умолчанию в описание дела записывается 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": {<Полный набор данных о звонке>}
}
В объекте raw присутствуют только поля с непустым/ненулевым значением.
Вернуть:
{
"data": {
"<Название поля дела в Битрикс>": "<Значение этого поля>",
...
},
"state": "success"
}
Примеры: .
Полный набор данных о звонке описан в статье .
Подробное описание полей дела в .
Примеры: .
Полный набор данных о звонке описан в статье .
Подробное описание полей лида в .
Подробное описание полей контакта в .
Базовая настройка черного/белого списка для внутренних номеров доступна .
Примеры:.
Полный набор данных о звонке описан в статье .
Доступна , она запускается ДО выполнения кастомизации.
Примеры в статье .
Полный набор данных о звонке описан в статье .
Примеры: .
Статусы звонка в Битрикс24 описаны в .
Полный набор данных о звонке описан в статье .
Подробное описание параметров завершения звонка в .
Подробное описание с примерами в статье .
Подробное описание с примерами в статье .
При установке Itgrix_bx по умолчанию уже включена перед отправкой в Битрикс24. Это позволяет вам:
Полный набор данных о звонке описан в статье .
Показ карточки звонка вынесен в отдельный запрос, и кастомизируется отдельной кастомизацией , поэтому параметр SHOW всегда равен 0.
Подробное описание параметров регистрации звонка в .
Данная кастомизация работает, только если создание задач включено в настройках коннектора: .
Пример: (начиная с версии это можно ).
Полный набор данных о звонке описан в статье .
Подробное описание полей задачи в .
Доступна , она запускается ДО выполнения кастомизации.