> For the complete documentation index, see [llms.txt](https://docs.aiokk.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aiokk.io/settings/datasource/podderzhivaemye-istochniki/webhook.md).

# Универсальный вебхук

Если вашей системы нет в списке поддерживаемых источников данных, но у вас есть техническая возможность отправлять POST-запросы из своей системы, то вы можете использовать наш универсальный вебхук в качестве "моста" для связи вашего источника данных с нашей системой.

> **Вебхук** – это способ автоматического обмена информацией между системами. Он позволяет одной системе (например, вашей базе данных / телефонии / ERP- или CRM-системе) отправлять данные в другую систему (например, в aiokk) сразу же, как только происходит какое-то событие. В нашем случае таким событием должно быть *завершение* *телефонного звонка*.

## Как это работает

Настройте свою систему так, чтобы мы получали через вебхук информацию о новом звонке каждый раз, когда заканчивается телефонный звонок. Вы можете встроить в своей системе отправку данных на наш вебхук только в тех местах, где вам это предусмотрено вашими бизнес-процессами.

## Настройки на стороне личного кабинета

### Первичная настройка

Для подключения сторонней системы через вебхук необходимо произвести несколько предварительных действий на стороне личного кабинета.

<figure><img src="/files/udPxkJjYttZlTCiDCdRa" alt=""><figcaption><p>Активация вебхука в разделе Настройки → Источники даных</p></figcaption></figure>

1. В разделе **Настройки → Источник данных** выберите в качестве источника **Универсальный вебхук**.
2. Активируйте вебхук
3. Убедитесь, что вебхук был активирован. Соответствующее состояние будет отображено рядом с заголовком страницы.

<figure><img src="/files/rFCfJgiyg5uYmDPBNCkR" alt=""><figcaption></figcaption></figure>

4. Скопируйте **токен**, который далее будете использовать для формирования ссылки для POST-запросов.

{% hint style="warning" %}
**Внимание!**&#x20;

1. Доступ к данным внутри вашего кабинета обеспечивается посредством верификации через уникальный токен, видимы только в вашем личном кабинете. Никогда не передавайте токен третьим лицам!
2. Техническая поддержка **никогда не будет запрашивать токен** вашей учетной записи!
   {% endhint %}

### Смена токена

Если по каким-либо причинам вам понадобилось изменить токен, то воспользуйтесь специальной кнопкой, чтобы сгенерировать новый токен.

<figure><img src="/files/c79vl0sUqCFiXgxG1Ak4" alt=""><figcaption><p>Кнопка перегенерации токена доступа</p></figcaption></figure>

Во всплывающем уведомлении подтвердите перегенерацию токена доступа и дождитесь, когда в поле "Токен доступа" появится новый токен.

{% hint style="danger" %}
**Очень важно!** Если вы ранее задействовали старый токен в своих запросах, то после перегенерации токена **вебхуки со старым токеном перестанут работать**, и для восстановления работоспособности вебхука вам нужно будет **самостоятельно заменить старый токен на новый** во всех сценариях, где был задействован старый вебхук, т.к. вебхуки с недействительным токеном перестанут работать, получая в ответе статус 401 (см. подробнее [**тут**](#otvet-na-zapros-tbd)).
{% endhint %}

### Отключение вебхука

В разделе **Настройки → Источник данных** нажмите на кнопку "Отключить вебхук", если хотите разорвать соединение aiokk c вашим источником данных. Запросы, отправляемые после отключения вебхука, будут завершаться со статусом 403 (подробности см.[ **тут**](#otvet-na-zapros-tbd)), новые данные не будут попадать в личный кабинет, аналитика новых звонков производиться не будет.

Если в дальнейшем вы снова активируете вебхук, то **прежний токен доступа будет по-прежнему работать**, и вам ничего не придется перенастраивать.

## Составляем запрос

<mark style="color:green;">`POST`</mark> **`https://my.aiokk.{domain_zone}/api/v1/{token}/call/new`**

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

### Подготовка ссылки эндпоинта

Для подготовки корректной ссылки эндпоинта вам необходимо подставить в приведенный выше URL `https://my.aiokk.{domain_zone}/api/v1/{token}/call/new` две переменные:

1. **<https://my.aiokk.{domain\\_zone}>** - соответствует доменной зоне, на которой зарегистрирован ваш кабинет aiokk. Чтобы уточнить вашу доменную зону, авторизуйтесь в своём личном кабинете aiokk и проверьте домен в адресной строке вашего браузера.

   <figure><img src="/files/UvWNfpV8nbuj0HnmiGQs" alt=""><figcaption><p>Проверка доменной зоны аккаунта aiokk</p></figcaption></figure>

   В данном конкретном примере, доменная зона - **kz**
2. **{token} -** уникальный токен доступа, видимый только в вашем личном кабинете на странице **"Настройки → Источник данных"** при выборе **вебхука** в качестве источника.

### **Заголовки**

<table data-full-width="false"><thead><tr><th>Заголовок</th><th>Значение</th></tr></thead><tbody><tr><td>Content-Type</td><td><code>application/json</code></td></tr></tbody></table>

### **Тело запроса**

Тело запроса представляет собой JSON-объект с тремя основными блоками: **call, employee и analytics.**

**Блок "call"**

<table data-full-width="false"><thead><tr><th>Поле</th><th>Тип</th><th>Обязательность</th><th>Описание</th></tr></thead><tbody><tr><td><strong>uid</strong></td><td>string</td><td>❌ Нет</td><td>Уникальный идентификатор вызова</td></tr><tr><td><strong>phone</strong></td><td>string</td><td>✅ Да</td><td>Номер телефона абонента в международном формате (например, +77771112233)</td></tr><tr><td><strong>duration</strong></td><td>int</td><td>✅ Да</td><td>Длительность звонка в секундах (поддерживается перевод string в integer) </td></tr><tr><td><strong>date</strong></td><td>datetime with timezone</td><td>✅ Да</td><td>Дата и время звонка в формате ISO 8601 (например, 2024-12-15T12:25:41+03:00)</td></tr><tr><td><strong>type</strong></td><td>int</td><td>✅ Да</td><td>Тип звонка: <br>1 - Исходящий, <br>2 - Входящий,<br>3 - Входящий с переадресацией<br>4 - Обратный вызов<br>(поддерживается перевод string в integer) </td></tr><tr><td><strong>url</strong></td><td>string</td><td>✅ Да</td><td>Ссылка на запись звонка</td></tr><tr><td><strong>extNumber</strong></td><td>string</td><td>❌ Нет</td><td>Внешний номер, на который поступил звонок</td></tr><tr><td><strong>ownerBacklink</strong></td><td>string</td><td>❌ Нет</td><td>Ссылка на сущность в вашей системе, к которой подвязан звонок <em>(используется для быстрого перехода из карточки звонка)</em></td></tr></tbody></table>

**Блок "employee"**

<table data-full-width="false"><thead><tr><th>Поле</th><th>Тип</th><th>Обязательность</th><th>Описание</th></tr></thead><tbody><tr><td><strong>id</strong></td><td>string</td><td>❌ Нет</td><td>Идентификатор сотрудника</td></tr><tr><td><strong>fullName</strong></td><td>string</td><td>✅ Да</td><td>Полное имя сотрудника</td></tr><tr><td><strong>intNum</strong></td><td>int</td><td>❌ Нет</td><td>Внутренний номер сотрудника</td></tr><tr><td><strong>departmentId</strong></td><td>string</td><td>❌ Нет</td><td>Идентификатор отдела, в котором работает сотрудник</td></tr><tr><td><strong>departmentName</strong></td><td>string</td><td>✅ Да</td><td>Название отдела, в котором работает сотрудник</td></tr></tbody></table>

**Блок "analytics"**

<table data-full-width="false"><thead><tr><th>Поле</th><th width="100">Тип</th><th>Обязательность</th><th>Описание</th></tr></thead><tbody><tr><td><strong>summary</strong></td><td>boolean</td><td>❌ Нет</td><td>Пересказ текста <em>(по умолчанию true)</em>. Используйте этот параметр <strong>только самостоятельно без других заданий на аналитику</strong>, если вам требуется исключительно пересказ звонка. Во всех остальных случаях значение параметра будет проигнорировано и по умолчанию будет принято значение <em>true.</em></td></tr><tr><td><strong>language</strong></td><td>boolean</td><td>❌ Нет</td><td>Определять применяемые языки <em>(по умолчанию false)</em></td></tr><tr><td><strong>customerSatisfaction</strong></td><td>object</td><td>❌ Нет</td><td>Блок задач на определение удовлетворенности клиента <em>(по умолчанию не задействован)</em></td></tr><tr><td><strong>→ assessment</strong></td><td>boolean</td><td>☝️Условно необязательное</td><td>Оценка удовлетворенности клиента <em>(если false, то motivation и recommendation не могут быть true)</em></td></tr><tr><td><strong>→ motivation</strong></td><td>boolean</td><td>☝️Условно необязательное</td><td>Развернутое обоснование оценки удовлетворенности клиента <em>(может быть true, только если assessment - true)</em></td></tr><tr><td><strong>→ recommendation</strong></td><td>boolean</td><td>☝️Условно необязательное</td><td>Рекомендации по повышению оценки удовлетворенности клиента <em>(может быть true, только если assessment - true)</em></td></tr><tr><td><strong>evaluationCriteria</strong></td><td>object</td><td>❌ Нет</td><td>Блок задач на оценку сотрудника по своим критериям <em>(по умолчанию не задействован)</em></td></tr><tr><td><strong>→ questionPack</strong></td><td>int</td><td>☝️Условно необязательное</td><td>Идентификатор набора вопросов для оценки сотрудника <em>(если false, то motivation и recommendation не могут быть true)</em></td></tr><tr><td><strong>→ motivation</strong></td><td>boolean</td><td>☝️Условно необязательное</td><td>Развернутое обоснование оценки по каждому критерию оценки <em>(может быть true, только если assessment - true)</em></td></tr><tr><td><strong>→ recommendation</strong></td><td>boolean</td><td>☝️Условно необязательное</td><td>Рекомендации по повышению оценки удовлетворенности клиента <em>(может быть true, только если assessment - true)</em></td></tr><tr><td><strong>signals</strong></td><td>int</td><td>❌ Нет</td><td>Идентификатор набора маяков для проверки на наличие в разговоре</td></tr><tr><td><strong>scripts</strong></td><td>int</td><td>❌ Нет</td><td>Идентификатор скрипта, на соответствие которому необходимо оценить разговор <em>(скоро)</em></td></tr><tr><td><strong>markers</strong></td><td>boolean</td><td>❌ Нет</td><td>Маркировка звонка тегами из заданного списка на основе содержания разговора</td></tr></tbody></table>

{% hint style="danger" %}
**Обратите внимание!** В блоке "analytics" не упоминается параметр, отвечающий за пересказ содержимого звонка, т.к. задание пересказа добавляется к любому составу аналитики **по умолчанию.** То есть, даже если в составе аналитики не будет указано ни одно задание, **пересказ будет произведен в любом случае.**
{% endhint %}

{% hint style="warning" %}
Оставьте массив **analytics{}** полностью пустым, если хотите запросить аналитику по стандартному составу аналитики, настроенному на стороне личного кабинета aiokk.
{% endhint %}

### **Пример запроса**

{% code title="Тело POST-запроса" overflow="wrap" fullWidth="false" %}

```json
{
    "call": {
        "uid": "abcd1234567890asdasdfsdf1231232123123", // Уникальный идентификатор вызова
        "phone": "+77771112233", // Номер телефона абонента в международном формате
        "duration": 78, // Длительность звонка в секундах
        "date": "2024-12-15T12:25:41+03:00", // Дата и время звонка с часовым поясом
        "type": 2, // Тип звонка
        "url": "https://source.to/your/audio.mp3" // Ссылка на запись звонка
        "extNumber": "88001119900", // Внешний номер, на который поступил звонок
        "ownerBacklink": "https://source.to/owner" // Ссылка на сущность в вашей системе, к которой подвязан звонок 
    },
    "employee": {
        "id": "123", // Идентификатор сотрудника
        "fullName": "Иван Иванов", // Полное имя сотрудника
        "intNum": "1309", // Внутренний номер сотрудника
        "departmentId": "98", // Идентификатор отдела, в котором работает сотрудник
        "departmentName": "Отдел продаж" // Название отдела сотрудника
    }, 
    "analytics": {
        "language": false, // Определять применяемые языки
        "customerSatisfaction":{
            "assessment": true, // Оценка удовлетворенности клиента
            "motivation": false, // Развернутое обоснование оценки удовлетворенности клиента
            "recommendation": true, // Рекомендации по повышению оценки удовлетворенности клиента
        },
        "evaluationCriteria": {
            "questionPack": 123, // Идентификатор набора вопросов для оценки сотрудника
            "motivation": true, // Развернутое обоснование оценки по каждому критерию оценки
            "recommendation": false, // Рекомендации по повышению оценки удовлетворенности клиента
        }, 
        "signals": 21, // Идентификатор набора маяков для проверки на наличие в разговоре
        "scripts": 55,  // Идентификатор скрипта, на соответствие которому необходимо оценить разговор
        "markers": true,  // Тематические маркеры на основе содержания звонка
    }
}
```

{% endcode %}

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

В результате выполнения запроса, вы получите ответ от нашей системы. Содержимое ответа может быть разным, в зависимости от статуса и результата проверки тела запроса. Ниже приведены варианты статусов, с которыми может завершиться запрос. Помимо общего статуса, в параметре "message" может прийти дополнительная полезная информация с кодами. Расшифровку кодов и пути решения ошибок вы можете получить ниже в [**Справочнике**](#spravochnik-kodov-oshibok-i-preduprezhdenii).

{% tabs %}
{% tab title="200" %}

```json
{
    "status": "success",
    "message": "Some warning text or null if not provided" 
}
```

{% endtab %}

{% tab title="401" %}

```json
{
    "status": "error",
    "message": "1000. Unauthorized: token is invalid"
}
```

{% endtab %}

{% tab title="403" %}

```json
{
    "status": "error",
    "message": "1001. Forbidden: Connection refused"
}
```

{% endtab %}

{% tab title="422" %}

```json
{
    "status": "Validation error",
    "messages": 
        "1100. The field 'field.name' is required."
    }
}
```

{% endtab %}
{% endtabs %}

## Итоговый набор аналитики

Если ваш запрос получил в ответ статус 200 (в том числе если наряду с ним были получены различного рода предупреждения), значит по отправленному разговору будет произведена аналитика.

### Логика формирования итогового набора аналитики

{% hint style="danger" %}
**Внимание!** Учитывая разнообразие настроек в составе аналитики, а также возможные ошибки, которые могут возникнуть из-за некорректного заполнения полей или нарушения логических взаимосвязей между полями, **итоговый набор аналитики может отличаться от первичного состава, указываемого в теле запроса.**
{% endhint %}

#### Возможные варианты итогового набора аналитики

Возможны следующие варианты в зависимости от корректности заполнения данных в массиве **analytics{}.**

1. **Указан только параметр "summary":"true".** Мы понимаем, что вам нужен только пересказ звонка, и на полученном звонке будет произведен только пересказ.
2. **Указано несколько параметров, все прошли проверку на валидацию.** Конечный состав аналитики будет соответствовать запрошенному составу в вебхуке. При этом тег **"summary"** может отсутствовать или быть некорректно заполнен, но пересказ разговора в любом случае будет автоматически добавлен к запрошенному составу аналитики.
3. **Указано несколько параметров, но не все параметры прошли проверку на валидацию.** Конечный состав аналитики будет состоять только из корректно заполненных параметров, успешно прошедших все проверки на валидацию. При этом тег **"summary"** может отсутствовать или быть некорректно заполнен, но пересказ разговора в любом случае будет автоматически добавлен к запрошенному составу аналитики.
4. **Указано несколько параметров, но ни один параметр не прошел проверку на валидацию.**  Логика схожа с предыдущим случаем. Если ни один параметр не прошел успешную валидацию, то **будет применено задание на пересказ**, по умолчанию присутствующее во всех составах аналитики.
5. **Пустой массив analytics{}.** Именно **пустой, а не отсутствующий.** Массив обязательно должен быть в теле запроса, так мы поймем, что вы не забыли его прописать, а целенаправленно оставили пустым. Будет применен состав аналитики по умолчанию, настроенный в личном кабинете aiokk в разделе [**Настройки → Аналитика**](#sostav-analitiki-po-umolchaniyu). Он также **включает в себя пересказ** звонка.

### Состав аналитики по умолчанию

При работе с вебхуками возможно использование набора аналитики по умолчанию, настраиваемого в разделе [**Настройки → Аналитика**](/settings/analytics/sostav-analitiki.md#sostav-analitiki-po-umolchaniyu).&#x20;

{% hint style="warning" %}
Для того, чтобы произвести аналитику звонка по стандартному набору действий, **отправьте в вебхуке пустой параметр "analytics": {}**

Это послужит для нас сигналом, что вам требуется именно стандартный сценарий аналитики, согласно настройкам в личном кабинете (состав аналитики по умолчанию).
{% endhint %}

{% hint style="info" %}
Некоторые задания аналитики, такие как **критерии оценки, набор маяков** и др., для которых необходима привязка к отдельным сущностям в настройках кабинета, **нуждаются в дополнительном уточнении сущности по умолчанию** в случае работы по стандартному сценарию аналитики.
{% endhint %}

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

**Критерии оценки**

<figure><img src="/files/rULMB6D6ZwAijE6QMezh" alt=""><figcaption><p>Выбор набора вопросов по умолчанию для стандартного набора аналитики</p></figcaption></figure>

**Маяки**

<figure><img src="/files/aKpxhyvgBoKkrFhclH2c" alt=""><figcaption><p>Выбор списка маяков по умолчанию для стандартного набора аналитики</p></figcaption></figure>

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

## Справочник кодов ошибок и предупреждений

### Ошибки аутентификации и подключения (1000-1099)

<details>

<summary>1000 - Недействительный токен доступа (статус 401)</summary>

**Исходное сообщение**: 'error': '1000. Unauthorized: token is invalid' (401)&#x20;

**Описание**: Предоставленный токен доступа недействителен. Необходимо получить новый токен аутентификации.&#x20;

**Решение**:

* Проверьте правильность токена
* При необходимости получите новый токен на странице **Настройки → Источник данных** и перенастройте вебхук.

</details>

<details>

<summary>1001 - Отказ в подключении (статус 403)</summary>

**Исходное сообщение**: 'error': '1001. Forbidden: Connection refused' (403)&#x20;

**Описание**: Сервер отказал в установлении соединения. Это может быть связано с выключенным токеном или проблемами с сетевым подключением.

**Решение**:

* Убедитесь в стабильности сетевого подключения.
* Проверьте правильность настроек файервол.
* Убедитесь, что на странице **Настройки → Источник данных** статус вебхука указан как "**Активный**".

</details>

### Ошибки валидации данных (1100-1199) (статус 422)

<details>

<summary>1100 - Некорректные данные запроса</summary>

**Исходное сообщение**: "error": "1100. The field '*field.name*' is required."

**Описание**: Единый код ошибки без привязки к конкретному полю. В запросе отсутствуют обязательные поля. См. раздел "[**Тело запроса**](#telo-zaprosa)".

**Решение**:

* Проверьте наличие всех обязательных полей в запросе
* Убедитесь, что значения полей соответствуют требуемому формату
* Сверьтесь с документацией API для уточнения требований к данным

</details>

<details>

<summary>1101 - Некорректный формат даты</summary>

**Исходное сообщение**: "1100. The field 'call.date' must be in ISO 8601 format with timezone."

**Описание**: Предоставленное значение даты не соответствует требуемому формату ISO 8601 с указанием временной зоны.&#x20;

**Решение**:

* Проверьте наличие информации о часовом поясе в передаваемой информации.
* Убедитесь, что дата указана в формате ISO 8601 (например: "2024-12-31T15:30:00+03:00")
* Используйте стандартные библиотеки для форматирования дат

</details>

<details>

<summary>1102 - Неверный тип данных поля call.type</summary>

**Исходное сообщение**: "1102. The field 'call.type' must be an integer."

**Описание**: Значение поля call.type должно быть целым числом, но предоставлено значение другого типа данных.

**Решение**:

* Убедитесь, что значение является целым числом. Если вы передаете целое число в виде строкового поля, то происходит автоматическое преобразование типа поля.
* При необходимости выполните преобразование типа данных на стороне вашего источника данных.

</details>

<details>

<summary>1103 - Недопустимое значение типа звонка</summary>

**Исходное сообщение**: "1103. The field 'call.type' must be one of the following values: 1 (Outgoing), 2 (Incoming), 3 (Incoming with redirection), 4 (Callback)."

**Описание**: Указанное значение типа звонка не соответствует списку допустимых значений.

**Решение**:

* Убедитесь, что значение передается как целое число, а не строка
* Используйте только следующие значения для поля call.type:
  * 1: Исходящий звонок (Outgoing)
  * 2: Входящий звонок (Incoming)
  * 3: Входящий звонок с переадресацией (Incoming with redirection)
  * 4: Обратный звонок (Callback)
* Проверьте соответствие значения бизнес-логике вашего приложения

</details>

<details>

<summary>1104 - Некорректный формат URL</summary>

**Исходное сообщение**: "1104. The field 'call.url' must be a valid URL starting with http or https."

**Описание**: Предоставленный URL источника записи звонка не соответствует требуемому формату или не содержит необходимый протокол.

**Решение**:

* Убедитесь, что URL начинается с "http\://" или "https\://"
* Проверьте правильность написания URL
* Проверьте наличие всех необходимых компонентов URL (домен, путь и т.д.)

</details>

<details>

<summary>1105 - Некорректное расширение аудиофайла</summary>

**Исходное сообщение**: "1105. The audio file extension is not supported. Allowed extensions are: .mp3, .m4a, .wav, .ogg"

**Описание**: Загружаемый аудиофайл имеет неподдерживаемое расширение. Система принимает только определённые форматы аудиофайлов.

**Решение**:

* Используйте только следующие форматы аудиофайлов:
  * .mp3 (MPEG Layer-3)
  * .m4a (MPEG-4 Audio)
  * .wav (Waveform Audio File Format)
  * .ogg (Ogg Vorbis)
* Проверьте расширение загружаемого файла
* При необходимости конвертируйте файл в поддерживаемый формат перед отправкой вебхука
* Убедитесь, что файл не был переименован и действительно содержит аудиоданные в указанном формате

</details>

<details>

<summary>1106 - Некорректный формат длительности звонка</summary>

**Исходное сообщение**: "1106. The field 'call.duration' must be an integer or a numeric string."

**Описание**: Значение длительности звонка должно быть представлено в виде целого числа или числовой строки. Другие форматы данных не поддерживаются.

**Решение**:

* Убедитесь, что значение длительности передается как целое число (например: 120) или числовая строка (например: "120")
* Проверьте, что значение не содержит десятичных дробей
* Удалите любые нечисловые символы (буквы, специальные символы)
* При необходимости выполните преобразование значения в подходящий формат

</details>

<details>

<summary>1107 - Недопустимые символы в номере телефона</summary>

**Исходное сообщение**: "1107. The field 'call.phone' can only contain digits, '+', '-', '(', and ')'. Spaces and other characters are not allowed."&#x20;

**Описание**: В номере телефона обнаружены недопустимые символы. Разрешены только цифры и специальные символы для форматирования номера.&#x20;

**Решение**:

* Используйте только следующие символы:
  * Цифры (0-9)
  * Плюс (+) для международного формата
  * Дефис (-) для разделения групп цифр
  * Круглые скобки ( ) для кода города/страны
* Удалите все пробелы из номера
* Удалите любые другие специальные символы
* Проверьте номер на соответствие допустимому формату

</details>

<details>

<summary>1108 - Слишком короткий номер телефона</summary>

**Исходное сообщение**: "1108. The field 'call.phone' must contain at least 3 characters."

**Описание**: Указанный номер телефона слишком короткий. Минимальная допустимая длина - 3 символа.&#x20;

**Решение**:

* Убедитесь, что номер телефона содержит не менее 3 символов
* Проверьте, не были ли случайно удалены цифры при вводе
* Укажите полный номер телефона в соответствии с принятым форматом
* При необходимости добавьте код города или страны

</details>

### Ошибки валидации необязательных полей (1200-1299) (статус 200)

<details>

<summary>1200 - Некорректное значение оценки удовлетворенности</summary>

**Исходное сообщение**: "1200. analytics.customerSatisfaction.assessment can only be true, false, or null."

**Описание**: Поле оценки удовлетворенности клиента принимает только логические значения или может быть не заполнено.

**Решение**:

* Используйте только значения: true, false или null
* Проверьте формат передаваемых данных
* Убедитесь, что значение соответствует бизнес-логике

</details>

<details>

<summary>1201 - Некорректный формат ID элемента в aiokk</summary>

**Исходное сообщение**: "1201. The field '*field.name*" must be an integer or a numeric string."

**Описание**: Идентификатор набора вопросов должен быть целым числом или числовой строкой. Другие форматы данных не поддерживаются.

**Проверяемые поля:**&#x20;

* analytics.evaluationCriteria.questionPack,
* analytics.signals,
* analytics.scripts.

**Решение**:

* Убедитесь, что значение является целым числом и числовой строкой
* Проверьте тип передаваемых данных
* При необходимости выполните преобразование типа

</details>

<details>

<summary>1202 - Нарушение логики оценки удовлетворенности клиента</summary>

**Исходное сообщение**: "1202. If 'analytics.customerSatisfaction.assessment' is not true, then 'motivation' and 'recommendation' cannot be true."

**Описание**: Ошибка возникает в случае, если задача на мотивацию оценки удовлетворенности клиента и/или рекомендация по ее повышению активированы без активации непосредственно задачи на оценку удовлетворенности клиента.&#x20;

**Решение**:

* Убедитесь, что ваш запрос содержит "analytics.customerSatisfaction.assessment": "true"
* Проверьте логическую связь между полями
* Убедитесь в последовательности заполнения данных

</details>

<details>

<summary>1203 - Нарушение логики в разделе критериев оценки</summary>

**Исходное сообщение**: "1203. If 'analytics.evaluationCriteria.questionPack' is not specified, then 'motivation' and 'recommendation' cannot be true."

**Описание**: Ошибка возникает в случае, если задача на мотивацию оценки по критериям и/или рекомендация по повышению общей оценки активированы без указания непосредственно id набора вопросов.

**Решение**:

* Сначала укажите ID набора вопросов в числовое поле analytics.evaluationCriteria.questionPack
* Проверьте зависимости между полями
* Соблюдайте правильную последовательность заполнения

</details>

<details>

<summary>1204 - Некорректные значения флагов аналитики</summary>

**Исходное сообщение**: "1204. The field '*field.name*' must contain only true or false."

**Описание**: Проверяемые поля принимают только логические значения true или false.

**Проверяемые поля:**&#x20;

* 'analytics.language',
* 'analytics.evaluationCriteria.motivation',
* 'analytics.evaluationCriteria.recommendation',
* 'analytics.customerSatisfaction.motivation',
* 'analytics.customerSatisfaction.recommendation'

**Решение**:

* Используйте только значения true или false
* Проверьте формат данных
* Не используйте null или другие значения. Если вам необходимо оставить поле пустым, то уберите соответствующий ключ из тела запроса.

</details>

<details>

<summary>1205 - Отсутствует внутренний номер сотрудника</summary>

**Исходное сообщение**: "1205. For more comprehensive analytics, please provide the 'employee.intNum' field."

**Описание**: Рекомендуется указывать внутренний номер сотрудника для улучшения качества аналитики и дальнейшего формирования отчетов.

**Решение**:

* Проверьте наличие номера на стороне источника данных
* Заполните поле ''employee.intNum
* Укажите корректный внутренний номер в виде целого числа

</details>

<details>

<summary>1206 - Отсутствует ID отдела</summary>

**Исходное сообщение**: "1206. For more comprehensive analytics, please provide the 'employee.departmentId' field."

**Описание**: Рекомендуется указать идентификатор отдела для улучшения качества аналитики и дальнейшего формирования отчетов.

**Решение**:

* Заполните поле employee.departmentId
* Укажите существующий ID отдела
* Проверьте корректность идентификатора

</details>

<details>

<summary>1207 - Отсутствует обратная ссылка на владельца</summary>

**Исходное сообщение**: "1207. Attached owner entity URL is missing."

**Описание**: Отсутствует ссылка для привязки звонка к материнской сущности на стороне источника данных.

**Решение:**

* Заполните поле call.ownerBacklink
* Укажите корректную ссылку
* Проверьте доступность ресурса

</details>

<details>

<summary>1208 - Некорректный формат ссылки на владельца</summary>

**Исходное сообщение**: "1208. The field 'call.ownerBacklink' must contain a valid URL starting with 'http\://' or 'https\://'."&#x20;

**Описание**: Ссылка на владельца должна быть корректным URL с указанием протокола.

**Решение**:

* Начните URL с http\:// или https\://
* Проверьте правильность написания URL
* Убедитесь в доступности ресурса

</details>

<details>

<summary>1209 - Отсутствует внешний номер</summary>

**Исходное сообщение**: "1209. For more comprehensive analytics, please provide the 'call.extNumber' field."

**Описание**: Рекомендуется указать внешний номер для улучшения качества аналитики.

**Решение**:

* Заполните поле call.extNumber
* Укажите действительный внешний номер
* Проверьте формат номера

</details>

<details>

<summary>1210 - Несуществующий ID элемента в aiokk</summary>

**Исходное сообщение**: "Element with ID {id} not found in aiokk"

**Описание**: Элемент с указанным в вебхуке идентификатором не найден в вашем аккаунте aiokk. Это может быть связано с тем, что элемент был удален или никогда не существовал.

**Проверяемые поля:**&#x20;

* analytics.evaluationCriteria.questionPack,
* analytics.signals,
* analytics.scripts.

**Решение**:

* Убедитесь, что элемент существует в вашем аккаунте aiokk
* Проверьте, не был ли элемент удален
* Проверьте правильность указанного в вебхуке ID элемента aiokk

</details>

<details>

<summary>1211 - Запрос архивного набора вопросов</summary>

**Исходное сообщение**: "1211. The Question Pack you requested is archived"

**Описание**: Запрашиваемый набор вопросов находится в архиве и недоступен для использования. Архивные наборы вопросов нельзя применять в активных оценках.

**Решение**:

* Убедитесь, что вы используете актуальный (не архивный) набор вопросов
* Выберите альтернативный активный набор вопросов
* Проверьте, не был ли набор вопросов недавно перемещен в архив
* При необходимости восстановите набор вопросов из архива

</details>