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

Данная статья актуальна для версий коннектора 3.13.*

Для предыдущих версий можно воспользоваться "исторической" версией статьи: Полезные кастомизации itgrix_bx (Битрикс24) [С историей]

Дополнительные кастомизации описаны в разделе Полезные кастомизации (любая CRM).

Схема обработки звонка модулем интеграции Itgrix

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

Отмена запросов

Кастомизации, запускаемые непосредственно перед выполнением запросов к CRM, позволяют отменить отправку соответствующего запроса. Для этого нужно вернуть пустой объект data.

Пример данных для отмены запроса:

{
  "data": {},
  "state": "success"
}

Кроме значения {}, также допустимы варианты [] и null.

Отмена запроса отмечается в логе текстом "cancelled by customization" и не считается ошибкой, но отсутствие данных, которые ожидалось получить в ответе на запрос, может привести к ошибкам последующих шагов обработки звонка и должно быть учтено в остальных кастомизациях.

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

№

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

Описание

customize_activity.php

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

customize_entity.php

Обновление полей сущности (в конце звонка).

need_registration.php

Нужна ли регистрация звонка? Можно сделать черные/белые списки по внутреннему номеру/транку.

process_client_phone.php

Изменение номера телефона перед регистрацией в CRM: Можно сменить формат телефонного номера (+7, 8...).

process_final_params.php

Изменение данных завершения звонка.

process_originate_params.php

Изменение параметров при инициализации звонка из CRM. Можно позвонить через другой транк, через другой контекст, сменить формат номера и прочее.

process_record_file_path.php

Кастомизация пути до файла записи разговора.

process_registration_params.php

Изменение параметров регистрации звонка.

process_task_creation_params.php

Кастомизация создания задач по пропущенным звонкам.

process_user_phone.php

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

customize_autodistribution.php

Изменение внутреннего номера при автораспределении входящего звонка.

post_registration.php

Действие после регистрации звонка.

customize_show_call_card.php

Изменение параметров отображения карточки звонка.

customize_attach_record_url.php

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

process_originate_response.php

При получении результата Click-to-Call (событие OriginateResponse) от Asterisk. Позволяет выполнить дополнительные действия при успехе/ошибке Originate.

customize_recording_query.php

Изменение запроса поиска записи звонка.

customize_record_conversion.php

Кастомизация параметров конвертации записи звонка.

process_rejected_call_event.php

Кастомизация для игнорируемых событий звонка, которые намеренно не обрабатываются стандартной логикой.

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

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.registration
entity → call_full.entity
entity_type → call_full.entity.type
entity_id → call_full.entity.id
entity_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_registration → call_full.registration
entity → call_full.entity
entity_type → call_full.entity.type
entity_id → call_full.entity.id
entity_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

Преобразование пути до файла записи разговора.

Подробное описание с примерами в статье Кастомизация имени файла аудиозаписи.

В версиях Itgrix_bx ниже 3.13.0 эта кастомизация использовалась для конвертации файлов записей разговоров в формат mp3 перед отправкой в Битрикс24.

Начиная с версии 3.13.0, конвертация записей выполняется основной логикой коннектора, а кастомизация 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) в кастомизациях.

Номера внешних линий в Битрикс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"
}

Подробное описание параметров регистрации звонка в документации 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)!

Поля 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             - завершение звонка>",
}

Полный набор данных о звонке описан в статье Данные о звонке (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"
}

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"
}

PreviousПараметры звонка (call) и разговора (conversation) в кастомизациях NextПолезные кастомизации itgrix_bx (Битрикс24) [С историей]

Last updated 4 months ago

Was this helpful?