# Кастомизации (для версий до 3.0)

В версии 2.15.0 обновлена логика обработки звонков: теперь звонки регистрируются через телефонию Битрикс24, что позволяет [использовать сквозную аналитику](https://docs.itgrix.ru/settings/additional/end-to-end-analytics).

Это также означает, что теперь при необходимости создания сущности (лида/контакта) это делает сам Битрикс, а коннектор больше не ищет и не создаёт сущность напрямую.

В связи с обновлением изменилась также и функциональность кастомизаций.

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

(Схема для версий начиная с 2.15.0)

![](https://lh6.googleusercontent.com/7sGdM2yuQrdTPRBomzlvWv28X2BCX3aiv5wp3B8licyFYI009d8qDEwSmTyGrO_L6AskCjD2cSG076joY2_51Cx-DZLhIU6iNCbmT9ASpr_2EqzJL9eRSXfv_H4_UwMydW5ppxYz)

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

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

| <p>Файл кастомизации<br>(по алфавиту)</p> | Описание                                                                                                                                                         |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| get\_updated\_activity\_fields.php        | Обновление полей дела (в конце звонка).                                                                                                                          |
| get\_updated\_entity\_fields.php          | Обновить поля сущности (в конце звонка).                                                                                                                         |
| need\_registration.php                    | <p>Нужна ли регистрация звонка?<br>Можно сделать черно-белые списки по внутреннему номеру/транку.</p>                                                            |
| process\_final\_params.php                | Изменение данных завершения звонка.                                                                                                                              |
| process\_originate\_params.php            | <p>Изменение параметров при инициализации звонка из Битрикс24.<br>Можно позвонить через другой транк, через другой контекст, сменить формат номера и прочее.</p> |
| process\_phone\_number.php                | <p>Изменение номера телефона перед регистрацией в Б24 и перед поиском пользователя.<br>Можно сменить формат телефонного номера (+7, 8...).</p>                   |
| process\_record\_file\_path.php           | Кастомизация пути до файла записи разговора.                                                                                                                     |
| process\_registration\_params.php         | Изменение параметров регистрации звонка.                                                                                                                         |
| process\_task\_creation\_params.php       | Кастомизация создания задач по пропущенным звонкам.                                                                                                              |

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

### **1) process\_originate\_params**

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

**Примеры** [Изменения номера\контекста для вызова в астериск](https://docs.itgrix.ru/custom_bx)

**Вход:**

`{`\
`"params": {`\
`"caller_id": "<caller_id>",`\
`"channel": "<channel>",`\
`"context": "<context>",`\
`"extension": "<extension>",`\
`"priority": "<priority>"`\
`}`\
`}`

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

`{`\
`"data": {`\
`"caller_id": "<caller_id>",`\
`"channel": "<channel>",`\
`"context": "<context>",`\
`"extension": "<extension>",`\
`"priority": "<priority>"`\
`}`\
`}`

К этому массиву данных можно добавить переменные "codecs" и "variables":

`"codecs": "<codecs>",`\
`"variable": "variable",`

### **2) process\_phone\_number**

Преобразование номеров – как внутренних, так и внешних.

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

**Вход:**

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

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

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

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

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

**Пример** [Черные и белые списки. Как настроить?](https://docs.itgrix.ru/custom_common/black-white-list)

**Вход:**

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

Набор данных о разговоре описан ниже в разделе [Данные разговора в параметрах.](#parametry-razgovora-conversation)

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

`{`\
`"data": {`\
`"result": "<Булева переменная: true - регистрируем, false - игнорируем>"`\
`},`\
`"state": "success"`\
`}`

### **4) process\_registration\_params**

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

**Примеры** [Изменение внешнего номера в Битрикс24](https://docs.itgrix.ru/custom_bx/dobavlenie-koda-goroda-v-zavisimosti-ot-goroda-operatora)

**Вход:**

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

Набор данных о разговоре описан ниже в разделе [Данные разговора в параметрах.](#parametry-razgovora-conversation)

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

Полный список параметров в [документации Битрикса](https://dev.1c-bitrix.ru/rest_help/scope_telephony/telephony/telephony_externalcall_register.php).

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

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

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

**Примеры** [Разные ответственные за пропущенные за разные транки](https://docs.itgrix.ru/custom_bx/default-resp-for-trunks)

**Вход:**

`{"params": {`\
`"ADD_TO_CHAT": "<Добавить сообщение о звонке в бизнес чат>",`\
`"CALL_ID": "<Идентификатор звонка в битрикс>",`\
`"DURATION": "<Длительность>",`\
`"STATUS_CODE": 200,`\
`"USER_ID": "<Идентификатор пользователя Битрикс, ответственного за разговор>",`\
`"conversation": {<Набор данных о разговоре>}`\
`}}`

Набор данных о разговоре описан ниже в разделе [Данные разговора в параметрах](#parametry-razgovora-conversation).

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

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

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

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

**Пример** [Кастомизация имени файла аудиозаписи](https://docs.itgrix.ru/custom_common/filepath)

**Вход:**

`{"params": {`\
`"call_id": "<id_звонка>",`\
`"from": "<номер>",`\
`"to": "<номер>",`\
`"path": "<путь_до_записи>"`\
`}`\
`}`

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

`{"data": {`\
`"path": "<кастомизированный_путь_до_записи>"`\
`},`\
`"state": "success"`\
`}`

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

Событие возникает перед постановкой задачи (при пропущенном входящем звонке).\
Полное описание полей задачи в [API Битрикса](https://dev.1c-bitrix.ru/rest_help/tasks/fields.php)

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

**Вход:**

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

```
{"params": {
    "arNewTaskData": {
        "DEADLINE":"<Крайний срок исполнения>",
        "CREATED_BY": "<Идентификатор постановщика>",
        "RESPONSIBLE_ID": "<Идентификатор сотрудника, ответственного за задачу>",
        "TITLE":"<Заголовок задачи>",
        "UF_CRM_TASK": ["L_11201"]
    },
    "conversation": {
        "1550838819.13014": {<Набор данных о разговоре>},
        "1550838850.13029": {<Набор данных о разговоре>}
    }
}}
```

Набор данных о разговоре (conversation) описан ниже в разделе [Данные разговора в параметрах](#parametry-razgovora-conversation).

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

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

### **8) get\_updated\_activity\_fields**

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

Примеры использования\
[Обновление полей дела](https://docs.itgrix.ru/custom_bx/update-activity-fields)

**Вход:**

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

Набор данных о разговоре описан ниже в разделе [Данные разговора в параметрах](#parametry-razgovora-conversation).

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

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

### **9) get\_updated\_entity\_fields**

В версии 2.15.0 **get\_updated\_lead\_fields** перенесена в **get\_updated\_entity\_fields** и вызывается и для лидов, и для контактов.

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

Примеры использования – [Обновление полей сущности](https://docs.itgrix.ru/custom_bx/update-entity-fields)

**Вход:**

```
{"params": {
    "conversations": {
        "1550838819.13014": {<Набор данных о разговоре>},
        "1550838850.13029": {<Набор данных о разговоре>}
    },
    "answered_at":"",
    "ended_at":"",
    "from":"",
    "from_local":false,
    "id":"1550838797.13013",
    "started_at":"",
    "state":3,
    "to":"",
    "to_local":true,
    "trunk":"",
    "type":
}}
```

Набор данных о разговоре описан ниже в разделе [Данные разговора в параметрах](#parametry-razgovora-conversation).

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

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

Описание полей лида в [API Битрикса](https://dev.1c-bitrix.ru/rest_help/crm/leads/crm_lead_fields.php).\
Описание полей контакта в [API Битрикса](https://dev.1c-bitrix.ru/rest_help/crm/contacts/crm_contact_fields.php).

## Параметры разговора (conversation)

```
{
    "answered_at": "<Дата и время ответа>",
    "channel_id": "<Идентификатор канала>",
    "ended_at": "<Время завершения разговора>",
    "from": "<Номер звонящего>",
    "from_local": "<Является ли локальным номер звонящего: true/false>",
    "id": "<Идентификатор звонка>",
    "parent_channel_id": "<Идентификатор родительского канала>",
    "started_at": "<Дата и время начала звонка>",
    "state": "<Этап звонка. Числовое значение>",
    "state_code": "<Человекопонятное название этапа. 
                  Возмоные значения: unknown, ringing, talking, ended>",
    "to": "<Номер, на который пришёл звонок>",
    "to_local": "<Является ли локальным номер принимающего: true/false",
    "trunk": "<Внешний номер, на который поступил звонок>",
    "type": "<Направление звонка. Принимает значения: 
            1 - внутренний; 2 - входящий; 3 - исходящий>",
    "type_code": "<Направление звонка. Принимает значения: 
                 local - внутренний, incoming - входящий, outgoing - исходящий>",
    "was_answered": "<Является ли звонок отвеченным: true/false>"
}
```

**Пример** (входящий неотвеченный разговор с номера 89123456789 на 123 через транк 3432723033):

```
{
    "answered_at": null,
    "channel_id": "1175429532.4512",
    "ended_at": null,
    "from": "89123456789",
    "from_local": false,
    "id": "1175429532.4512",
    "parent_channel_id": "1175429532.4511",
    "started_at": "2019-04-01 12:05:25",
    "state": 1,
    "state_code": "ringing",
    "to": "123",
    "to_local": true,
    "trunk": "3432723033",
    "type": 2,
    "type_code": "incoming",
    "was_answered": false
}
```