Полезные кастомизации itgrix_bx (Битрикс24)
Схема обработки звонка модулем интеграции Itgrix
"Сущность" в логике коннектора – это контакт или лид. Запрос разговора – это начало дозвона на внутреннем номере. В одном звонке может быть несколько разговоров (в случае перевода звонка, группы, очереди и т.п.).
Отмена запросов
Кастомизации, запускаемые непосредственно перед выполнением запросов к CRM, позволяют отменить отправку соответствующего запроса.
Для этого нужно вернуть пустой объект data.
Пример данных для отмены запроса:
{
"data": {},
"state": "success"
}Кроме значения {}, также допустимы варианты [] и null.
Отмена запроса отмечается в логе текстом "cancelled by customization" и не считается ошибкой, но отсутствие данных, которые ожидалось получить в ответе на запрос, может привести к ошибкам последующих шагов обработки звонка и должно быть учтено в остальных кастомизациях.
Краткое описание кастомизаций
№
Файл кастомизации (по алфавиту)
Описание
3
Нужна ли регистрация звонка? Можно сделать черные/белые списки по внутреннему номеру/транку.
4
Изменение номера телефона перед регистрацией в CRM: Можно сменить формат телефонного номера (+7, 8...).
6
Изменение параметров при инициализации звонка из CRM. Можно позвонить через другой транк, через другой контекст, сменить формат номера и прочее.
11
Изменение внутреннего номера при автораспределении входящего звонка.
15
При получении результата Click-to-Call (событие OriginateResponse) от Asterisk. Позволяет выполнить дополнительные действия при успехе/ошибке Originate.
18
Кастомизация для игнорируемых событий звонка, которые намеренно не обрабатываются стандартной логикой.
Входные и выходные параметры кастомизаций
1) customize_activity
Обновление полей дела в конце звонка.
Примеры: Обновление полей дела.
Вход:
{
"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.
Запрос обновления дела не будет выполнен, если вернуть пустой объект data.
2) customize_entity
Примеры: Обновление полей сущности.
Вход:
{
"call_full": {<Полный набор данных о звонке>},
<Остальные поля временно сохранены для обратной совместимости: call_registration, entity, entity_type, entity_id, entity_new>
}Полный набор данных о звонке описан в статье Данные о звонке (call_full) в кастомизациях.
Часть полей в корне входных данных кастомизации считаются устаревшими и будут убраны в будущих версиях коннектора.
Вместо них рекомендуется использовать актуальные поля внутри объекта call_full:
call_registration→call_full.registrationentity→call_full.entityentity_type→call_full.entity.typeentity_id→call_full.entity.identity_new→call_full.entity.is_new
Вернуть:
{
"data": {
"<Название поля сущности в Битрикс>": "<Значение этого поля>",
...
},
"state": "success"
}Подробное описание полей лида в документации REST API Битрикс24.
Подробное описание полей контакта в документации REST API Битрикс24.
Запрос обновления сущности не будет выполнен, если вернуть пустой объект data.
3) need_registration
Используется для реализации функционала чёрных/белых списков по номерам, транкам и прочим более сложным условиям.
Примеры: Черный/белый список для транков.
Вход:
{
"call_full": {<Полный набор данных о звонке>},
"call_stage": "<Стадия звонка. Для данной кастомизации один из вариантов:
conversation_requested - запрос разговора;
conversation_accepted - ответ;
conversation_ended - завершение разговора;
call_ended - завершение звонка>"
}Полный набор данных о звонке описан в статье Данные о звонке (call_full) в кастомизациях.
Вернуть:
{
"data": {
"result": <true - регистрируем; false - игнорируем>
},
"state": "success"
}4) process_client_phone
Преобразование телефонных номеров клиентов перед отправкой запросов в Битрикс24.
Примеры в статье Изменение номера телефона перед отправкой данных в CRM.
Вход:
{
"phone": "<номер>",
"call_full": {<Полный набор данных о звонке>},
"call_stage": "<Стадия звонка. Для данной кастомизации один из вариантов:
call_started - начало звонка;
conversation_requested - запрос разговора;
conversation_accepted - ответ;
conversation_ended - завершение разговора;
call_ended - завершение звонка;
forward <id> - автораспределение звонка>"
}Полный набор данных о звонке описан в статье Данные о звонке (call_full) в кастомизациях.
Вернуть:
{
"data": {
"phone": “<Кастомизированный номер>”
},
"state": "success"
}5) process_final_params
Кастомизация параметров завершения регистрации звонка.
Примеры: Разные ответственные за пропущенные за разные транки.
Вход:
{
"ADD_TO_CHAT": <[0/1] Добавить ли сообщение о звонке в бизнес чат.
По умолчанию 1>,
"CALL_ID": "<ID звонка в Битрикс24. Не рекомендуется изменять!>",
"DURATION": <Длительность звонка в секундах>,
"STATUS_CODE": "<Статус звонка в Битрикс24>",
"USER_ID": <ID пользователя Битрикс24, ответственного за разговор>,
"call_full": {<Полный набор данных о звонке>},
<Остальные поля временно сохранены для обратной совместимости: call_registration, entity, entity_type, entity_id, entity_new>
}Статусы звонка в Битрикс24 описаны в статье Детальные статусы звонка.
Полный набор данных о звонке описан в статье Данные о звонке (call_full) в кастомизациях.
Часть полей в корне входных данных кастомизации считаются устаревшими и будут убраны в будущих версиях коннектора.
Вместо них рекомендуется использовать актуальные поля внутри объекта call_full:
call_registration→call_full.registrationentity→call_full.entityentity_type→call_full.entity.typeentity_id→call_full.entity.identity_new→call_full.entity.is_new
Вернуть:
{
"data": {
"ADD_TO_CHAT": <[0/1] Добавить ли сообщение о звонке в бизнес чат>,
"CALL_ID": "<ID звонка в Битрикс24. Не рекомендуется изменять!>",
"DURATION": <Длительность звонка в секундах>,
"STATUS_CODE": "<Статус звонка>",
"USER_ID": <ID пользователя Битрикс24, ответственного за разговор>
},
"state": "success"
}Подробное описание параметров завершения звонка в документации REST API Битрикс24.
Запрос завершения регистрации звонка можно отменить, вернув пустой объект data.
6) process_originate_params
Изменение параметров при инициализации звонка из Битрикс24.
Подробное описание с примерами в статье Изменение параметров при click-to-call.
7) process_record_file_path
Преобразование пути до файла записи разговора.
Подробное описание с примерами в статье Кастомизация имени файла аудиозаписи.
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 - завершение звонка>"
}Полный набор данных о звонке описан в статье Данные о звонке (call_full) в кастомизациях.
Показ карточки звонка вынесен в отдельный запрос, и кастомизируется отдельной кастомизацией 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.
Запрос регистрации можно отменить, вернув пустой объект data.
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": {<Полный набор данных о звонке>}
}Полный набор данных о звонке описан в статье Данные о звонке (call_full) в кастомизациях.
Вернуть:
{
"data": {
"fields": {
"<Название поля задачи в Битрикс>": "<Значение этого поля>"
...
}
},
"state": "success"
}Подробное описание полей задачи в документации REST API Битрикс24.
Запрос создания задачи можно отменить, вернув пустой объект data.
10) process_user_phone
Изменение номера пользователя перед поиском пользователя Битрикс24.
Пример: Несколько внутренних номеров у сотрудника.
Вход:
{
"phone": "<номер>",
"call_full": {<Полный набор данных о звонке>},
"call_stage": "<Стадия звонка. Для данной кастомизации один из вариантов:
conversation_requested - запрос разговора;
conversation_accepted - ответ;
conversation_ended - завершение разговора;
call_ended - завершение звонка;
forward <id> - автораспределение звонка>"
}Полный набор данных о звонке описан в статье Данные о звонке (call_full) в кастомизациях.
Вернуть:
{
"data": {
"phone": "<кастомизированный_номер>"
},
"state": "success"
}11) customize_autodistribution
Вход:
{
"number": "<номер пользователя, на которого распределять звонок>",
"name": "<имя пользователя, на которого распределять звонок>",
"from": "<номер, с которого пришёл звонок>",
"trunk": "<номер транка>",
"user": {
"id": <ID пользователя числом>,
"phones": ["<список номеров пользователя>"],
"name": "<Полное имя пользователя>",
"email": "<email пользователя>",
"position": "<должность пользователя>"
},
"entity": {
"type": "<Тип сущности текстом, например lead, contact>",
"id": <ID сущности числом>,
"name": "<Имя сущности>",
"responsible_id": <ID ответственного пользователя числом>
},
"request_data": {<Параметры запроса>},
"call_full": {<Полный набор данных о звонке>},
"error": "<текст ошибки>"
}Вернуть:
{
"data": {
"number": "<Номер пользователя, на которого распределять звонок>",
"name": "<Имя пользователя, на которого распределять звонок, лимит 20 символов>"
},
"state": "success"
}name - текст, который появится в CallerID и будет отображен в телефоне (или софтфоне) оператора.
Должен быть не более 20 символов (ограничение Asterisk)!
12) post_registration
Данная кастомизация дает возможность выполнить какие-либо действия после регистрации звонка.
Может быть вызвана в разные моменты в зависимости от типа звонка:
Для звонков кликом (click-to-call, c2c) кастомизация будет вызвана в начале обработки стадии Запрос разговора (Conversation requested).
Пропущенные звонки на IVR регистрируются и завершаются на стадии Завершение звонка (Call ended).
Для всех остальных звонков кастомизация будет вызвана после выполнения запроса регистрации звонка в Битрикс24 на стадии Запрос разговора (Conversation requested).
Вход:
{
"call_full": {<Полный набор данных о звонке>},
"call_stage": "<Стадия звонка. Для данной кастомизации один из вариантов:
conversation_requested - запрос разговора;
call_ended - завершение звонка>",
}Полный набор данных о звонке описан в статье Данные о звонке (call_full) в кастомизациях.
Вернуть:
Нужно вернуть только 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 - завершение звонка>"
}Полный набор данных о звонке описан в статье Данные о звонке (call_full) в кастомизациях.
Вернуть:
{
"data": {
"CALL_ID": <ID зарегистрированного звонка в Битрикс24>,
"USER_ID": <ID пользователя>
},
"state": "success"
}Подробное описание параметров показа карточки в документации REST API Битрикс24.
Запрос показа карточки звонка можно отменить, вернув пустой объект data.
14) customize_attach_record_url
Кастомизация прикрепления ссылки на запись звонка. Запускается только если настроено прикрепление ссылки на запись вместо файла записи звонка.
По умолчанию в описание дела записывается 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": {<Полный набор данных о звонке>},
"record_url": "<URL записи звонка>",
"old_description": "<Описание дела до кастомизации>"
}Полный набор данных о звонке описан в статье Данные о звонке (call_full) в кастомизациях.
В объекте raw присутствуют только поля с непустым/ненулевым значением.
Вернуть:
{
"data": {
"<Название поля дела в Битрикс>": "<Значение этого поля>",
...
},
"state": "success"
}Подробное описание полей дела в документации REST API Битрикс24.
Запрос обновления дела не будет выполнен, если вернуть пустой объект data.
15) process_originate_response
Кастомизация результата Click-to-Call. Запускается при получении события OriginateResponse от Asterisk после выполнения запроса Click-to-Call. Позволяет выполнить дополнительные действия при успехе/ошибке Originate.
Вход:
{
"originate_params": {<Параметры запроса Click-to-Call>},
"originate_response": {<Поля события AMI OriginateResponse>},
"request_id": <ID запроса Click-to-Call>,
"call_full": {<Полный набор данных о звонке>}
}Полный набор данных о звонке описан в статье Данные о звонке (call_full) в кастомизациях.
Поле call_full может быть пустым, если на момент получения события OriginateResponse звонок отсутствует в кэше коннектора.
Вернуть:
{
"state": "success"
}16) customize_recording_query
Кастомизация запроса поиска записи звонка. Запускается перед поиском записи звонка в таблице CDR. Позволяет модифицировать запрос поиска.
Вход:
{
"query": "<SQL-запрос поиска записи звонка>",
"callID": "<ID звонка>",
"from_variants": ["<Список вариантов номера источника звонка>"],
"to_variants": ["<Список вариантов номера получателя звонка>"],
"call_full": {<Полный набор данных о звонке>}
}Полный набор данных о звонке описан в статье Данные о звонке (call_full) в кастомизациях.
Запрос поиска записи звонка можно отменить, вернув пустой объект query.
Вернуть:
{
"data": {
"query": "<SQL-запрос поиска записи звонка>"
},
"state": "success"
}17) customize_record_conversion
Кастомизация параметров конвертации записи. Запускается перед конвертацией записи в mp3. Позволяет изменить настройки конвертации записи для данного звонка.
Вход:
{
"IN": "<Путь к исходному файлу записи>",
"OUT": "<Путь к конечному файлу записи>",
"recording_converter_path": "<Путь программы для конвертации записи>",
"recording_converter_args": "<Аргументы запуска программы конвертации записи>",
"recording_converter_timeout_msec": <Таймаут выполнения конвертации записи в миллисекундах>,
"overwrite_cdr_recordingfile": <true - обновлять путь к записи в таблице CDR; false - не обновлять>,
"initial_cdr_recordingfile": "<Исходный путь к записи в таблице CDR>",
"updated_cdr_recordingfile": "<Конечный путь к записи в таблице CDR>",
"delete_original_recordings": <true - удалить исходный файл записи после конвертации; false - не удалять>,
"call_full": {<Полный набор данных о звонке>}
}Полный набор данных о звонке описан в статье Данные о звонке (call_full) в кастомизациях.
Поле call_full может быть пустым, если на момент выполнения конвертации записи звонок отсутствует в кэше коннектора.
Выполнение конвертации записи можно отменить, вернув пустой объект data.
Входные значения соответствуют настройкам конвертации записи.
Вернуть:
{
"data": {
"IN": "<Путь к исходному файлу записи>",
"OUT": "<Путь к конечному файлу записи>",
"recording_converter_path": "<Путь программы для конвертации записи>",
"recording_converter_args": "<Аргументы запуска программы конвертации записи>",
"recording_converter_timeout_msec": <Таймаут выполнения конвертации записи в миллисекундах>,
"overwrite_cdr_recordingfile": <true - обновлять путь к записи в таблице CDR; false - не обновлять>,
"initial_cdr_recordingfile": "<Исходный путь к записи в таблице CDR>",
"updated_cdr_recordingfile": "<Конечный путь к записи в таблице CDR>",
"delete_original_recordings": <true - удалить исходный файл записи после конвертации; false - не удалять>
},
"state": "success"
}Поля initial_cdr_recordingfile и updated_cdr_recordingfile используются для формирования SQL-запроса обновления записи в таблице CDR следующего вида:
UPDATE CDR SET CDR.recordingfile = '<updated_cdr_recordingfile>' WHERE CDR.recordingfile = '<initial_cdr_recordingfile>'
18) process_rejected_call_event
Кастомизация игнорируемых событий звонка. Запускается когда событие звонка намеренно не обрабатывается стандартной логикой, например при звонке между сотрудниками или звонке неопределенного типа.
Вход:
{
"call_full": {<Полный набор данных о звонке>},
"call_stage": "<Стадия звонка. Для данной кастомизации один из вариантов:
"call_started" - начало звонка;
"conversation_requested" - запрос разговора;
"conversation_accepted" - ответ;
"conversation_ended" - завершение разговора;
"call_ended" - завершение звонка>",
"rejection_reason": "<Причина отклонения события звонка>"
}Возможные значения поля rejection_reason:
"no active conversation"- событие разговора без указания ID разговора;"local conversation"- событие разговора между сотрудниками;"unknown conversation type"- событие разговора неопределенного типа;"self conversation type"- событие разговора с совпадающими номерамиfromиto;"conversation processed earlier"- событие разговора уже обработано ранее;"invalid event name"- неизвестное событие звонка;"local call"- звонок между сотрудниками;"unknown call type"- звонок неопределенного типа;"self call type"- звонок с совпадающими номерамиfromиto;"call processed earlier"- звонок уже обработан ранее.
Вернуть:
{
"state": "success"
}Last updated
Was this helpful?