> For the complete documentation index, see [llms.txt](https://itgro-aly.gitbook.io/test-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://itgro-aly.gitbook.io/test-docs/custom_bx_history.md).

# custom\_bx\_history

{% hint style="info" %}
Дополнительные кастомизации описаны в разделе [Полезные кастомизации (любая CRM)](file:///1659967/custom_common/).
{% endhint %}

## Обновление кастомизаций, начиная с версии 3.0.0

Звонки регистрируются через API телефонии Битрикс24, что позволяет [использовать сквозную аналитику.](file:///1659967/settings/additional/end-to-end-analytics.md)

По сравнению [кастомизациями в версиях 2.15.0–2.15.6](broken://pages/ec610be6528be8d8992f29703921388fd574de58):

* Выделена кастомизация `need_registration`, в которой можно реализовать черные и белые списки.
* Разделена кастомизация `process_phone_number` на два метода:
  * `process_user_phone` – кастомизация внутреннего номера пользователя;
  * `process_client_phone` – кастомизация номера клиента.
* Кастомизация `get_updated_entity_fields` переименована в `customize_entity`.
* Кастомизация `get_updated_activity_fields` переименована в `customize_activity`.

{% hint style="warning" %}
Начиная с версии [3.13.0](file:///1659967/changelog-bx.md#id-3.13.0) из входных данных ряда кастомизаций были **удалены устаревшие поля**, дублирующие информацию из `call_full`: `call` и `conversation`.

Если ваши кастомизации всё ещё обращаются к полям `call` или `conversation` в корне входного JSON-объекта, обновите код, используя соответствующие данные внутри объекта `call_full`.
{% endhint %}

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

(Схема для версий начиная с [3.10.0](file:///1659967/changelog-bx.md#3.10.0))

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

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

| №  | <p>Файл кастомизации<br>(по алфавиту)</p>                                                                                     | Описание                                                                                                                                                   |
| -- | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1  | [customize\_activity.php](broken://pages/d256efd9f5986eb537a9b847d0e4c7a9dee9050e#1-customize_activity)                       | Обновление полей дела (в конце звонка).                                                                                                                    |
| 2  | [customize\_entity.php](broken://pages/d256efd9f5986eb537a9b847d0e4c7a9dee9050e#2-customize_entity)                           | Обновление полей сущности (в конце звонка).                                                                                                                |
| 3  | [need\_registration.php](broken://pages/d256efd9f5986eb537a9b847d0e4c7a9dee9050e#3-need_registration)                         | <p>Нужна ли регистрация звонка?<br>Можно сделать черные/белые списки по внутреннему номеру/транку.</p>                                                     |
| 4  | [process\_client\_phone.php](broken://pages/d256efd9f5986eb537a9b847d0e4c7a9dee9050e#4-process_client_phone)                  | <p>Изменение номера телефона перед регистрацией в CRM:<br>Можно сменить формат телефонного номера (+7, 8...).</p>                                          |
| 5  | [process\_final\_params.php](broken://pages/d256efd9f5986eb537a9b847d0e4c7a9dee9050e#5-process_final_params)                  | Изменение данных завершения звонка.                                                                                                                        |
| 6  | [process\_originate\_params.php](broken://pages/d256efd9f5986eb537a9b847d0e4c7a9dee9050e#6-process_originate_params)          | <p>Изменение параметров при инициализации звонка из CRM.<br>Можно позвонить через другой транк, через другой контекст, сменить формат номера и прочее.</p> |
| 7  | [process\_record\_file\_path.php](broken://pages/d256efd9f5986eb537a9b847d0e4c7a9dee9050e#7-process_record_file_path)         | Кастомизация пути до файла записи разговора.                                                                                                               |
| 8  | [process\_registration\_params.php](broken://pages/d256efd9f5986eb537a9b847d0e4c7a9dee9050e#8-process_registration_params)    | Изменение параметров регистрации звонка.                                                                                                                   |
| 9  | [process\_task\_creation\_params.php](broken://pages/d256efd9f5986eb537a9b847d0e4c7a9dee9050e#9-process_task_creation_params) | Кастомизация создания задач по пропущенным звонкам.                                                                                                        |
| 10 | [process\_user\_phone.php](broken://pages/d256efd9f5986eb537a9b847d0e4c7a9dee9050e#10-process_user_phone)                     | Изменение номера пользователя перед поиском пользователя в Б24.                                                                                            |
| 11 | [customize\_autodistribution.php](broken://pages/d256efd9f5986eb537a9b847d0e4c7a9dee9050e#11-customize_autodistribution)      | Изменение внутреннего номера при автораспределении входящего звонка.                                                                                       |
| 12 | [post\_registration.php](broken://pages/d256efd9f5986eb537a9b847d0e4c7a9dee9050e#12-post_registration)                        | Действие после регистрации звонка.                                                                                                                         |
| 13 | [customize\_show\_call\_card.php](broken://pages/d256efd9f5986eb537a9b847d0e4c7a9dee9050e#13-customize_show_call_card)        | Изменение параметров отображения карточки звонка.                                                                                                          |
| 14 | [customize\_attach\_record\_url.php](broken://pages/d256efd9f5986eb537a9b847d0e4c7a9dee9050e#14-customize_attach_record_url)  | Изменение параметров прикрепления записи.                                                                                                                  |
| 15 | [process\_originate\_response.php](broken://pages/d256efd9f5986eb537a9b847d0e4c7a9dee9050e#15-process_originate_response)     | При получении результата Click-to-Call (событие OriginateResponse) от Asterisk. Позволяет выполнить дополнительные действия при успехе/ошибке Originate.   |
| 16 | [customize\_recording\_query.php](broken://pages/d256efd9f5986eb537a9b847d0e4c7a9dee9050e#16-customize_recording_query)       | Изменение запроса поиска записи звонка.                                                                                                                    |
| 17 | [customize\_record\_conversion.php](broken://pages/d256efd9f5986eb537a9b847d0e4c7a9dee9050e#17-customize_record_conversion)   | Кастомизация параметров конвертации записи звонка.                                                                                                         |
| 18 | [process\_rejected\_call\_event.php](broken://pages/d256efd9f5986eb537a9b847d0e4c7a9dee9050e#18-process_rejected_call_event)  | Кастомизация игнорируемых событий звонка.                                                                                                                  |

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

### 1) customize\_activity

{% hint style="info" %}
[3.10.0](file:///1659967/changelog-bx.md#3.10.0) – добавлен полный набор данных о звонке (`call_full`) и вынесена кастомизация [customize\_attach\_record\_url](broken://pages/d256efd9f5986eb537a9b847d0e4c7a9dee9050e#14-customize_attach_record_url) для прикрепления ссылки на запись звонка.

[3.13.0](file:///1659967/changelog-bx.md#id-3.13.0) – удалено устаревшее поле `conversation` из корня входных данных, используйте `call_full.conversation`.
{% endhint %}

Обновление полей дела в конце звонка.\
Если настроено прикрепление ссылки на запись вместо самой записи, ссылка добавляется в описание дела.

**Примеры:**

* [Обновление полей дела](broken://pages/d7a21f573d2a34f3bb10673862aec777f45ea968)

**Вход:**

```json
{
  "activity": {
    "id":             "<ID дела>",
    "is_new":         <Всегда false>,
    "name":           "<Название дела (из поля SUBJECT)>",
    "phones":         [<Всегда пустой массив>],
    "raw":            {Поля дела как в Битрикс24},
    "responsible":    {<Данные ответственного пользователя>},
    "responsible_id": "<ID ответственного пользователя>",
    "type":           "activity"
  },

  "call_full": {<Полный набор данных о звонке>}
}
```

Набор данных о разговоре (conversation) описан в статье [Параметры звонка (call) и разговора (conversation) в кастомизациях](file:///1659967/custom_common/call-conversation-parameters.md#parametry-razgovora-conversation).\
В объекте `raw` присутствуют только поля с непустым/ненулевым значением.

**Вернуть:**

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

[Документация полей дела в REST API Битрикс24](https://dev.1c-bitrix.ru/rest_help/crm/rest_activity/crm_activity_fields.php)

### 2) customize\_entity

{% hint style="info" %}
[3.10.0](file:///1659967/changelog-bx.md#3.10.0) – добавлен полный набор данных о звонке (`call_full`) и обновление полей сущности стало выполняться вне зависимости от того, была ли сущность создана на этом звонке, или ранее.

[3.13.0](file:///1659967/changelog-bx.md#id-3.13.0) – удалено устаревшее поле `call` из корня входных данных (остальные временно сохраняются для обратной совместимости).
{% endhint %}

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

**Примеры:**

* [Обновление полей сущности](broken://pages/63e20aec5440b759c4185ce1878638caefcbbe59)

**Вход:**

```json
{
  "call_registration": {<Набор данных о регистрации звонка (сохранён для обратной совместимости)>},
  "entity":            {<Данные сущности>},
  "entity_type":       "<Тип сущности текстом, например lead, contact>",
  "entity_id":         "<ID сущности>",
  "entity_new":        <true/false создана ли сущность на этом звонке>,

  "call_full": {<Полный набор данных о звонке>}
}
```

Набор данных о звонке описан в статье [Параметры звонка (call) и разговора (conversation) в кастомизациях](file:///1659967/custom_common/call-conversation-parameters.md#parametry-zvonka-call).\
Формат данных сущности в поле `entity` описан в соответствующем разделе статьи [Данные о звонке (call\_full) в кастомизациях](file:///1659967/custom_common/dannye-o-zvonke-call_full-v-kastomizaciyakh.md#dannye-sushnosti-entity).

**Вернуть:**

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

[Документация полей лида](https://dev.1c-bitrix.ru/rest_help/crm/leads/crm_lead_fields.php)\
[Документация полей контакта](https://dev.1c-bitrix.ru/rest_help/crm/contacts/crm_contact_fields.php)

### 3) need\_registration

{% hint style="info" %}
[3.0.7](file:///1659967/changelog-bx.md#3.0.7) – добавлена возможность настройки чёрного/белого списка для внутренних номеров [через веб-интерфейс модуля](file:///1659967/custom_common/black-white-list.md#nastroika-cherez-interfeis-modulya).

[3.10.0](file:///1659967/changelog-bx.md#3.10.0) – добавлены параметры `call_stage` и `call_full`.
{% endhint %}

Определяет, нужно ли регистрировать конкретный звонок. Можно реализовать чёрные/белые списки по внутреннему номеру, транку или более сложным условиям.

**Примеры:**

* [Черный/белый список для транков](file:///1659967/custom_common/black-white-list.md#chernyi-belyi-spisok-dlya-trankov)

**Вход:**

```json
{
  "call_full":  {<Полный набор данных о звонке>},
  "call_stage": "<Стадия звонка. Для данной кастомизации один из вариантов:
     conversation_requested - запрос разговора;
     conversation_accepted  - ответ;
     conversation_ended     - завершение разговора;
     call_ended             - завершение звонка>"
}
```

Набор данных о звонке и разговорах описан в статье [Параметры звонка (call) и разговора (conversation) в кастомизациях](file:///1659967/custom_common/call-conversation-parameters.md).

**Вернуть:**

```json
{
  "data": {
    "result": <true – регистрируем; false – игнорируем>
  },
  "state": "success"
}
```

### 4) process\_client\_phone

{% hint style="info" %}
[3.0.0](file:///1659967/changelog-bx.md#3.0.0) – кастомизация номера разделена на две: `process_user_phone` (внутренний номер) и `process_client_phone` (номер клиента).

[3.7.0](file:///1659967/changelog-bx.md#3.7.0) – добавлена [автозамена номеров](file:///1659967/for-admins/autoreplacement.md), запускается ДО выполнения кастомизации.

[3.10.0](file:///1659967/changelog-bx.md#3.10.0) – добавлены параметры `call_stage` и `call_full`.
{% endhint %}

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

**Примеры:**

* [Изменение номера телефона перед отправкой данных в CRM](file:///1659967/custom_common/client-phone-number.md)

**Вход:**

```json
{
  "phone": "<номер>",

  "call_full":  {<Полный набор данных о звонке>},
  "call_stage": "<Стадия звонка. Для данной кастомизации один из вариантов:
     call_started           - начало звонка;
     conversation_requested - запрос разговора;
     conversation_accepted  - ответ;
     conversation_ended     - завершение разговора;
     call_ended             - завершение звонка;
     forward <id>           - автораспределение звонка>"
}
```

Описание блока `call_full` см. в статье [Данные о звонке (call\_full) в кастомизациях](file:///1659967/custom_common/dannye-o-zvonke-call_full-v-kastomizaciyakh.md).

**Вернуть:**

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

### 5) process\_final\_params

{% hint style="info" %}
[2.15.0](file:///1659967/changelog-bx.md#2.15.0) – чёрные/белые списки вынесены в кастомизацию [need\_registration](broken://pages/d256efd9f5986eb537a9b847d0e4c7a9dee9050e#3-need_registration).

[3.0.7](file:///1659967/changelog-bx.md#3.0.7) – настройка чёрного/белого списка для внутренних номеров доступна через [веб-интерфейс модуля](file:///1659967/custom_common/black-white-list.md#nastroika-cherez-interfeis-modulya).

[3.10.0](file:///1659967/changelog-bx.md#3.10.0) – добавлен полный набор данных о звонке (`call_full`).

[3.13.0](file:///1659967/changelog-bx.md#id-3.13.0) – удалено устаревшее поле `call` из корня входных данных.
{% endhint %}

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

**Примеры:**

* [Разные ответственные за пропущенные за разные транки](broken://pages/b8c58628476e1e30180b4dce671f01dcbc7136e7)

**Вход:**

```json
{
  "params": {
    "ADD_TO_CHAT":   <[0/1] Добавить ли сообщение о звонке в бизнес чат. По умолчанию 1>,
    "CALL_ID":       "<ID звонка в Битрикс24. Не рекомендуется изменять!>",
    "DURATION":      <Длительность звонка в секундах>,
    "STATUS_CODE":   "<Статус звонка в Битрикс24>",
    "USER_ID":       <ID пользователя Битрикс24, ответственного за разговор>,

    "entity_type":       "<Тип сущности текстом, например lead, contact (сохранён для обратной совместимости)>",
    "entity_id":         "<ID сущности, в которую будет записан звонок (сохранён для обратной совместимости)>",
    "entity_new":        <true/false создана ли сущность на этом звонке (сохранено для обратной совместимости)>,
    "call_full":         {<Полный набор данных о звонке>},
    "call_registration": {<Набор данных о регистрации звонка (сохранён для обратной совместимости)>}
  }
}
```

Статусы звонка в Битрикс24 описаны в [статье Детальные статусы звонка](file:///1659967/faq/detalnye-statusy-zvonka.md#bitrix24).\
Описание блока `call_full` см. в статье [Данные о звонке (call\_full) в кастомизациях](file:///1659967/custom_common/dannye-o-zvonke-call_full-v-kastomizaciyakh.md).

**Вернуть:**

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

[Документация параметров завершения звонка в REST API Битрикс24](https://dev.1c-bitrix.ru/rest_help/scope_telephony/telephony/telephony_externalcall_finish.php)

### 6) process\_originate\_params

Изменение параметров при инициализации звонка из Битрикс24 (Click-to-Call).

Подробное описание с примерами в статье [Изменение параметров при click-to-call](file:///1659967/custom_common/c2c.md).

### 7) process\_record\_file\_path

{% hint style="info" %}
[3.10.19](file:///1659967/changelog-bx.md#id-3.10.19) – таймаут выполнения кастомизации стал настраиваемым (ранее был жёстко зафиксирован в 10 секунд).

[3.13.0](file:///1659967/changelog-bx.md#id-3.13.0) – конвертация записей вынесена в основную логику коннектора, кастомизация служит только для изменения пути до файла записи.
{% endhint %}

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

**Примеры:**

* [Кастомизация имени файла аудиозаписи](file:///1659967/custom_common/filepath.md)

### 8) process\_registration\_params

{% hint style="info" %}
[3.10.0](file:///1659967/changelog-bx.md#3.10.0) – добавлен полный набор данных о звонке (`call_full`), показ карточки звонка вынесен в отдельную кастомизацию `customize_show_call_card`.

[3.13.0](file:///1659967/changelog-bx.md#id-3.13.0) – удалены устаревшие поля `call`, `conversation` из корня входных данных.
{% endhint %}

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

**Примеры:**

* [Добавление кода города в зависимости от города оператора](broken://pages/ee3d2554458db56d5f55c484e54459119d8471ed)
* [Изменение первого ответственного за лид/контакт](broken://pages/a98fcb78a8aca13590c5956a33ae43994daad0f3)
* [Создавать лид для каждого входящего звонка](broken://pages/f6f5feb1f7079ddbeb992c4577d2b243703d94bc)

**Вход:**

```json
{
  "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.\
Описание блока `call_full` см. в статье [Данные о звонке (call\_full) в кастомизациях](file:///1659967/custom_common/dannye-o-zvonke-call_full-v-kastomizaciyakh.md).

**Вернуть:**

```json
{
  "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](https://dev.1c-bitrix.ru/rest_help/scope_telephony/telephony/telephony_externalcall_register.php)

### 9) process\_task\_creation\_params

{% hint style="info" %}
[2.15.0](file:///1659967/changelog-bx.md#2.15.0) – добавлен блок данных о разговоре (`conversation`).

[3.4.0](file:///1659967/changelog-bx.md#3.4.0) – возможность настройки задач через [веб-интерфейс модуля](file:///1659967/settings/additional/parametry-sozdaniya-zadach.md).

[3.10.0](file:///1659967/changelog-bx.md#3.10.0) – добавлен полный набор данных о звонке (`call_full`).

[3.13.0](file:///1659967/changelog-bx.md#id-3.13.0) – удалено устаревшее поле `conversation` из корня входных данных.
{% endhint %}

Кастомизация параметров создания задачи (при пропущенном входящем звонке или неотвеченном исходящем).\
Запускается только если создание задач включено в настройках коннектора.

**Примеры:**

* [Кастомизация задач по пропущенным звонкам](broken://pages/7b1ca78bc99f1702f24c5174a16959a57f00fea0)

**Вход:**

```json
{
  "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` см. в статье [Данные о звонке (call\_full) в кастомизациях](file:///1659967/custom_common/dannye-o-zvonke-call_full-v-kastomizaciyakh.md).

**Вернуть:**

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

[Документация полей задачи в REST API Битрикс24](https://dev.1c-bitrix.ru/rest_help/tasks/fields.php)

### 10) process\_user\_phone

{% hint style="info" %}
[3.0.0](file:///1659967/changelog-bx.md#3.0.0) – кастомизация номера разделена на две: `process_user_phone` (внутренний номер) и `process_client_phone` (номер клиента).

[3.7.0](file:///1659967/changelog-bx.md#3.7.0) – добавлена [автозамена номеров](file:///1659967/for-admins/autoreplacement.md), запускается ДО выполнения кастомизации.

[3.10.0](file:///1659967/changelog-bx.md#3.10.0) – добавлены параметры `call_stage` и `call_full`.
{% endhint %}

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

**Примеры:**

* [Несколько внутренних номеров у сотрудника](broken://pages/b8215acd6fe17743deed5a7963b22f48a92d1bf0)

**Вход:**

```json
{
  "phone": "<номер>",

  "call_full":  {<Полный набор данных о звонке>},
  "call_stage": "<Стадия звонка. Для данной кастомизации один из вариантов:
    conversation_requested - запрос разговора;
    conversation_accepted  - ответ;
    conversation_ended     - завершение разговора;
    call_ended             - завершение звонка;
    forward <id>           - автораспределение звонка>"
}
```

Описание блока `call_full` см. в статье [Данные о звонке (call\_full) в кастомизациях](file:///1659967/custom_common/dannye-o-zvonke-call_full-v-kastomizaciyakh.md).

**Вернуть:**

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

### 11) customize\_autodistribution

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

**Вход:**

```json
{
  "number": "<номер пользователя на которого распределять звонок>",
  "name":   "<имя пользователя на которого распределять звонок>",

  "from":   "<номер с которого пришёл звонок>",
  "trunk":  "<номер транка>",
  "user":   {
    "id":       <ID пользователя числом>,
    "phones":   ["<список номеров пользователя>"],
    "name":     "<Полное имя пользователя>",
    "email":    "<email пользователя>",
    "position": "<должность пользователя>"
  },
  "entity": {
    "type":           "<Тип сущности текстом, например lead, contact>",
    "id":             <ID сущности числом>,
    "name":           "<Имя сущности>",
    "responsible_id": <ID ответственного пользователя числом>
  },
  "error": "<текст ошибки>",
  "request_data": {<Параметры запроса>},
  "call_full":    {<Полный набор данных о звонке>}
}
```

**Вернуть:**

```json
{
  "data": {
    "number": "<Номер пользователя, на которого распределять звонок>",
    "name":   "<Имя пользователя, на которого распределять звонок, лимит 20 символов>"
  },
  "state": "success"
}
```

**Примечания:**

* `name` – текст который появится в CallerID и будет отображен в телефоне (или софтфоне) оператора. **Должен быть не более 20 символов (ограничение Asterisk)!**
* Поля `from`, `trunk`, `user`, `entity` и `error` – только для чтения и присутствуют только когда не пустые. Они будут автоматически удалены, даже если вернуть их в объекте `data`.

### 12) post\_registration

{% hint style="info" %}
[3.10.0](file:///1659967/changelog-bx.md#3.10.0) – кастомизация добавлена.
{% endhint %}

Действие после регистрации звонка. Может быть вызвана в разные моменты в зависимости от типа звонка:

* Для звонков кликом (click-to-call, c2c) – в начале обработки стадии Запрос разговора (Conversation requested)
* Пропущенные звонки на IVR – на стадии Завершение звонка (Call ended)
* Для всех остальных звонков – после выполнения запроса регистрации звонка в Битрикс24 на стадии Запрос разговора (Conversation requested)

**Вход:**

```json
{
  "call_full":  {<Полный набор данных о звонке>},
  "call_stage": "<Стадия звонка. Для данной кастомизации один из вариантов:
    conversation_requested - запрос разговора;
    call_ended             - завершение звонка>",
}
```

Описание блока `call_full` см. в статье [Данные о звонке (call\_full) в кастомизациях](file:///1659967/custom_common/dannye-o-zvonke-call_full-v-kastomizaciyakh.md).

**Вернуть:**

```json
{
  "state": "success"
}
```

### 13) customize\_show\_call\_card

{% hint style="info" %}
[3.10.0](file:///1659967/changelog-bx.md#3.10.0) – кастомизация добавлена.
{% endhint %}

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

**Вход:**

```json
{
  "CALL_ID": <ID зарегистрированного звонка в Битрикс24>,
  "USER_ID": <ID пользователя>,
  
  "call_full":  {<Полный набор данных о звонке>},
  "call_stage": "<Стадия звонка. Для данной кастомизации один из вариантов:
    conversation_requested - запрос разговора;
    conversation_accepted  - ответ;
    conversation_ended     - завершение разговора;
    call_ended             - завершение звонка>"
 }
```

Описание блока `call_full` см. в статье [Данные о звонке (call\_full) в кастомизациях](file:///1659967/custom_common/dannye-o-zvonke-call_full-v-kastomizaciyakh.md).

**Вернуть:**

```json
{
  "data": { 
    "CALL_ID": <ID зарегистрированного звонка в Битрикс24>,
    "USER_ID": <ID пользователя>
  },
  "state": "success"
}
```

[Документация параметров показа карточки в REST API Битрикс24](https://dev.1c-bitrix.ru/rest_help/scope_telephony/telephony/telephony_externalcall_show.php)

### 14) customize\_attach\_record\_url

{% hint style="info" %}
[3.10.0](file:///1659967/changelog-bx.md#3.10.0) – кастомизация добавлена.
{% endhint %}

Кастомизация прикрепления ссылки на запись звонка. Запускается только если настроено прикрепление ссылки на запись вместо файла записи звонка.

По умолчанию в описание дела записывается HTML-код аудиоплеера (тег `audio`) со ссылкой на запись звонка.

**Вход:**

```json
{
  "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` см. в статье [Данные о звонке (call\_full) в кастомизациях](file:///1659967/custom_common/dannye-o-zvonke-call_full-v-kastomizaciyakh.md).\
В объекте `raw` присутствуют только поля с непустым/ненулевым значением.

**Вернуть:**

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

[Документация полей дела в REST API Битрикс24](https://dev.1c-bitrix.ru/rest_help/crm/rest_activity/crm_activity_fields.php)

### 15) process\_originate\_response

{% hint style="info" %}
[3.13.0](file:///1659967/changelog-bx.md#id-3.13.0) – кастомизация добавлена.
{% endhint %}

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

**Вход:**

```json
{
  "originate_params":   {<Параметры запроса Click-to-Call>},
  "originate_response": {<Поля события AMI OriginateResponse>},
  "request_id":         <ID запроса Click-to-Call>,
  "call_full":          {<Полный набор данных о звонке>}
}
```

Описание блока `call_full` см. в статье [Данные о звонке (call\_full) в кастомизациях](file:///1659967/custom_common/dannye-o-zvonke-call_full-v-kastomizaciyakh.md).\
Поле `call_full` может быть пустым, если на момент получения события OriginateResponse звонок отсутствует в кэше коннектора.

**Вернуть:**

```json
{
  "state": "success"
}
```

### 16) customize\_recording\_query

{% hint style="info" %}
[3.13.0](file:///1659967/changelog-bx.md#id-3.13.0) – кастомизация добавлена.
{% endhint %}

Кастомизация запроса поиска записи звонка. Запускается перед поиском записи звонка в таблице CDR.

**Вход:**

```json
{
  "query": "<SQL-запрос поиска записи звонка>",

  "callID":        "<ID звонка>",
  "from_variants": ["<Список вариантов номера источника звонка>"],
  "to_variants":   ["<Список вариантов номера получателя звонка>"],

  "call_full": {<Полный набор данных о звонке>}
}
```

Описание блока `call_full` см. в статье [Данные о звонке (call\_full) в кастомизациях](file:///1659967/custom_common/dannye-o-zvonke-call_full-v-kastomizaciyakh.md).\
Запрос поиска записи звонка можно отменить, вернув пустой объект `query`.

**Вернуть:**

```json
{
  "data": {
    "query": "<SQL-запрос поиска записи звонка>"
  },
  "state": "success"
}
```

### 17) customize\_record\_conversion

{% hint style="info" %}
[3.13.0](file:///1659967/changelog-bx.md#id-3.13.0) – кастомизация добавлена.
{% endhint %}

Кастомизация параметров конвертации записи. Запускается перед конвертацией записи в mp3.

**Вход:**

```json
{
  "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) в кастомизациях](file:///1659967/custom_common/dannye-o-zvonke-call_full-v-kastomizaciyakh.md).\
Поле `call_full` может быть пустым, если на момент выполнения конвертации записи звонок отсутствует в кэше коннектора.\
Выполнение конвертации записи можно отменить, вернув пустой объект `data`.

Входные значения соответствуют [настройкам конвертации записи](file:///1659967/blog/mp3-conversion.md).

**Вернуть:**

```json
{
  "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

{% hint style="info" %}
[3.13.0](file:///1659967/changelog-bx.md#id-3.13.0) – кастомизация добавлена.
{% endhint %}

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

**Вход:**

```json
{
  "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"` - звонок уже обработан ранее.

**Вернуть:**

```json
{
  "state": "success"
}
```