# Полезные кастомизации itgrix\_bx (Битрикс24) \[С историей]

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

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

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

По сравнению [кастомизациями в версиях 2.15.0–2.15.6](/custom_bx/custom-before-3.0.md):

* Выделена кастомизация `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](https://docs.itgrix.ru/custom_bx/pages/-M0SZwZn5pERjpAzqeP-#id-3.13.0) из входных данных ряда кастомизаций были **удалены устаревшие поля**, дублирующие информацию из `call_full`: `call` и `conversation`.

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

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

(Схема для версий начиная с [3.10.0](https://docs.itgrix.ru/custom_bx/pages/-M0SZwZn5pERjpAzqeP-#3.10.0))

<figure><img src="/files/0ptRy3JLsYzSg4pz8FBY" alt=""><figcaption><p>Кастомизации версий 3.10+</p></figcaption></figure>

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

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

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

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

### 1) customize\_activity

{% hint style="info" %}
[3.10.0](https://docs.itgrix.ru/custom_bx/pages/-M0SZwZn5pERjpAzqeP-#3.10.0) – добавлен полный набор данных о звонке (`call_full`) и вынесена кастомизация [customize\_attach\_record\_url](#14-customize_attach_record_url) для прикрепления ссылки на запись звонка.

[3.13.0](https://docs.itgrix.ru/custom_bx/pages/-M0SZwZn5pERjpAzqeP-#id-3.13.0) – удалено устаревшее поле `conversation` из корня входных данных, используйте `call_full.conversation`.
{% endhint %}

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

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

* [Обновление полей дела](/custom_bx/update-activity-fields.md)

**Вход:**

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

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

Набор данных о разговоре (conversation) описан в статье [Параметры звонка (call) и разговора (conversation) в кастомизациях](/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](https://docs.itgrix.ru/custom_bx/pages/-M0SZwZn5pERjpAzqeP-#3.10.0) – добавлен полный набор данных о звонке (`call_full`) и обновление полей сущности стало выполняться вне зависимости от того, была ли сущность создана на этом звонке, или ранее.

[3.13.0](https://docs.itgrix.ru/custom_bx/pages/-M0SZwZn5pERjpAzqeP-#id-3.13.0) – удалено устаревшее поле `call` из корня входных данных (остальные временно сохраняются для обратной совместимости).
{% endhint %}

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

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

* [Обновление полей сущности](/custom_bx/update-entity-fields.md)

**Вход:**

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

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

Набор данных о звонке описан в статье [Параметры звонка (call) и разговора (conversation) в кастомизациях](/custom_common/call-conversation-parameters.md#parametry-zvonka-call).\
Формат данных сущности в поле `entity` описан в соответствующем разделе статьи [Данные о звонке (call\_full) в кастомизациях](/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](https://docs.itgrix.ru/custom_bx/pages/-M0SZwZn5pERjpAzqeP-#3.0.7) – добавлена возможность настройки чёрного/белого списка для внутренних номеров [через веб-интерфейс модуля](/custom_common/black-white-list.md#nastroika-cherez-interfeis-modulya).

[3.10.0](https://docs.itgrix.ru/custom_bx/pages/-M0SZwZn5pERjpAzqeP-#3.10.0) – добавлены параметры `call_stage` и `call_full`.
{% endhint %}

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

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

* [Черный/белый список для транков](/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) в кастомизациях](/custom_common/call-conversation-parameters.md).

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

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

### 4) process\_client\_phone

{% hint style="info" %}
[3.0.0](https://docs.itgrix.ru/custom_bx/pages/-M0SZwZn5pERjpAzqeP-#3.0.0) – кастомизация номера разделена на две: `process_user_phone` (внутренний номер) и `process_client_phone` (номер клиента).

[3.7.0](https://docs.itgrix.ru/custom_bx/pages/-M0SZwZn5pERjpAzqeP-#3.7.0) – добавлена [автозамена номеров](/for-admins/autoreplacement.md), запускается ДО выполнения кастомизации.

[3.10.0](https://docs.itgrix.ru/custom_bx/pages/-M0SZwZn5pERjpAzqeP-#3.10.0) – добавлены параметры `call_stage` и `call_full`.
{% endhint %}

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

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

* [Изменение номера телефона перед отправкой данных в CRM](/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) в кастомизациях](/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](https://docs.itgrix.ru/custom_bx/pages/-M0SZwZn5pERjpAzqeP-#2.15.0) – чёрные/белые списки вынесены в кастомизацию [need\_registration](#3-need_registration).

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

[3.10.0](https://docs.itgrix.ru/custom_bx/pages/-M0SZwZn5pERjpAzqeP-#3.10.0) – добавлен полный набор данных о звонке (`call_full`).

[3.13.0](https://docs.itgrix.ru/custom_bx/pages/-M0SZwZn5pERjpAzqeP-#id-3.13.0) – удалено устаревшее поле `call` из корня входных данных.
{% endhint %}

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

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

* [Разные ответственные за пропущенные за разные транки](/custom_bx/default-resp-for-trunks.md)

**Вход:**

```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 описаны в [статье Детальные статусы звонка](/faq/detalnye-statusy-zvonka.md#bitrix24).\
Описание блока `call_full` см. в статье [Данные о звонке (call\_full) в кастомизациях](/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](/custom_common/c2c.md).

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

{% hint style="info" %}
[3.10.19](https://docs.itgrix.ru/custom_bx/pages/-M0SZwZn5pERjpAzqeP-#id-3.10.19) – таймаут выполнения кастомизации стал настраиваемым (ранее был жёстко зафиксирован в 10 секунд).

[3.13.0](https://docs.itgrix.ru/custom_bx/pages/-M0SZwZn5pERjpAzqeP-#id-3.13.0) – конвертация записей вынесена в основную логику коннектора, кастомизация служит только для изменения пути до файла записи.
{% endhint %}

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

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

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

### 8) process\_registration\_params

{% hint style="info" %}
[3.10.0](https://docs.itgrix.ru/custom_bx/pages/-M0SZwZn5pERjpAzqeP-#3.10.0) – добавлен полный набор данных о звонке (`call_full`), показ карточки звонка вынесен в отдельную кастомизацию `customize_show_call_card`.

[3.13.0](https://docs.itgrix.ru/custom_bx/pages/-M0SZwZn5pERjpAzqeP-#id-3.13.0) – удалены устаревшие поля `call`, `conversation` из корня входных данных.
{% endhint %}

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

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

* [Добавление кода города в зависимости от города оператора](/custom_bx/dobavlenie-koda-goroda-v-zavisimosti-ot-goroda-operatora.md)
* [Изменение первого ответственного за лид/контакт](/custom_bx/first-resp-for-call.md)
* [Создавать лид для каждого входящего звонка](/custom_bx/always-create-lead-on-incoming.md)

**Вход:**

```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) в кастомизациях](/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](https://docs.itgrix.ru/custom_bx/pages/-M0SZwZn5pERjpAzqeP-#2.15.0) – добавлен блок данных о разговоре (`conversation`).

[3.4.0](https://docs.itgrix.ru/custom_bx/pages/-M0SZwZn5pERjpAzqeP-#3.4.0) – возможность настройки задач через [веб-интерфейс модуля](/settings/additional/parametry-sozdaniya-zadach.md).

[3.10.0](https://docs.itgrix.ru/custom_bx/pages/-M0SZwZn5pERjpAzqeP-#3.10.0) – добавлен полный набор данных о звонке (`call_full`).

[3.13.0](https://docs.itgrix.ru/custom_bx/pages/-M0SZwZn5pERjpAzqeP-#id-3.13.0) – удалено устаревшее поле `conversation` из корня входных данных.
{% endhint %}

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

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

* [Кастомизация задач по пропущенным звонкам](/custom_bx/task-for-missed-call.md)

**Вход:**

```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) в кастомизациях](/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](https://docs.itgrix.ru/custom_bx/pages/-M0SZwZn5pERjpAzqeP-#3.0.0) – кастомизация номера разделена на две: `process_user_phone` (внутренний номер) и `process_client_phone` (номер клиента).

[3.7.0](https://docs.itgrix.ru/custom_bx/pages/-M0SZwZn5pERjpAzqeP-#3.7.0) – добавлена [автозамена номеров](/for-admins/autoreplacement.md), запускается ДО выполнения кастомизации.

[3.10.0](https://docs.itgrix.ru/custom_bx/pages/-M0SZwZn5pERjpAzqeP-#3.10.0) – добавлены параметры `call_stage` и `call_full`.
{% endhint %}

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

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

* [Несколько внутренних номеров у сотрудника](/custom_bx/neskolko-vnutrennikh-nomerov-u-sotrudnika.md)

**Вход:**

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

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

Описание блока `call_full` см. в статье [Данные о звонке (call\_full) в кастомизациях](/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](https://docs.itgrix.ru/custom_bx/pages/-M0SZwZn5pERjpAzqeP-#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) в кастомизациях](/custom_common/dannye-o-zvonke-call_full-v-kastomizaciyakh.md).

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

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

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

{% hint style="info" %}
[3.10.0](https://docs.itgrix.ru/custom_bx/pages/-M0SZwZn5pERjpAzqeP-#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) в кастомизациях](/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](https://docs.itgrix.ru/custom_bx/pages/-M0SZwZn5pERjpAzqeP-#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) в кастомизациях](/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](https://docs.itgrix.ru/custom_bx/pages/-M0SZwZn5pERjpAzqeP-#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) в кастомизациях](/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](https://docs.itgrix.ru/custom_bx/pages/-M0SZwZn5pERjpAzqeP-#id-3.13.0) – кастомизация добавлена.
{% endhint %}

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

**Вход:**

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

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

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

Описание блока `call_full` см. в статье [Данные о звонке (call\_full) в кастомизациях](/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](https://docs.itgrix.ru/custom_bx/pages/-M0SZwZn5pERjpAzqeP-#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) в кастомизациях](/custom_common/dannye-o-zvonke-call_full-v-kastomizaciyakh.md).\
Поле `call_full` может быть пустым, если на момент выполнения конвертации записи звонок отсутствует в кэше коннектора.\
Выполнение конвертации записи можно отменить, вернув пустой объект `data`.

Входные значения соответствуют [настройкам конвертации записи](/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](https://docs.itgrix.ru/custom_bx/pages/-M0SZwZn5pERjpAzqeP-#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"
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.itgrix.ru/custom_bx/custom_bx_history.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.