Полезные кастомизации 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.0.0)

“Сущность” – это контакт или лид. Запрос разговора – это начало звонка на внутреннем номере. В одном звонке может быть несколько разговоров (в случае перевода звонка).

Краткое описание кастомизаций

Файл кастомизации (по алфавиту)

Описание

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.

Входные и выходные параметры кастомизаций

1) customize_activity

Обновление полей дела в конце звонка.

Примеры использования: Обновление полей дела.

Вход:

{
"params": {<Набор данных о разговоре (conversation)>}
}

Набор данных о разговоре (conversation) описан в статье Параметры звонка (call) и разговора (conversation) в кастомизациях.

Вернуть:

{
"data": {
"<Название поля дела в Битрикс>": "<Значение этого поля>",
...
},
"state": "success"
}

Описание полей дела в API Битрикс24.

2) customize_entity

Обновление полей лида/контакта в конце входящего звонка работает только для сущностей, которые созданы в результате регистрации звонка модулем.

Примеры использования: Обновление полей сущности.

Вход:

{
"params": {<Набор данных о звонке (call)>}
}

Набор данных о звонке (call) описан в статье Параметры звонка (call) и разговора (conversation) в кастомизациях.

Вернуть:

{
"data": {
"<Название поля сущности в Битрикс>": "<Значение этого поля>",
...
},
"state": "success"
}

Описание полей лида в API Битрикс24. Описание полей контакта в API Битрикс24.

3) need_registration

Используется для реализации функционала чёрных/белых список по номерам, транкам и прочим сложным условиям.

Подробное описание с примерами в статье Черные и белые списки. Как настроить?

4) process_client_phone

Преобразование телефонных номеров клиентов.

Начиная с версии itgrix_bx 3.0.0 касмитозация номера разделена на две: process_user_phone – кастомизация внутреннего номера пользователя; process_client_phone – кастомизация номера клиента.

Подробное описание с примерами в статье Изменение номера телефона перед отправкой данных в CRM.

5) process_final_params

Начиная с версии 2.15.0 кастомизация всех черных/белых списков реализуется через need_registration.

Примеры: Разные ответственные за пропущенные за разные транки.

Вход:

{
"params": {
"ADD_TO_CHAT": <[0/1] Добавить ли сообщение о звонке в бизнес чат.
По умолчанию 1>,
"CALL_ID": "<Идентификатор звонка в Битрикс. Не рекомендуется изменять!>",
"DURATION": <Длительность в секундах>,
"STATUS_CODE": "<Статус звонка.
304 - пропущенный/неотвеченный, 200 - OK>",
"USER_ID": <Идентификатор пользователя Битрикс, ответственного за разговор>,
"call": {<Набор данных о звонке>},
"entity_type": "<Тип сущности текстом, например lead, contact>",
"entity_id": <ID сущности числом>,
"entity_new": <true/false создана ли сущность на этом звонке>
}
}

Набор данных о звонке (call) описан в статье Параметры звонка (call) и разговора (conversation) в кастомизациях.

Вернуть:

Полный список параметров в документации API Битрикс24.

{
"data": {
"ADD_TO_CHAT": <[0/1] Добавить ли сообщение о звонке в бизнес чат>,
"CALL_ID": "<Идентификатор звонка в Битрикс. Не рекомендуется изменять!>",
"DURATION": <Длительность в секундах>,
"STATUS_CODE": "<Статус звонка>",
"USER_ID": <Идентификатор пользователя Битрикс, ответственного за разговор>
},
"state": "success"
}

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": "<Транк из настроек модуля, на который пришел звонок>",
"PHONE_NUMBER": "<Номер для поиска сущности в битрикс>",
"SHOW": <[0/1] Показывать ли карточку звонка при регистрации>,
"TYPE": <Направление звонка: 1 - исходящий, 2 - входящий>,
"USER_ID": <Идентификатор пользователя>,
"conversation": {<Набор данных о разговоре>}
}
}

Набор данных о разговоре (conversation) описан в статье Параметры звонка (call) и разговора (conversation) в кастомизациях.

Вернуть:

Полный список параметров в документации API Битрикс24.

{
"data": {
"CALL_START_DATE": "<Дата-время начала звонка>",
"CRM_CREATE": <[0/1] Создавать или нет новый лид (если номер не найден в CRM)>,
"CRM_SOURCE": "<STATUS_ID источника из справочника источников>",
"LINE_NUMBER": "<Транк из настроек модуля, на который пришел звонок>",
"PHONE_NUMBER": "<Номер для поиска сущности в битрикс>",
"SHOW": <[0/1] Показывать ли карточку звонка при регистрации>,
"TYPE": <Направление звонка: 1 - исходящий, 2 - входящий>,
"USER_ID": <Идентификатор пользователя>
},
"state": "success"
}

9) process_task_creation_params

Событие возникает перед постановкой задачи (при пропущенном входящем звонке). Полное описание полей задачи в документации API Битрикс24.

Пример: Кастомизация задач по пропущенным звонкам (начиная с версии 3.4.0 это можно делать через веб-интерфейс настройки модуля).

Вход:

В версии 2.15.0 добавлен блок данных о разговоре (conversation).

{
"params": {
"fields": {
"CREATED_BY": <Идентификатор постановщика>,
"DEADLINE": "<Крайний срок исполнения>",
"RESPONSIBLE_ID": <Идентификатор сотрудника, ответственного за задачу>,
"TITLE": "<Заголовок задачи>",
"UF_CRM_TASK": ["<Идентификатор сущности в специальном формате:
<Тип сущности>_<ID>.
Типы сущности:
лид - L
контакт - C,
компания - CO,
дело - D.
Пример: L_11201 для лида с ID 11201 >"]
},
"conversation": {<Набор данных о разговоре>}
}
}

Набор данных о разговоре (conversation) описан в статье Параметры звонка (call) и разговора (conversation) в кастомизациях.

Вернуть:

{
"data": {
"fields": {
"<Название поля задачи в Битрикс>": "<Значение этого поля>"
...
}
},
"state": "success"
}

10) process_user_phone

Изменение номера пользователя перед поиском пользователя в Битрикс24.

Начиная с версии itgrix_bx 3.0.0 касмитозация номера разделена на две: process_user_phone – кастомизация внутреннего номера пользователя; process_client_phone – кастомизация номера клиента.

Пример: Пример обрезания номера и подстановки 8 в начале.

Вход:

{
"params": {
"phone":<номер>
}
}

Вернуть:

{
"data": {
"phone":<кастомизированный_номер>
},
"state": "success"
}