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

Если вашей системы нет в списке поддерживаемых источников данных, но у вас есть техническая возможность отправлять 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>


---

# 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.aiokk.io/settings/datasource/podderzhivaemye-istochniki/webhook.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.