> 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/readme.md).

# README

{% hint style="info" %}
**Данная статья актуальна для версий коннектора 3.13.\***

Для предыдущих версий можно воспользоваться "исторической" версией статьи: [Полезные кастомизации itgrix\_bx (Битрикс24) \[С историей\]](broken://pages/d256efd9f5986eb537a9b847d0e4c7a9dee9050e)
{% endhint %}

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

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

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

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

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

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

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

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

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

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

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

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

### **1)** customize\_activity

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

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

**Вход:**

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

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

{% hint style="warning" %}
В объекте `raw` присутствуют только поля с непустым/ненулевым значением.
{% endhint %}

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

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

Подробное описание полей **дела** в [**документации REST API Битрикс24**](https://dev.1c-bitrix.ru/rest_help/crm/rest_activity/crm_activity_fields.php/)**.**\
Запрос обновления дела не будет выполнен, если вернуть пустой объект `data`.

### **2) customize\_entity**

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

**Вход:**

```json
{
  "call_full": {<Полный набор данных о звонке>},
  <Остальные поля временно сохранены для обратной совместимости: call_registration, entity, entity_type, entity_id, entity_new>
}
```

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

{% hint style="warning" %}
Часть полей в корне входных данных кастомизации считаются устаревшими и будут убраны в будущих версиях коннектора.\
Вместо них рекомендуется использовать актуальные поля внутри объекта `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`
  {% endhint %}

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

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

Подробное описание полей **лида** в [**документации REST API Битрикс24**](https://dev.1c-bitrix.ru/rest_help/crm/leads/crm_lead_fields.php/)**.**\
Подробное описание полей **контакта** в [**документации REST API Битрикс24**](https://dev.1c-bitrix.ru/rest_help/crm/contacts/crm_contact_fields.php/)**.**\
Запрос обновления сущности не будет выполнен, если вернуть пустой объект `data`.

### **3) need\_registration**

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

{% hint style="info" %}
Базовая настройка черного/белого списка для внутренних номеров и транков доступна [из админки (интерфейса настройки) коннектора](file:///1659967/custom_common/black-white-list.md#nastroika-cherez-interfeis-modulya).
{% 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\_full) в кастомизациях](file:///1659967/custom_common/dannye-o-zvonke-call_full-v-kastomizaciyakh.md).

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

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

### **4) process\_client\_phone**

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

{% hint style="info" %}
Доступна [автозамена номеров](file:///1659967/for-admins/autoreplacement.md), она запускается ДО выполнения кастомизации.
{% endhint %}

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

**Вход:**

<pre class="language-json"><code class="lang-json">{
<strong>  "phone": "&#x3C;номер>",
</strong><strong>  
</strong><strong>  "call_full": {&#x3C;Полный набор данных о звонке>},
</strong>  "call_stage": "&#x3C;Стадия звонка. Для данной кастомизации один из вариантов:
     call_started           - начало звонка;
     conversation_requested - запрос разговора;
     conversation_accepted  - ответ;
     conversation_ended     - завершение разговора;
     call_ended             - завершение звонка;
     forward &#x3C;id> - автораспределение звонка>"
}
</code></pre>

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

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

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

### **5) process\_final\_params**

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

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

**Вход:**

```json
{
  "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 описаны в [статье Детальные статусы звонка](file:///1659967/faq/detalnye-statusy-zvonka.md#bitrix24).

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

{% hint style="warning" %}
Часть полей в корне входных данных кастомизации считаются устаревшими и будут убраны в будущих версиях коннектора.\
Вместо них рекомендуется использовать актуальные поля внутри объекта `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`
  {% endhint %}

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

```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)**.**\
Запрос завершения регистрации звонка можно отменить, вернув пустой объект `data`.

### **6) process\_originate\_params**

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

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

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

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

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

{% hint style="info" %}
В версиях Itgrix\_bx ниже 3.13.0 эта кастомизация использовалась для конвертации файлов записей разговоров в формат mp3 перед отправкой в Битрикс24.

Начиная с версии 3.13.0, конвертация записей выполняется [основной логикой коннектора](file:///1659967/blog/mp3-conversion.md), а кастомизация process\_record\_file\_path служит только для изменения пути до файла записи перед конвертацией.
{% endhint %}

### **8) process\_registration\_params**

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

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

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

**Вход:**

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

{% hint style="info" %}
Номера внешних линий в Битрикс24 (`LINE_NUMBER`) соответствуют транкам в настройках коннектора Itgrix.

Коннектор регистрирует номера транков как внешние линии в Битрикс24 при запуске, при этом каждой линии можно задать название в настройках.
{% endhint %}

{% hint style="warning" %}
Показ карточки звонка вынесен в отдельный запрос, и кастомизируется отдельной кастомизацией [customize\_show\_call\_card](file:///1659967/Archive.zip/#13-customize_show_call_card), поэтому **параметр `SHOW` всегда равен `0`.**

Это позволяет настроить момент показа карточки звонка отдельно от регистрации звонка: при дозвоне или при ответе.
{% endhint %}

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

```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)**.**\
Запрос регистрации можно отменить, вернув пустой объект `data`.

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

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

{% hint style="info" %}
Данная кастомизация работает, только если создание задач включено в настройках коннектора: [Настройка задачи по пропущенному через админку](file:///1659967/settings/additional/parametry-sozdaniya-zadach.md).

При этом сначала применяются настройки, описанные в статье, а затем выполняется данная кастомизация.
{% endhint %}

**Пример:** [Кастомизация задач по пропущенным звонкам](broken://pages/7b1ca78bc99f1702f24c5174a16959a57f00fea0) (начиная с версии [3.4.0](file:///1659967/changelog-bx.md#3.4.0) это можно [делать через веб-интерфейс настройки модуля](file:///1659967/settings/additional/parametry-sozdaniya-zadach.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) в кастомизациях](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)**.**\
Запрос создания задачи можно отменить, вернув пустой объект `data`.

### **10) process\_user\_phone**

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

{% hint style="info" %}
Доступна [автозамена номеров](file:///1659967/for-admins/autoreplacement.md), она запускается ДО выполнения кастомизации.
{% endhint %}

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

**Вход:**

<pre class="language-json"><code class="lang-json">{
  "phone": "&#x3C;номер>",
  
<strong>  "call_full": {&#x3C;Полный набор данных о звонке>},
</strong>  "call_stage": "&#x3C;Стадия звонка. Для данной кастомизации один из вариантов:
    conversation_requested - запрос разговора;
    conversation_accepted  - ответ;
    conversation_ended     - завершение разговора;
    call_ended             - завершение звонка;
    forward &#x3C;id> - автораспределение звонка>"
}
</code></pre>

Полный набор данных о звонке описан в статье [Данные о звонке (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 ответственного пользователя числом>
  },
  "request_data": {<Параметры запроса>},
  "call_full": {<Полный набор данных о звонке>},
  "error": "<текст ошибки>"
}
```

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

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

{% hint style="warning" %}
`name` - текст, который появится в CallerID и будет отображен в телефоне (или софтфоне) оператора.

**Должен быть не более 20 символов (ограничение Asterisk)!**
{% endhint %}

{% hint style="info" %}
Поля `from`, `user`, `entity` и `error` - только для чтения и присутствуют только когда не пустые.

Они будут автоматически удалены, даже если вернуть их в объекте `data`.
{% endhint %}

### 12) post\_registration

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

Может быть вызвана в разные моменты в зависимости от типа звонка:

* Для звонков кликом (click-to-call, c2c) кастомизация будет вызвана в начале обработки стадии Запрос разговора (Conversation requested).

{% hint style="info" %}
При звонках кликом Битрикс24 сам регистрирует звонок в момент клика и передает данные о регистрации коннектору, т.е. ещё до инициализации звонка в Asterisk.

Поэтому звонки кликом коннектор сам НЕ регистрирует, а только заканчивает, как и все остальные звонки.
{% endhint %}

* Пропущенные звонки на IVR регистрируются и завершаются на стадии Завершение звонка (Call ended).
* Для всех остальных звонков кастомизация будет вызвана после выполнения запроса регистрации звонка в Битрикс24 на стадии Запрос разговора (Conversation requested).

**Вход:**

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

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

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

Нужно вернуть только `state`, остальное игнорируется:

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

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

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

**Вход:**

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

Полный набор данных о звонке описан в статье [Данные о звонке (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)**.**\
Запрос показа карточки звонка можно отменить, вернув пустой объект `data`.

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

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

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

**Вход:**

<pre class="language-json"><code class="lang-json">{
  "DESCRIPTION": "&#x3C;Описание дела с аудиоплеером и ссылкой на запись звонка>",
<strong>  "DESCRIPTION_TYPE": &#x3C;Тип содержания в виде целого числа, по умолчанию 3, т.е. HTML>,
</strong>
  "activity": {
    "id": "&#x3C;ID дела>",
    "is_new": &#x3C;Всегда false>,
    "name": "&#x3C;Название дела (из поля SUBJECT)>",
    "phones": [&#x3C;Всегда пустой массив>],
    "raw": {Поля дела как в Битрикс24},
    "responsible": {&#x3C;Данные ответственного пользователя>},
    "responsible_id": "&#x3C;ID ответственного пользователя>",
    "type": "activity"
  },
  "call_full": {&#x3C;Полный набор данных о звонке>},
  "record_url": "&#x3C;URL записи звонка>",
  "old_description": "&#x3C;Описание дела до кастомизации>"
 }
</code></pre>

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

{% hint style="warning" %}
В объекте `raw` присутствуют только поля с непустым/ненулевым значением.
{% endhint %}

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

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

Подробное описание полей **дела** в [**документации REST API Битрикс24**](https://dev.1c-bitrix.ru/rest_help/crm/rest_activity/crm_activity_fields.php/)**.**\
Запрос обновления дела не будет выполнен, если вернуть пустой объект `data`.

### 15) process\_originate\_response

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

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

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

### 16) customize\_recording\_query

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

**Вход:**

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

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

Кастомизация параметров конвертации записи. Запускается перед конвертацией записи в 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) в кастомизациях](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

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

**Вход:**

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