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

Текущая страница находится в разработке. Материал дополняется...

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

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

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

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

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

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

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

Активация вебхука в разделе Настройки → Источники даных

1. В разделе Настройки → Источник данных выберите в качестве источника Универсальный вебхук.

2. Активируйте вебхук

3. Убедитесь, что вебхук был активирован. Соответствующее состояние будет отображено рядом с заголовком страницы.

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

Внимание!

1. Доступ к данным внутри вашего кабинета обеспечивается посредством верификации через уникальный токен, видимы только в вашем личном кабинете. Никогда не передавайте токен третьим лицам!

2. Техническая поддержка никогда не будет запрашивать токен вашей учетной записи!

Смена токена

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

Кнопка перегенерации токена доступа

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

Очень важно! Если вы ранее задействовали старый токен в своих запросах, то после перегенерации токена вебхуки со старым токеном перестанут работать, и для восстановления работоспособности вебхука вам нужно будет самостоятельно заменить старый токен на новый во всех сценариях, где был задействован старый вебхук, т.к. вебхуки с недействительным токеном перестанут работать, получая в ответе статус 401 (см. подробнее тут).

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

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

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

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

POST 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 и проверьте домен в адресной строке вашего браузера.

   

   Проверка доменной зоны аккаунта aiokk

   В данном конкретном примере, доменная зона - kz

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

Заголовки

Заголовок	Значение
Content-Type	application/json

Тело запроса

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

Блок "call"

Поле	Тип	Обязательность	Описание
uid	string	❌ Нет	Уникальный идентификатор вызова
phone	string	✅ Да	Номер телефона абонента в международном формате (например, [phone])
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	❌ Нет	Идентификатор скрипта, на соответствие которому необходимо оценить разговор (скоро)
markers	boolean	❌ Нет	Маркировка звонка тегами из заданного списка на основе содержания разговора

Обратите внимание! В блоке "analytics" не упоминается параметр, отвечающий за пересказ содержимого звонка, т.к. задание пересказа добавляется к любому составу аналитики по умолчанию. То есть, даже если в составе аналитики не будет указано ни одно задание, пересказ будет произведен в любом случае.

Оставьте массив analytics{} полностью пустым, если хотите запросить аналитику по стандартному составу аналитики, настроенному на стороне личного кабинета aiokk.

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

Тело POST-запроса

{
    "call": {
        "uid": "abcd1234567890asdasdfsdf1231232123123", // Уникальный идентификатор вызова
        "phone": "[phone]", // Номер телефона абонента в международном формате
        "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,  // Тематические маркеры на основе содержания звонка
    }
}

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

В результате выполнения запроса, вы получите ответ от нашей системы. Содержимое ответа может быть разным, в зависимости от статуса и результата проверки тела запроса. Ниже приведены варианты статусов, с которыми может завершиться запрос. Помимо общего статуса, в параметре "message" может прийти дополнительная полезная информация с кодами. Расшифровку кодов и пути решения ошибок вы можете получить ниже в Справочнике.

200

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

401

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

403

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

422

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

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

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

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

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

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

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

1. Указан только параметр "summary":"true". Мы понимаем, что вам нужен только пересказ звонка, и на полученном звонке будет произведен только пересказ.

2. Указано несколько параметров, все прошли проверку на валидацию. Конечный состав аналитики будет соответствовать запрошенному составу в вебхуке. При этом тег "summary" может отсутствовать или быть некорректно заполнен, но пересказ разговора в любом случае будет автоматически добавлен к запрошенному составу аналитики.

3. Указано несколько параметров, но не все параметры прошли проверку на валидацию. Конечный состав аналитики будет состоять только из корректно заполненных параметров, успешно прошедших все проверки на валидацию. При этом тег "summary" может отсутствовать или быть некорректно заполнен, но пересказ разговора в любом случае будет автоматически добавлен к запрошенному составу аналитики.

4. Указано несколько параметров, но ни один параметр не прошел проверку на валидацию. Логика схожа с предыдущим случаем. Если ни один параметр не прошел успешную валидацию, то будет применено задание на пересказ, по умолчанию присутствующее во всех составах аналитики.

5. Пустой массив analytics{}. Именно пустой, а не отсутствующий. Массив обязательно должен быть в теле запроса, так мы поймем, что вы не забыли его прописать, а целенаправленно оставили пустым. Будет применен состав аналитики по умолчанию, настроенный в личном кабинете aiokk в разделе Настройки → Аналитика. Он также включает в себя пересказ звонка.

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

При работе с вебхуками возможно использование набора аналитики по умолчанию, настраиваемого в разделе Настройки → Аналитика.

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

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

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

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

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

Выбор набора вопросов по умолчанию для стандартного набора аналитики

Маяки

Выбор списка маяков по умолчанию для стандартного набора аналитики

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

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

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

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

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

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

Решение:

• Проверьте правильность токена

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

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

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

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

Решение:

• Убедитесь в стабильности сетевого подключения.

• Проверьте правильность настроек файервол.

• Убедитесь, что на странице Настройки → Источник данных статус вебхука указан как "Активный".

Ошибки валидации данных (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-1299) (статус 200)

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 - Некорректные значения флагов аналитики

Исходное сообщение: "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"

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

Решение:

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

• Выберите альтернативный активный набор вопросов

• Проверьте, не был ли набор вопросов недавно перемещен в архив

• При необходимости восстановите набор вопросов из архива