# Полезные кастомизации itgrix\_amo (amoCRM)

Дополнительные кастомизации описаны в разделе [Полезные кастомизации (любая CRM)](https://docs.itgrix.ru/custom_common).

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

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

<figure><img src="https://349598197-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M-rywOcELBwBcmtSBHS%2Fuploads%2FGsGBMtuVg7xBnp7CA9lf%2Famo-custom-3.0.png?alt=media&#x26;token=bbf9ec92-a4f1-467b-b564-4b4e3f48d4ae" alt=""><figcaption></figcaption></figure>

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

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

<table data-header-hidden><thead><tr><th width="79"></th><th></th><th></th></tr></thead><tbody><tr><td>№</td><td>Файл кастомизации<br>(по алфавиту)</td><td>Описание</td></tr><tr><td>1</td><td><a href="#1-need_registration">need_registration.php</a></td><td>Нужна ли регистрация звонка?<br>Можно сделать черные/белые списки по внутреннему номеру/транку.</td></tr><tr><td>2</td><td><a href="#2-process_call_params">process_call_params.php</a></td><td>Изменение параметров регистрации звонка.</td></tr><tr><td>3</td><td><a href="#3-process_client_phone">process_client_phone.php</a></td><td>Изменение номера телефона перед регистрацией в CRM.<br>Можно сменить формат телефонного номера (+7, 8...).</td></tr><tr><td>4</td><td><a href="#4-process_contact_creation_params">process_contact_creation_params.php</a></td><td>Изменение параметров создания контакта.</td></tr><tr><td>5</td><td><a href="#5-process_lead_creation_params">process_lead_creation_params.php</a></td><td>Изменение параметров создания сделки.</td></tr><tr><td>6</td><td><a href="#6-process_originate_params">process_originate_params.php</a></td><td>Изменение параметров при инициализации звонка из CRM.<br>Можно позвонить через другой транк, через другой контекст, сменить формат номера и прочее.</td></tr><tr><td>7</td><td><a href="#7-process_record_file_path">process_record_file_path.php</a></td><td><p>Кастомизация пути до файла записи разговора.</p><p>Также в этом файле настраивается конвертирование из формата wav в mp3. Описание в статье <a href="custom_common/mp3-record">Конвертация записей в формат MP3</a>.</p></td></tr><tr><td>8</td><td><a href="#8-process_task_creation_params">process_task_creation_params.php</a></td><td>Изменение параметров создания задач по пропущенным звонкам. Изменение названия задачи может помешать опции <a href="../settings/additional/auto-mange-tasks#amocrm">автоматического завершения задач</a>.</td></tr><tr><td>9</td><td><a href="#id-9-customize_autodistribution">customize_autodistribution.php</a></td><td>Кастомизация автораспределения входящих звонков.</td></tr><tr><td>10</td><td><a href="#id-10-post_registration">post_registration.php</a></td><td>Действия после регистрации звонка.</td></tr><tr><td>11</td><td><a href="#id-11-process_contact_update_params">process_contact_update_params.php</a></td><td>Изменение параметров обновления контакта.</td></tr><tr><td>12</td><td><a href="#id-12-process_lead_update_params">process_lead_update_params.php</a></td><td>Изменение параметров обновления сделки.</td></tr><tr><td>13</td><td><a href="#id-13-process_unsorted_creation_params">process_unsorted_creation_params.php</a></td><td>Изменение параметров создания неразобранного. Позволяет изменить поля контакта и сделки.</td></tr></tbody></table>

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

### **1) need\_registration**

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

{% hint style="info" %}
Базовая настройка черного/белого списка для внутренних номеров доступна [из админки (интерфейса настройки) коннектора](https://docs.itgrix.ru/custom_common/black-white-list#nastroika-cherez-interfeis-modulya).
{% endhint %}

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

**Вход:**

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

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

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

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

### **2) process\_call\_params**

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

{% hint style="info" %}
Подробнее про статусы звонка (поля `call_status` и `call_result`) в статье [Детальные статусы звонка](https://docs.itgrix.ru/faq/detalnye-statusy-zvonka#amocrm).
{% endhint %}

**Вход:**

```javascript
{
  "call_full": {<Полный набор данных о звонке>},
  
  "call_result": "<Результат звонка>",
  "call_status": <Статус звонка>,
  "created_at": <Дата создания звонка (в формате Unix Timestamp)>,
  "created_by": <ID ответственного пользователя>,
  "direction": "<Направление звонка. Принимает значения:
                "inbound" - входящий, "outbound" - исходящий>",
  "duration": <Длительность (последнего разговора) в секундах>,
  "link": "<Ссылка на получение записи (последнего разговора)>",
  "phone": "<Телефонный номер клиента
            (уже кастомизированный через process_client_phone)>",
  "responsible_user_id": <ID ответственного пользователя>,
  "source": "itgrix_amo"
}
```

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

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

```javascript
{
  "data": {
    "call_result": "<Результат звонка>",
    "call_status": <Статус звонка>,
    "created_at": <Дата создания звонка в Unix Timestamp>,
    "created_by": <ID ответственного пользователя>,
    "direction": "<Направление звонка. Принимает значения:
                    "inbound" - входящий, "outbound" - исходящий>",
    "duration": <Длительность (последнего разговора) в секундах>,
    "link": "<Ссылка на получение записи (последнего разговора)>",
    "phone": "<Телефонный номер клиента
                (уже кастомизированный через process_client_phone)>",
    "responsible_user_id": <ID ответственного пользователя>,
    "source": "itgrix_amo"
  },
  "state": "success"
}
```

### **3) process\_client\_phone**

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

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

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

**Вход:**

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

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

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

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

### **4) process\_contact\_creation\_params**

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

{% hint style="info" %}
В amoCRM по умолчанию в контакте нет поля для телефонного номера. Вместо этого используются пользовательские поля контактов.

Itgrix\_amo работает с полем контактов `"code": "PHONE"` с доступным значением `"enum": "WORK"`. **Если такого поля для контактов в аккаунте нет, то модуль не запустится.**

Подробное описание пользовательских полей в [документации **API amoCRM**](https://www.amocrm.ru/developers/content/crm_platform/custom-fields).
{% endhint %}

**Пример:** [Изменение тега при создании контакта/сделки](https://docs.itgrix.ru/custom_amo/izmenenie-tega-pri-sozdanii-kontakta-sdelki)**.**

**Вход:**

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

  "custom_fields_values": [
    {
      "field_id": <ID пользовательского поля контактов в аккаунте
                   (получено автоматически)>,
      "values": [
        {
          "enum_code": "<Значение поля.
                        Itgrix работает со значением "WORK">",
          "value": "<Номер телефона звонившего>"
        }
      ]
    }
  ],
  "name": "<Имя контакта. По умолчанию "Контакт <Тел.номер>">",
  "responsible_user_id": <ID ответственного пользователя>,
  "tags": [
    "Itgrix"
  ]
}
```

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

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

```javascript
{
  "data": {
    "custom_fields_values": [
      {
        "field_id": <ID пользовательского поля контактов в аккаунте
                    (получено автоматически)>,
        "values": [
          {
            "enum_code": "<Значение поля.
                          Itgrix работает со значением "WORK">",
            "value": "<Номер телефона звонившего>"
          }
        ]
      }
    ],
    "name": "<Имя контакта. По умолчанию "Контакт <Тел.номер>">",
    "responsible_user_id": <ID ответственного пользователя>,
    "tags": [
      "Itgrix"
    ]
    
    // Прочие поля также можно установить
  },
  "state": "success"
}
```

Параметры запроса создания контакта описаны в [документации API amoCRM](https://www.amocrm.ru/developers/content/crm_platform/contacts-api#contacts-add).

### **5) process\_lead\_creation\_params**

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

**Пример:** [Изменение тега при создании контакта/сделки](https://docs.itgrix.ru/custom_amo/izmenenie-tega-pri-sozdanii-kontakta-sdelki).

**Вход:**

```javascript
{
  "call_full": {<Полный набор данных о звонке>},
  
  "_embedded": {
    "contacts": [
      {"id": <ID контакта, с которыми связана сделка>}
    ],
    "tags": [
      {"name": "Itgrix"}
    ]
  },
  "name": "<Название сделки.
          По умолчанию "<Тел.номер> - [пропущенный] входящий/исходящий">",
  "pipeline_id": <ID воронки сделок>,
  "responsible_user_id": <ID ответственного пользователя>,
  "status_id": <ID статуса, в который добавляется сделка>
}
```

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

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

```javascript
{
  "data": {
    "_embedded": {
      "contacts": [
        {"id": <ID контакта, с которыми связана сделка>}
      ],
      "tags": [
        {"name": "Itgrix"}
      ]
    },
    "name": "<Название сделки.
            По умолчанию "<Тел.номер> - входящий/исходящий звонок">",
    "pipeline_id": <ID воронки сделок>,
    "responsible_user_id": <ID ответственного пользователя>,
    "status_id": <ID статуса, в который добавляется сделка>
    
    // Прочие поля также можно установить
  },
  "state": "success"
}
```

Параметры запроса создания сделки описаны в [документации API amoCRM](https://www.amocrm.ru/developers/content/crm_platform/leads-api#leads-add).

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

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

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

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

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

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

{% hint style="info" %}
При регистрации звонка в amoCRM в заметку будет добавлен плеер для проигрывания записи этого звонка (по ссылке, которую модуль Itgrix добавляет автоматически). Но плеер поддерживает только формат mp3.

При установке Itgrix\_amo по умолчанию уже включена [конвертация файлов записей разговоров в mp3](https://docs.itgrix.ru/custom_common/mp3-record).
{% endhint %}

{% hint style="warning" %}
Поскольку конвертация записей может занимать значительное время, у этой кастомизации индивидуальный **таймаут 10 секунд** (изменить можно в конфигурационном файле коннектора - `/etc/itgrix_amo/config.json`).

Если запись не успеет сконвертироваться до истечения таймаута, будет использован исходный файл.
{% endhint %}

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

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

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

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

**Вход:**

```javascript
{
  "call_full": {<Полный набор данных о звонке>},
  
  "complete_till": <Дата-время, когда задача должна быть завершена
                    (в формате Unix Timestamp)>,
  "created_by": <ID пользователя, создающего задачу>,
  "entity_id": <ID сущности, к которой привязана задача>,
  "entity_type": "<Тип сущности, к которой привязана задача.
                  Принимает значения: "contacts", "leads">",
  "is_completed": <Выполнена ли задача. При создании всегда false>,
  "responsible_user_id": <ID ответственного пользователя>,
  "task_type_id": <Тип задачи. Числовое значение:
                1 - Звонок, 2 - Встреча, 3 - Письмо>,
  "text": "<Описание задачи. По умолчанию:
           "Перезвонить <Имя сущности> по пропущенному звонку с номера <Тел.номер>">"
}
```

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

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

```javascript
{
  "data": {
    "complete_till": <Дата-время, когда задача должна быть завершена
                      (в формате Unix Timestamp)>,
    "created_by": <ID пользователя, создающего задачу>,
    "entity_id": <ID сущности, к которой привязана задача>,
    "entity_type": "<Тип сущности, к которой привязана задача.
                    Принимает значения: "contacts", "leads">",
    "is_completed": <Выполнена ли задача. При создании всегда false>,
    "responsible_user_id": <ID ответственного пользователя>,
    "task_type_id": <Тип задачи. Числовое значение:
                  1 - Звонок, 2 - Встреча, 3 - Письмо>,
    "text": "<Описание задачи. По умолчанию:
             "Перезвонить <Имя сущности> по пропущенному звонку с номера <Тел.номер>">"

    // Прочие поля также можно установить
  },
  "state": "success"
}
```

Параметры запроса создания задачи описаны в [документации API amoCRM](https://www.amocrm.ru/developers/content/crm_platform/tasks-api#tasks-add).

### 9) customize\_autodistribution

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

{% hint style="info" %}
Для работы функции автораспределения необходимо выполнить настройку Asterisk, описанную в статье [Автораспределение звонка на ответственного менеджера](https://docs.itgrix.ru/settings/autodistribution).
{% endhint %}

**Вход:**

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

  "from": "<номер с которого пришёл звонок>",
  "trunk": "<Номер транка>",
  "request_data": {<Параметры запроса автораспределения как есть>},
  "entity": {<Данные найденной сущности>},
  "error": "<текст ошибки>"
}
```

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

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

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

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

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

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

### 10) post\_registration

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

**Вход:**

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

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

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

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

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

### 11) process\_contact\_update\_params

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

**Вход:**

```json
{
  "call_full": {<Полный набор данных о звонке>},
  
  "id": <ID контакта>,
  "responsible_user_id": <ID ответственного пользователя>
}
```

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

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

```json
{
  "data": {
    "id": <ID контакта>,
    "responsible_user_id": <ID ответственного пользователя>

    // Прочие поля также можно изменить
  },
  "state": "success"
}
```

Параметры запроса обновления контакта описаны в [документации API amoCRM](https://www.amocrm.ru/developers/content/crm_platform/contacts-api#contacts-edit).

### 12) process\_lead\_update\_params

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

**Вход:**

```json
{
  "call_full": {<Полный набор данных о звонке>},
  
  "id": <ID сделки>,
  "responsible_user_id": <ID ответственного пользователя>
}
```

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

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

```json
{
  "data": {
    "id": <ID сделки>,
    "responsible_user_id": <ID ответственного пользователя>

    // Прочие поля также можно изменить
  },
  "state": "success"
}
```

Параметры запроса обновления сделки описаны в [документации API amoCRM](https://www.amocrm.ru/developers/content/crm_platform/leads-api#leads-edit).

### 13) process\_unsorted\_creation\_params

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

**Вход:**

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

  "_embedded": {
    "contacts": [{
      "custom_fields_values": [{
        "field_id": <ID пользовательского поля контактов в аккаунте
                    (получено автоматически)>,
        "values": [{
          "enum_code": "<Значение поля.
                        Itgrix работает со значением "WORK">",
          "value": "<Номер телефона звонившего>"
        }]
      }],
      "name": "<Имя контакта. По умолчанию "Контакт <Тел.номер>">",
      "tags": [
        "Itgrix"
      ]
    }],
    "leads": [{
      "name": "<Название сделки.
               По умолчанию "<Тел.номер> - [пропущенный] входящий/исходящий">",
      "pipeline_id": <ID воронки сделок>,
      "tags": [
        {"name": "Itgrix"},
      ]
    }]
  },
  "created_at": <Дата создания неразобранного (в формате Unix Timestamp)>,
  "metadata": {
    "called_at": <Когда сделан звонок (в формате Unix Timestamp)>,
    "duration": <Длительность звонка в секундах>,
    "from": "<Номер телефона звонившего>",
    "is_call_event_needed": false,
    "link": "<Ссылка на запись звонка>",
    "phone": "<Номер телефона, на который звонили>",
    "service_code": "itgrix_amo",
    "uniq": "<Уникальный идентификатор звонка.
              Itgrix передает linkedid звонка>"
  },
  "pipeline_id": <ID воронки сделок>,
  "source_name": "itgrix_amo",
  "source_uid": "<UID источника заявки.
                  Itgrix передает linkedid звонка>"
}
```

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

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

```json
{
  "data": {
    "_embedded": {
      "contacts": [{
        "custom_fields_values": [{
          "field_id": <ID пользовательского поля контактов в аккаунте
                      (получено автоматически)>,
          "values": [{
            "enum_code": "<Значение поля.
                          Itgrix работает со значением "WORK">",
            "value": "<Номер телефона звонившего>"
          }]
        }],
        "name": "<Имя контакта. По умолчанию "Контакт <Тел.номер>">",
        "tags": [
          "Itgrix"
        ]
      }],
      "leads": [{
        "name": "<Название сделки.
                По умолчанию "<Тел.номер> - [пропущенный] входящий/исходящий">",
        "pipeline_id": <ID воронки сделок>,
        "tags": [
          {"name": "Itgrix"},
        ]
      }]
    },
    "created_at": <Дата создания неразобранного (в формате Unix Timestamp)>,
    "metadata": {
      "called_at": <Когда сделан звонок (в формате Unix Timestamp)>,
      "duration": <Длительность звонка в секундах>,
      "from": "<Номер телефона звонившего>",
      "is_call_event_needed": false,
      "link": "<Ссылка на запись звонка>",
      "phone": "<Номер телефона, на который звонили>",
      "service_code": "itgrix_amo",
      "uniq": "<Уникальный идентификатор звонка.
                Itgrix передает linkedid звонка>"
    },
    "pipeline_id": <ID воронки сделок>,
    "source_name": "itgrix_amo",
    "source_uid": "<UID источника заявки.
                    Itgrix передает linkedid звонка>"

    // Прочие поля также можно установить
  },
  "state": "success"
}
```

Параметры запроса создания неразобранного описаны в [документации API amoCRM](https://www.amocrm.ru/developers/content/crm_platform/unsorted-api#unsorted-add-sip).