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

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

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

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

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

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

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

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

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

{% hint style="info" %}
Подробнее про статусы звонка (поля `call_status` и `call_result`) в статье [Детальные статусы звонка](/faq/detalnye-statusy-zvonka.md#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) в кастомизациях](/custom_common/dannye-o-zvonke-call_full-v-kastomizaciyakh.md).

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

```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" %}
Доступна [автозамена номеров](/for-admins/autoreplacement.md), она запускается ДО выполнения кастомизации.
{% endhint %}

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

**Вход:**

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

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

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

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

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

**Вход:**

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

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

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

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

```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**

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

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

**Вход:**

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

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

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

```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](/custom_common/c2c.md).

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

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

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

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

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

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

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

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

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

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

При этом сначала применяются настройки, описанные в статье, а затем выполняется данная кастомизация.
{% 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) в кастомизациях](/custom_common/dannye-o-zvonke-call_full-v-kastomizaciyakh.md).

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

```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, описанную в статье [Автораспределение звонка на ответственного менеджера](/settings/autodistribution.md).
{% 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) в кастомизациях](/custom_common/dannye-o-zvonke-call_full-v-kastomizaciyakh.md).

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

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

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

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

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

**Вход:**

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

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

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

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

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

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

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

```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).


---

# 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_amo.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.