Если вашей системы нет в списке поддерживаемых источников данных, но у вас есть техническая возможность отправлять POST-запросы из своей системы, то вы можете использовать наш универсальный вебхук в качестве "моста" для связи вашего источника данных с нашей системой.
Вебхук – это способ автоматического обмена информацией между системами. Он позволяет одной системе (например, вашей базе данных / телефонии / ERP- или CRM-системе) отправлять данные в другую систему (например, в aiokk) сразу же, как только происходит какое-то событие. В нашем случае таким событием должно быть завершениетелефонного звонка.
Как это работает
Настройте свою систему так, чтобы мы получали через вебхук информацию о новом звонке каждый раз, когда заканчивается телефонный звонок. Вы можете встроить в своей системе отправку данных на наш вебхук только в тех местах, где вам это предусмотрено вашими бизнес-процессами.
Настройки на стороне личного кабинета
Первичная настройка
Для подключения сторонней системы через вебхук необходимо произвести несколько предварительных действий на стороне личного кабинета.
В разделе Настройки → Источник данных выберите в качестве источника Универсальный вебхук.
Активируйте вебхук
Убедитесь, что вебхук был активирован. Соответствующее состояние будет отображено рядом с заголовком страницы.
Скопируйте токен, который далее будете использовать для формирования ссылки для POST-запросов.
Внимание!
Доступ к данным внутри вашего кабинета обеспечивается посредством верификации через уникальный токен, видимы только в вашем личном кабинете. Никогда не передавайте токен третьим лицам!
Техническая поддержка никогда не будет запрашивать токен вашей учетной записи!
Смена токена
Если по каким-либо причинам вам понадобилось изменить токен, то воспользуйтесь специальной кнопкой, чтобы сгенерировать новый токен.
Во всплывающем уведомлении подтвердите перегенерацию токена доступа и дождитесь, когда в поле "Токен доступа" появится новый токен.
Очень важно! Если вы ранее задействовали старый токен в своих запросах, то после перегенерации токена вебхуки со старым токеном перестанут работать, и для восстановления работоспособности вебхука вам нужно будет самостоятельно заменить старый токен на новый во всех сценариях, где был задействован старый вебхук, т.к. вебхуки с недействительным токеном перестанут работать, получая в ответе статус 401 (см. подробнее тут).
Отключение вебхука
В разделе Настройки → Источник данных нажмите на кнопку "Отключить вебхук", если хотите разорвать соединение aiokk c вашим источником данных. Запросы, отправляемые после отключения вебхука, будут завершаться со статусом 403 (подробности см. тут), новые данные не будут попадать в личный кабинет, аналитика новых звонков производиться не будет.
Если в дальнейшем вы снова активируете вебхук, то прежний токен доступа будет по-прежнему работать, и вам ничего не придется перенастраивать.
Метод предназначен для создания нового звонка с подробной информацией о звонке, сотруднике, заданиях аналитики и связанных данных.
Подготовка ссылки эндпоинта
Для подготовки корректной ссылки эндпоинта вам необходимо подставить в приведенный выше URL https://my.aiokk.{domain_zone}/api/v1/{token}/call/new две переменные:
https://my.aiokk.{domain_zone} - соответствует доменной зоне, на которой зарегистрирован ваш кабинет aiokk. Чтобы уточнить вашу доменную зону, авторизуйтесь в своём личном кабинете aiokk и проверьте домен в адресной строке вашего браузера.
В данном конкретном примере, доменная зона - kz
{token} - уникальный токен доступа, видимый только в вашем личном кабинете на странице "Настройки → Источник данных" при выборе вебхука в качестве источника.
Заголовки
Заголовок
Значение
Content-Type
application/json
Тело запроса
Тело запроса представляет собой JSON-объект с тремя основными блоками: call, employee и analytics.
Блок "call"
Поле
Тип
Обязательность
Описание
uid
string
❌ Нет
Уникальный идентификатор вызова
phone
string
✅ Да
Номер телефона абонента в международном формате (например, +77771112233)
duration
int
✅ Да
Длительность звонка в секундах (поддерживается перевод string в integer)
date
datetime with timezone
✅ Да
Дата и время звонка в формате ISO 8601 (например, 2024-12-15T12:25:41+03:00)
type
int
✅ Да
Тип звонка:
1 - Исходящий,
2 - Входящий,
3 - Входящий с переадресацией
4 - Обратный вызов
(поддерживается перевод string в integer)
url
string
✅ Да
Ссылка на запись звонка
extNumber
string
❌ Нет
Внешний номер, на который поступил звонок
ownerBacklink
string
❌ Нет
Ссылка на сущность в вашей системе, к которой подвязан звонок (используется для быстрого перехода из карточки звонка)
Блок "employee"
Поле
Тип
Обязательность
Описание
id
string
❌ Нет
Идентификатор сотрудника
fullName
string
✅ Да
Полное имя сотрудника
intNum
int
❌ Нет
Внутренний номер сотрудника
departmentId
string
❌ Нет
Идентификатор отдела, в котором работает сотрудник
departmentName
string
✅ Да
Название отдела, в котором работает сотрудник
Блок "analytics"
Поле
Тип
Обязательность
Описание
summary
boolean
❌ Нет
Пересказ текста (по умолчанию true). Используйте этот параметр только самостоятельно без других заданий на аналитику, если вам требуется исключительно пересказ звонка. Во всех остальных случаях значение параметра будет проигнорировано и по умолчанию будет принято значение true.
language
boolean
❌ Нет
Определять применяемые языки (по умолчанию false)
customerSatisfaction
object
❌ Нет
Блок задач на определение удовлетворенности клиента (по умолчанию не задействован)
→ assessment
boolean
☝️Условно необязательное
Оценка удовлетворенности клиента (если false, то motivation и recommendation не могут быть true)
→ motivation
boolean
☝️Условно необязательное
Развернутое обоснование оценки удовлетворенности клиента (может быть true, только если assessment - true)
→ recommendation
boolean
☝️Условно необязательное
Рекомендации по повышению оценки удовлетворенности клиента (может быть true, только если assessment - true)
evaluationCriteria
object
❌ Нет
Блок задач на оценку сотрудника по своим критериям (по умолчанию не задействован)
→ questionPack
int
☝️Условно необязательное
Идентификатор набора вопросов для оценки сотрудника (если false, то motivation и recommendation не могут быть true)
→ motivation
boolean
☝️Условно необязательное
Развернутое обоснование оценки по каждому критерию оценки (может быть true, только если assessment - true)
→ recommendation
boolean
☝️Условно необязательное
Рекомендации по повышению оценки удовлетворенности клиента (может быть true, только если assessment - true)
signals
int
❌ Нет
Идентификатор набора маяков для проверки на наличие в разговоре
scripts
int
❌ Нет
Идентификатор скрипта, на соответствие которому необходимо оценить разговор (скоро)
Обратите внимание! В блоке "analytics" не упоминается параметр, отвечающий за пересказ содержимого звонка, т.к. задание пересказа добавляется к любому составу аналитики по умолчанию. То есть, даже если в составе аналитики не будет указано ни одно задание, пересказ будет произведен в любом случае.
Оставьте массив analytics{} полностью пустым, если хотите запросить аналитику по стандартному составу аналитики, настроенному на стороне личного кабинета aiokk.
Пример запроса
Тело POST-запроса
{
"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, // Идентификатор скрипта, на соответствие которому необходимо оценить разговор
}
}
Ответ на запрос
В результате выполнения запроса, вы получите ответ от нашей системы. Содержимое ответа может быть разным, в зависимости от статуса и результата проверки тела запроса. Ниже приведены варианты статусов, с которыми может завершиться запрос. Помимо общего статуса, в параметре "message" может прийти дополнительная полезная информация с кодами. Расшифровку кодов и пути решения ошибок вы можете получить ниже в Справочнике.
{
"status": "success",
"message": "Some warning text or null if not provided"
}
{
"status": "error",
"message": "1000. Unauthorized: token is invalid"
}
{
"status": "Validation error",
"messages":
"1100. The field 'field.name' is required."
}
}
Итоговый набор аналитики
Если ваш запрос получил в ответ статус 200 (в том числе если наряду с ним были получены различного рода предупреждения), значит по отправленному разговору будет произведена аналитика.
Логика формирования итогового набора аналитики
Внимание! Учитывая разнообразие настроек в составе аналитики, а также возможные ошибки, которые могут возникнуть из-за некорректного заполнения полей или нарушения логических взаимосвязей между полями, итоговый набор аналитики может отличаться от первичного состава, указываемого в теле запроса.
Возможные варианты итогового набора аналитики
Возможны следующие варианты в зависимости от корректности заполнения данных в массиве analytics{}.
Указан только параметр "summary":"true". Мы понимаем, что вам нужен только пересказ звонка, и на полученном звонке будет произведен только пересказ.
Указано несколько параметров, все прошли проверку на валидацию. Конечный состав аналитики будет соответствовать запрошенному составу в вебхуке. При этом тег "summary" может отсутствовать или быть некорректно заполнен, но пересказ разговора в любом случае будет автоматически добавлен к запрошенному составу аналитики.
Указано несколько параметров, но не все параметры прошли проверку на валидацию. Конечный состав аналитики будет состоять только из корректно заполненных параметров, успешно прошедших все проверки на валидацию. При этом тег "summary" может отсутствовать или быть некорректно заполнен, но пересказ разговора в любом случае будет автоматически добавлен к запрошенному составу аналитики.
Указано несколько параметров, но ни один параметр не прошел проверку на валидацию. Логика схожа с предыдущим случаем. Если ни один параметр не прошел успешную валидацию, то будет применено задание на пересказ, по умолчанию присутствующее во всех составах аналитики.
Пустой массив analytics{}. Именно пустой, а не отсутствующий. Массив обязательно должен быть в теле запроса, так мы поймем, что вы не забыли его прописать, а целенаправленно оставили пустым. Будет применен состав аналитики по умолчанию, настроенный в личном кабинете aiokk в разделе Настройки → Аналитика. Он также включает в себя пересказ звонка.
Состав аналитики по умолчанию
При работе с вебхуками возможно использование набора аналитики по умолчанию, настраиваемого в разделе Настройки → Аналитика.
Для того, чтобы произвести аналитику звонка по стандартному набору действий, отправьте в вебхуке пустой параметр "analytics": {}
Это послужит для нас сигналом, что вам требуется именно стандартный сценарий аналитики, согласно настройкам в личном кабинете (состав аналитики по умолчанию).
Некоторые задания аналитики, такие как критерии оценки, набор маяков и др., для которых необходима привязка к отдельным сущностям в настройках кабинета, нуждаются в дополнительном уточнении сущности по умолчанию в случае работы по стандартному сценарию аналитики.
Для выбора элемента по умолчанию, применяемого в стандартном наборе аналитики, после активации вебхука необходимо перейти в соответствующий раздел и выбрать элемент по умолчанию.
Критерии оценки
Маяки
Аналогичным образом на соответствующих страницах настроек необходимо указать элемент по умолчанию для остальных заданий, где это предусмотрено.
Справочник кодов ошибок и предупреждений
Ошибки аутентификации и подключения (1000-1099)
1000 - Недействительный токен доступа (статус 401)
Исходное сообщение: 'error': '1000. Unauthorized: token is invalid' (401)
Описание: Предоставленный токен доступа недействителен. Необходимо получить новый токен аутентификации.
Решение:
Проверьте правильность токена
При необходимости получите новый токен на странице Настройки → Источник данных и перенастройте вебхук.
Описание: Сервер отказал в установлении соединения. Это может быть связано с выключенным токеном или проблемами с сетевым подключением.
Решение:
Убедитесь в стабильности сетевого подключения.
Проверьте правильность настроек файервол.
Убедитесь, что на странице Настройки → Источник данных статус вебхука указан как "Активный".
Ошибки валидации данных (1100-1199) (статус 422)
1100 - Некорректные данные запроса
Исходное сообщение: "error": "1100. The field 'field.name' is required."
Описание: Единый код ошибки без привязки к конкретному полю. В запросе отсутствуют обязательные поля. См. раздел "Тело запроса".
Решение:
Проверьте наличие всех обязательных полей в запросе
Убедитесь, что значения полей соответствуют требуемому формату
Сверьтесь с документацией API для уточнения требований к данным
1101 - Некорректный формат даты
Исходное сообщение: "1100. The field 'call.date' must be in ISO 8601 format with timezone."
Описание: Предоставленное значение даты не соответствует требуемому формату ISO 8601 с указанием временной зоны.
Решение:
Проверьте наличие информации о часовом поясе в передаваемой информации.
Убедитесь, что дата указана в формате ISO 8601 (например: "2024-12-31T15:30:00+03:00")
Используйте стандартные библиотеки для форматирования дат
1102 - Неверный тип данных поля call.type
Исходное сообщение: "1102. The field 'call.type' must be an integer."
Описание: Значение поля call.type должно быть целым числом, но предоставлено значение другого типа данных.
Решение:
Убедитесь, что значение является целым числом. Если вы передаете целое число в виде строкового поля, то происходит автоматическое преобразование типа поля.
При необходимости выполните преобразование типа данных на стороне вашего источника данных.
1103 - Недопустимое значение типа звонка
Исходное сообщение: "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)
Проверьте соответствие значения бизнес-логике вашего приложения
1104 - Некорректный формат URL
Исходное сообщение: "1104. The field 'call.url' must be a valid URL starting with http or https."
Описание: Предоставленный URL источника записи звонка не соответствует требуемому формату или не содержит необходимый протокол.
Решение:
Убедитесь, что URL начинается с "http://" или "https://"
Проверьте правильность написания URL
Проверьте наличие всех необходимых компонентов URL (домен, путь и т.д.)
1105 - Некорректное расширение аудиофайла
Исходное сообщение: "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)
Проверьте расширение загружаемого файла
При необходимости конвертируйте файл в поддерживаемый формат перед отправкой вебхука
Убедитесь, что файл не был переименован и действительно содержит аудиоданные в указанном формате
1106 - Некорректный формат длительности звонка
Исходное сообщение: "1106. The field 'call.duration' must be an integer or a numeric string."
Описание: Значение длительности звонка должно быть представлено в виде целого числа или числовой строки. Другие форматы данных не поддерживаются.
Решение:
Убедитесь, что значение длительности передается как целое число (например: 120) или числовая строка (например: "120")
Проверьте, что значение не содержит десятичных дробей
Удалите любые нечисловые символы (буквы, специальные символы)
При необходимости выполните преобразование значения в подходящий формат
1107 - Недопустимые символы в номере телефона
Исходное сообщение: "1107. The field 'call.phone' can only contain digits, '+', '-', '(', and ')'. Spaces and other characters are not allowed."
Описание: В номере телефона обнаружены недопустимые символы. Разрешены только цифры и специальные символы для форматирования номера.
Решение:
Используйте только следующие символы:
Цифры (0-9)
Плюс (+) для международного формата
Дефис (-) для разделения групп цифр
Круглые скобки ( ) для кода города/страны
Удалите все пробелы из номера
Удалите любые другие специальные символы
Проверьте номер на соответствие допустимому формату
1108 - Слишком короткий номер телефона
Исходное сообщение: "1108. The field 'call.phone' must contain at least 3 characters."
Описание: Указанный номер телефона слишком короткий. Минимальная допустимая длина - 3 символа.
Решение:
Убедитесь, что номер телефона содержит не менее 3 символов
Проверьте, не были ли случайно удалены цифры при вводе
Укажите полный номер телефона в соответствии с принятым форматом
1200 - Некорректное значение оценки удовлетворенности
Исходное сообщение: "1200. analytics.customerSatisfaction.assessment can only be true, false, or null."
Описание: Поле оценки удовлетворенности клиента принимает только логические значения или может быть не заполнено.
Решение:
Используйте только значения: true, false или null
Проверьте формат передаваемых данных
Убедитесь, что значение соответствует бизнес-логике
1201 - Некорректный формат ID элемента в aiokk
Исходное сообщение: "1201. The field 'field.name" must be an integer or a numeric string."
Описание: Идентификатор набора вопросов должен быть целым числом или числовой строкой. Другие форматы данных не поддерживаются.
Проверяемые поля:
analytics.evaluationCriteria.questionPack,
analytics.signals,
analytics.scripts.
Решение:
Убедитесь, что значение является целым числом и числовой строкой
Проверьте тип передаваемых данных
При необходимости выполните преобразование типа
1202 - Нарушение логики оценки удовлетворенности клиента
Исходное сообщение: "1202. If 'analytics.customerSatisfaction.assessment' is not true, then 'motivation' and 'recommendation' cannot be true."
Описание: Ошибка возникает в случае, если задача на мотивацию оценки удовлетворенности клиента и/или рекомендация по ее повышению активированы без активации непосредственно задачи на оценку удовлетворенности клиента.
Решение:
Убедитесь, что ваш запрос содержит "analytics.customerSatisfaction.assessment": "true"
Проверьте логическую связь между полями
Убедитесь в последовательности заполнения данных
1203 - Нарушение логики в разделе критериев оценки
Исходное сообщение: "1203. If 'analytics.evaluationCriteria.questionPack' is not specified, then 'motivation' and 'recommendation' cannot be true."
Описание: Ошибка возникает в случае, если задача на мотивацию оценки по критериям и/или рекомендация по повышению общей оценки активированы без указания непосредственно id набора вопросов.
Решение:
Сначала укажите ID набора вопросов в числовое поле analytics.evaluationCriteria.questionPack
Исходное сообщение: "1204. The field 'field.name' must contain only true or false."
Описание: Проверяемые поля принимают только логические значения true или false.
Проверяемые поля:
'analytics.language',
'analytics.evaluationCriteria.motivation',
'analytics.evaluationCriteria.recommendation',
'analytics.customerSatisfaction.motivation',
'analytics.customerSatisfaction.recommendation'
Решение:
Используйте только значения true или false
Проверьте формат данных
Не используйте null или другие значения. Если вам необходимо оставить поле пустым, то уберите соответствующий ключ из тела запроса.
1205 - Отсутствует внутренний номер сотрудника
Исходное сообщение: "1205. For more comprehensive analytics, please provide the 'employee.intNum' field."
Описание: Рекомендуется указывать внутренний номер сотрудника для улучшения качества аналитики и дальнейшего формирования отчетов.
Решение:
Проверьте наличие номера на стороне источника данных
Заполните поле ''employee.intNum
Укажите корректный внутренний номер в виде целого числа
1206 - Отсутствует ID отдела
Исходное сообщение: "1206. For more comprehensive analytics, please provide the 'employee.departmentId' field."
Описание: Рекомендуется указать идентификатор отдела для улучшения качества аналитики и дальнейшего формирования отчетов.
Решение:
Заполните поле employee.departmentId
Укажите существующий ID отдела
Проверьте корректность идентификатора
1207 - Отсутствует обратная ссылка на владельца
Исходное сообщение: "1207. Attached owner entity URL is missing."
Описание: Отсутствует ссылка для привязки звонка к материнской сущности на стороне источника данных.
Решение:
Заполните поле call.ownerBacklink
Укажите корректную ссылку
Проверьте доступность ресурса
1208 - Некорректный формат ссылки на владельца
Исходное сообщение: "1208. The field 'call.ownerBacklink' must contain a valid URL starting with 'http://' or 'https://'."
Описание: Ссылка на владельца должна быть корректным URL с указанием протокола.
Решение:
Начните URL с http:// или https://
Проверьте правильность написания URL
Убедитесь в доступности ресурса
1209 - Отсутствует внешний номер
Исходное сообщение: "1209. For more comprehensive analytics, please provide the 'call.extNumber' field."
Описание: Рекомендуется указать внешний номер для улучшения качества аналитики.
Решение:
Заполните поле call.extNumber
Укажите действительный внешний номер
Проверьте формат номера
1210 - Несуществующий ID элемента в aiokk
Исходное сообщение: "Element with ID {id} not found in aiokk"
Описание: Элемент с указанным в вебхуке идентификатором не найден в вашем аккаунте aiokk. Это может быть связано с тем, что элемент был удален или никогда не существовал.
Проверяемые поля:
analytics.evaluationCriteria.questionPack,
analytics.signals,
analytics.scripts.
Решение:
Убедитесь, что элемент существует в вашем аккаунте aiokk
Проверьте, не был ли элемент удален
Проверьте правильность указанного в вебхуке ID элемента aiokk
1211 - Запрос архивного набора вопросов
Исходное сообщение: "1211. The Question Pack you requested is archived"
Описание: Запрашиваемый набор вопросов находится в архиве и недоступен для использования. Архивные наборы вопросов нельзя применять в активных оценках.
Решение:
Убедитесь, что вы используете актуальный (не архивный) набор вопросов
Выберите альтернативный активный набор вопросов
Проверьте, не был ли набор вопросов недавно перемещен в архив
При необходимости восстановите набор вопросов из архива
