Полезные кастомизации itgrix_bx (Битрикс24)
Данная статья актуальна для версий коннектора 3.10.*
Для предыдущих версий можно воспользоваться "исторической" версией статьи: Полезные кастомизации itgrix_bx (Битрикс24) [С историей]
Кастомизации версий 3.10+
"Сущность" в логике коннектора – это контакт или лид.
Запрос разговора – это начало звонка на внутреннем номере.
В одном звонке может быть несколько разговоров (в случае перевода звонка).
№ | Файл кастомизации
(по алфавиту) | Описание |
1 | Обновление полей дела (в конце звонка). | |
2 | Обновление полей сущности (в конце звонка). | |
3 | Нужна ли регистрация звонка?
Можно сделать черные/белые списки по внутреннему номеру/ транку. | |
4 | Изменение номера телефона перед регистрацией в CRM:
Можно сменить формат телефонного номера (+7, 8...). | |
5 | Изменение данных завершения звонка. | |
6 | Изменение параметров при инициализации звонка из CRM.
Можно позвонить через другой транк, через другой контекст, сменить формат номера и прочее. | |
7 | Кастомизация пути до файла записи разговора. | |
8 | Изменение параметров регистрации звонка. | |
9 | Кастомизация создания задач по пропущенным звонкам. | |
10 | Изменение номера пользователя перед поиском пользователя в Б24. | |
11 | Изменение внутреннего номера при автораспределении входящего звонка. | |
12 | Действие после регистрации звонка. | |
13 | Изменение параметров отображения карточки звонка. | |
14 | Изменение параметров прикрепления записи. |
Обновление полей дела в конце звонка.
Вход:
{
<Набор данных о разговоре (conversation, сохранен для обратной совместимости)>,
"activity": {
"id": "<ID дела>",
"is_new": <Всегда false>,
"name": "<Название дела (из поля SUBJECT)>",
"phones": [<Всегда пустой массив>],
"raw": {Поля дела как в Битрикс24},
"responsible": {<Данные ответственного пользователя>},
"responsible_id": "<ID ответственного пользователя>",
"type": "activity"
},
"call_full": {<Полный набор данных о звонке>}
}
В объекте
raw присутствуют только поля с непустым/ненулевым значением.Вернуть:
{
"data": {
"<Название поля дела в Битрикс>": "<Значение этого поля>",
...
},
"state": "success"
}
Вход:
{
"call_full": {<Полный набор данных о звонке>},
<Остальные поля сохранены для обратной совместимости>
}
Вернуть:
{
"data": {
"<Название поля сущности в Битрикс>": "<Значение этого поля>",
...
},
"state": "success"
}
Подробное описание полей лида в документации REST API Битрикс24.
Подробное описание полей контакта в документации REST API Битрикс24.
Используется для реализации функционала чёрных/белых списков по номерам, транкам и прочим более сложным условиям.
Базовая настройка черного/белого списка для внутренних номеров доступна из админки (интерфейса настройки) коннектора.
Вход:
{
"call_full": {<Полный набор данных о звонке>},
"call_stage": "<Стадия звонка. Для данной кастомизации один из вариантов:
conversation_requested - запрос разговора;
conversation_accepted - ответ;
conversation_ended - завершение разговора;
call_ended - завершение звонка>"
<Остальные поля сохранены для обратной совместимости>
}
Вернуть:
{
"data": {
"result": <true - регистрируем; false - игнорируем>
},
"state": "success"
}
Преобразование телефонных номеров клиентов перед отправкой запросов в Битрикс24.
Вход:
{
"phone": "<номер>",
"call_full": {<Полный набор данных о звонке>},
"call_stage": "<Стадия звонка. Для данной кастомизации один из вариантов:
conversation_requested - запрос разговора;
conversation_accepted - ответ;
conversation_ended - завершение разговора;
call_ended - завершение звонка>"
}
Вернуть:
{
"data": {
"phone": “<Кастомизированный номер>”
},
"state": "success"
}
Кастомизация параметров завершения регистрации звонка.
Вход:
{
"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"
}
Изменение параметров при инициализации звонка из Битрикс24.
Преобразование пути до файла записи разговора.
При установке Itgrix_bx по умолчанию уже включена конвертация файлов записей разговоров в формат mp3 перед отправкой в Битрикс24. Это позволяет вам:
- 1.Сэкономить место на диске Битрикс24 (mp3 занимает меньше, чем wav);
- 2.Прослушивать записи при помощи встроенного в CRM плеера.
Поскольку конвертация записей может занимать значительное время, у этой кастомизации особый, фиксированный таймаут 10 секунд, который не зависит от настроек кастомизаций.
Если запись не успеет сконвертироваться до истечения таймаута, будет использован исходный файл.
Используется для кастомизации параметров регистрации начала звонка.
Примеры:
Вход:
{
"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 при запуске, при этом каждой линии можно задать название в настройках.
Показ карточки звонка вынесен в отдельный запрос, и кастомизируется отдельной кастомизацией 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"
}
Кастомизация параметров создания задачи (при пропущенном входящем звонке или неотвеченном исходящем).
Данная кастомизация работает, только если создание задач включено в настройках коннектора: Настройка задачи по пропущенному через админку.
При этом сначала применяются настройки, описанные в статье, а затем выполняется данная кастомизация.
Пример: Кастомизация задач по пропущенным звонкам (начиная с версии 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": {<Полный набор данных о звонке>},
<Остальные поля сохранены для обратной совместимости>
}
Вернуть:
{
"data": {
"fields": {
"<Название поля задачи в Битрикс>": "<Значение этого поля>"
...
}
},
"state": "success"
}
Изменение номера пользователя перед поиском пользователя Битрикс24.
Вход:
{
"phone": "<номер>",
"call_full": {<Полный набор данных о звонке>},
"call_stage": "<Стадия звонка. Для данной кастомизации один из вариантов:
conversation_requested - запрос разговора;
conversation_accepted - ответ;
conversation_ended - завершение разговора;
call_ended - завершение звонка>"
}
Вернуть:
{
"data": {
"phone": "<кастомизированный_номер>"
},
"state": "success"
}
Вход:
{
"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.Данная кастомизация дает возможность выполнить какие-либо действия после регистрации звонка.
Может быть вызвана в разные моменты в зависимости от типа звонка:
- Для звонков кликом (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"
}
Используется для кастомизации параметров отображения карточки звонка.
Вход:
{
"CALL_ID": <ID зарегистрированного звонка в Битрикс24>,
"USER_ID": <ID пользователя>,
"call_full": {<Полный набор данных о звонке>},
"call_stage": "<Стадия звонка. Для данной кастомизации один из вариантов:
conversation_requested - запрос разговора;
conversation_accepted - ответ;
conversation_ended - завершение разговора;
call_ended - завершение звонка>"
}
Вернуть:
{
"data": {
"CALL_ID": <ID зарегистрированного звонка в Битрикс24>,
"USER_ID": <ID пользователя>
},
"state": "success"
}
Кастомизация прикрепления ссылки на запись звонка. Запускается только если настроено прикрепление ссылки на запись вместо файла записи звонка.
По умолчанию в описание дела записывается 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"
}