Для работы Вам понадобится ключ (токен) доступа к API.
Ключ позволяет идентифицировать Ваш проект и получать к нему доступ с максимальными привилегиями без необходимости предварительной авторизации каждый раз.
На странице личного кабинета «API» необходимо создать ключ:
Этот ключ необходимо указывать при каждом запросе в заголовке Authorization.
Все относительные пути всех методов, описанных в этой документации, имеют пути относительно: https://api.unitalk.cloud/tracking/api
Все запросы к методам API выполняются в режиме POST.
Пример указания режима, необходимого заголовка авторизации и адреса метода для запроса в Postman выглядит следующим образом:
Также можно отправлять ключ в формате «Bearer *Ваш ключ*»
В случае если заголовок или ключ в нем авторизации будет отсутствовать или указан неверно, результат выполнения метода
будет следующим:
{"status": "Error", "message": "Authorization invalid"}
Любой метод из описанного API может вернуть ошибку:
{"status": "Error", "message": "Internal error"}
О таких ошибках сообщайте, пожалуйста, в техническую поддержку.
В общем случае ошибки выполнения методов имею следующую структуру:
{
"status": "Error",
"message": "*Текст ошибки*",
"data": "*Дополнительная информация*"
}
Далее в этой инструкции будут рассматриваться поля message и data (если присутствует).
Да, мы знаем что в JSON не может быть комментариев, но уверены что так понять будет проще 🙂
Работа с обзвонами выполняется с помощью действий, метод :
Относительный путь: /autodial/action
Режим: POST
Content-Type: application/json
Действия указываются в теле запроса в обязательном параметре action и определяют перечень необходимых параметров. Перечень существующих действий:
GET_LIST | Получить список обзвонов |
GET_WITH_DATA | Получить список обзвонов со всеми данными |
ADD | Добавить обзвон |
UPDATE | Обновить обзвон |
REMOVE | Удалить обзвон |
REFRESH | Прозвонить повторно |
CANCEL | Отменить обзвон |
PAUSE | Поставить на паузу |
UNPAUSE | Снять с паузы |
ADD_NUMBERS | Добавить номера |
GET_NUMBER | Получить информацию про номер обзвона |
GET_NUMBERS | Получить информацию про номера обзвона |
GET_CALLS_HISTORY | Получить информацию про звонки обзвона |
REMOVE_NUMBERS | Удалить номера из обзвона |
REMOVE_ALL_NUMBERS | Удалить все номера из обзвона |
Поскольку данный метод имеет множество вариаций использования и разнообразных параметров, рекомендуется настроить несколько обзвонов в личном кабинете и ознакомиться с их функционалом визуально, прежде чем изучать данную инструкцию.
Возможные ошибки:
Action is null | Целевое действие не указано |
Invalid action | Неверно указано целевое действие |
JSON запроса:
{
"action": "GET_LIST"
}
Пример ответа в случае успеха:
[
{
"id": 111, // Уникальный идентификатор обзвона
"name": "Sample_name", // Название обзвона
"type": "AUTODIAL" // Тип обзвона
},
...
]
Существующие типы обзвонов приведены в соответствующем словаре.
Действие «Получить список обзвонов с дополнительными данными» позволяет получить детальную информацию о текущей конфигурации обзвонов проекта в массиве tasks. Кроме того дополнительно передаются словари, параметры и списки, которые могут понадобиться для интерпретации и изменения конфигураций обзвонов.
Перечень дополнительных списков:
· audios — массив аудиозаписей проекта из раздела «Автообзвоны»
· moh — массив аудиозаписей проекта из раздела «Мелодии ожидания на линии и очередей»
· groups — массив групп внутренних линий проекта
· scenarios — массив входящих сценариев проекта
· outScenarios — массив исходящих сценариев проекта
· ttsSettings — массив профилей настроек синтеза речи проекта
· voiceSecretaries — массив голосовых секретарей проекта
· Массивы triggerActionEventsData и triggerActionEventsAndTriggerActions предоставляют такую информацию о событиях обзвонов как порядковый номер и список доступных обработчиков
Перечень дополнительных словарей:
· triggerActionEvents — прейти к словарю
· taskStatuses — перейти к словарю
· Параметры autodialNumberStatesInfo и statesInfo содержат информацию соответствующую словарю callState в различных представлениях
· autodialerTypes — перейти к словарю
· autodialerModes — перейти к словарю
· audioSynthesisDynamicValues — перейти к словарю
· withdrawalCategories
Перечень дополнительных параметров:
· triggerActionsPresent — указывает на наличие в проекте обработчиков событий
· maxAddNumbersCount — максимальное количество номеров, которое можно добавить за одно действие
· maxRemoveNumbersCount — максимальное количество номеров, которое можно удалить за одно действие
· multiAudiosLimit — максимальное количество элементов в списке compositeAudio
· minMultiAudioSilenceMillis — минимальное количество миллисекунд в элементе silenceMillis массива compositeAudio
· maxMultiAudioSilenceMillis — максимальное количество миллисекунд в элементе silenceMillis массива compositeAudio
JSON запроса:
{
"action": "GET_WITH_DATA"
}
Пример ответа в случае успеха:
{
"audios": { // Массив аудио
"1234": "Sample_audio_name", // "ID": "Название"
...
},
"moh": { // Массив мелодий ожидания на линии
"2345": "Sample_moh_name", // "ID": "Название"
...
},
"groups": { // Массив групп внутренних линий
"3456": "Sample_group_name", // "ID": "Название"
...
},
"scenarios": { // Массив входящих сценариев
"4567": "Main with IVR", // "ID": "Название"
...
},
"outScenarios": { // Массив исходящих сценариев
"5678": "From a fixed number", // "ID": "Название"
...
},
"ttsSettings": { // Массив профилей настроек синтеза речи
"12": "Pretty woman voice", // "ID": "Название"
...
},
"voiceSecretaries": { // Массив голосовых секретарей
"97": "Sample_voice_secretary_name", // "ID": "Название"
...
},
"triggerActionEvents": { // Массив событий для обзвона
"AUTODIAL_FINISH": "Обзвон завершен", // "Событие": "Название"
...
},
"triggerActionEventsData": [ // Информация о событиях обзвонов
{
"event": "AUTODIAL_FINISH", // Событие
"title": "Обзвон завершен", // Название события
"order": 200 // Порядковый номер
},
...
],
"triggerActionEventsAndTriggerActions": { // Списки доступных обработчиков для каждого из событий
"AUTODIAL_FINISH": { // "Событие": {Список доступных обработчиков}
"123": "[Telegram] Personal notification", // "ID": "Название"
...
},
...
},
"triggerActionsPresent": true, // Признак наличия в проекте обработчиков событий
"autodialNumberStatesInfo": { // Информация о состояниях номеров обзвонов
"lang": { // Язык проекта
"locale": "ru",
"shortLocaleCode": "ru",
"code": "RU"
},
"orderedStates": [ // Упорядоченный список состояний на основании порядкового номера
"NEW",
...
],
"statesAndTitles": { // Массив состояний с названиями
"DIALING": "В процессе обзвона",
...
},
"repeatableStates": [ // Список состояний доступных для автоматического повторного прозвона
"BUSY",
...
],
"refreshableStates": [ // Список состояний доступных для метода REFRESH
"FAIL",
...
],
"warningStates": [ // Список состояний свидетельствующих о возможных проблемах в настройках обзвона или телефонии
"AUDIO_ERR",
...
],
"doneStates": [ // Список состояний соответствующих завершенным звонкам
"ANSWER",
...
]
},
"taskStatuses": { // Массив состояний обзвона
"IN_PROGRESS": "В процессе обзвона",
...
},
"autodialerTypes": { // Массив типов обзвонов
"AUTODIAL": "Autodialer",
"GUARANTEED_DIAL": "Guaranteed autodialer",
"VOICE_ROBOT": "Voice robot"
}
"autodialerModes": { // Массив режимов обзвонов
"FIXED": "By number of threads",
"FREE": "By free operators",
"SMART": "Smart selection"
},
"maxAddNumbersCount": 100000, // Максимальное количество номеров, которое можно добавить за одно действие
"maxRemoveNumbersCount": 10000, // Максимальное количество номеров, которое можно удалить за одно действие
"multiAudiosLimit": 20, // Максимальное количество элементов в списке compositeAudio
"minMultiAudioSilenceMillis": 1, // Минимальное количество миллисекунд в элементе silenceMillis массива compositeAudio
"maxMultiAudioSilenceMillis": 10000, // Максимальное количество миллисекунд в элементе silenceMillis массива compositeAudio
"audioSynthesisDynamicValues": { // Массив динамических значений
"NA": "Autodialer number: name",
"NO": "Autodialer number: note",
"LI": "Autodialer number: data for Web Dialer",
"P1": "Autodialer number: parameter #1",
"P2": "Autodialer number: parameter #2",
"P3": "Autodialer number: parameter #3",
"P4": "Autodialer number: parameter #4",
"P5": "Autodialer number: parameter #5",
"P6": "Autodialer number: parameter #6",
"P7": "Autodialer number: parameter #7",
"P8": "Autodialer number: parameter #8",
"P9": "Autodialer number: parameter #9",
"P10": "Autodialer number: parameter #10"
},
"withdrawalCategories": { // Массив категорий списаний обзвонов
"CALL": "Совершение звонков",
"AUTODIALER": "Обзвон",
"VOICE_SECRETARY": "Голосовой секретарь",
"TEXT_TO_SPEECH": "Синтез речи",
"SPEECH_RECOGNITION": "Распознавание речи",
"VOICE_ANALYTICS": "Речевая аналитика",
"ANSWERING_MACHINE_DETECTION": "Распознавание автоответчика",
"MESSAGE_SERVICE_MESSAGE": "Отправка сообщений"
},
"tasks": [ // Массив всех обзвонов
{
"id": 12345, // ID обзвона
"name": "Обзвон окна", // Название обзвона
"autodialerType": "AUTODIAL", // Тип обзвона
"autodialerMode": "FIXED", // Режим обзвона
"statistics": { // Статистика номеров обзвона
"totalCount": 10, // Всего номеров
"doneCount": 6, // Обработано номеров
"repeatCount": 2 // Повторных звонков
"callsDoneCount": // Количество завершенных звонков
"statesCount": { // Статистика номеров по статусам
"NEW": 3, // "ID": Количество
...
}
},
"finishedDate": "2020-04-21", // Дата завершения обзвона. Присутствует в обзвона с состоянием FINISHED
"threadCount": 1, // Количество параллельных звонков. Присутствует в обзвонах с режимом FIXED
"delay": 2, // Пауза между концом воспроизведения аудиозаписи и запуском сценария в секундах. Присутствует в обзвонах с типом AUTODIAL
"smartSpeed": 0, // Регулятор скорости обзвона. Присутствует в обзвонах с режимом SMART
"coldBaseStartCallsMultiplier": null, // Если не null, изменяет количество одновременных звонков в зависимости от процента дозвона с указанным коэффициентом. Присутствует в обзвонах с режимами FREE и SMART
"callDelay": 0, // Пауза между звонками в секундах. Присутствует в обзвонах с режимом FIXED и учитывается только при количестве потоков - 1
"callDelayOnlyAnswered": true, // Пауза между звонками будет срабатывать только после звонков отвеченных оператором. Присутствует в обзвонах с режимом FIXED
"compositeAudio": { // Содержит информацию о комбинированном аудио, которое будет воспроизведено при ответе клиентом на звонок. Присутствует в обзвонах с типом AUTODIAL
"multiAudios": [ // Список частей аудио
{
"silenceMillis": 500 // Длительность тишины в миллисекундах
},
{
"id": 46615 // ID аудиозаписи проекта
},
{
"synthesisFromDynamicValue": { // Данные для синтеза речи
"dynamicValue": "NO", // Динамическое значение, значение которого будет синтезировано
"settingsId": 117 // ID профиля настройки синтеза аудио, который будет использоваться вместо указанного в настройках обзвона. Может быть null
}
}
]
},
"moh": 53, // ID аудио, которое клиент будет слышать ожидая соединение с оператором. Может быть null. Присутствует в обзвонах с типом GUARANTEED_DIAL
"startDate": "2020-03-15", // Дата начала периода проведения обзвона (включительно)
"endDate": "2020-05-15", // Дата окончания периода проведения обзвона (включительно)
"timeFrom": [ // Время начала обзвона по дням недели в формате "HH:mm"
"09:00", // Понедельник
"11:00", // Вторник
"11:00", // Среда
"11:00", // Четверг
"11:00", // Пятница
null, // Суббота, null - обзвон в этот день не работает
"14:00" // Воскресенье
],
"timeTo": [ // Время окончания обзвона по дням недели
"19:00",
"19:00",
"19:00",
"19:00",
"19:00",
null,
"17:00"
],
"voiceSecretaryId": 25 // ID голосового секретаря. Присутствует в обзвонах с типом VOICE_ROBOT
"groupId": 300, // ID отдела телефонии на который будут перенаправляться звонки обзвона. Присутствует в обзвонах с типом GUARANTEED_DIAL или режимами FREE и SMART
"scenarioId": null, // ID входящего сценария, который будет активирован, если клиент останется на линии после завершения аудио. Может быть null. Присутствует в обзвонах с типом AUTODIAL
"outScenarioId": null, // ID исходящего сценария, который будет использован для звонков обзвона. Может быть null.
"pauseOperatorNoAnswerLimit": 5, // Количество звонков подряд не отвеченных оператором, после которого он будет поставлен на паузу. Может быть null. Присутствует в обзвонах с режимами FREE и SMART
"ttsSettingsId": 18, // ID профиля настроек синтеза речи. Может быть null. Присутствует в обзвонах с типами AUTODIAL и GUARANTEED_DIAL
"useTaskAudioIfAudioError": false, // При ошибке аудио: true - “Использовать аудио обзвона”, false - “Завершить звонок с ошибкой”. Присутствует в обзвонах с типами AUTODIAL и GUARANTEED_DIAL
"repeatCallAttempts": 3, // Количество повторных прозвонов. Значения 0 и null означают, что повторный прозвон отключен
"repeatCallIntervalMinutes": 30, // Минимальный интервал повторных прозвонов в минутах
"repeatCallHighPriority": false, // Значение true указывает на необходимость внесения повторных прозвонов в приоритетную очередь
"repeatCallStates": [ // Список статусов звонков, которые будут повторно прозваниваться. Если пустой или null - повторный прозвон отключён
"NOANSWER",
...
],
"callerIdPrefix": null, // Префикс, который будет отображаться в SIP клиенте перед номером телефона. Может быть null
"crmMode": "DONT_SEND", // Определяет какие звонки будут отправлены в CRM
"clientCalledMode": "NEVER", // Указывает на необходимость игнорировать номера абонентов, от которых поступали звонки
"displayName": false, // Указывает на необходимость показывать имя закрепленное за номером в SIP клиенте
"displayNote": false, // Указывает на необходимость показывать примечание к номеру в SIP клиенте
"removeAfterFinish": false, // Указывает на необходимость удалить обзвон после завершения
"markAsBusySeconds": 60, // Количество секунд на которое SIP линия отмечается занятой после успешного звонка. Присутствует в обзвонах с режимами FREE и SMART
"markAsBusyMinSecondsTalk": 15, // Минимальная длительность звонка для срабатывания настройки markAsBusySeconds в секундах. Присутствует в обзвонах с режимами FREE и SMART
"reservedSipsBusyOnlyForAutodials": true, // Указывает на доступность внутренних линий для звонков, поступающих по входящим сценариям. Присутствует в обзвонах с режимами FREE и SMART
"triggerActions": { // Список событий и обработчиков за ними закрепленными
"AUTODIAL_NOANSWER": [ // Событие
2, // ID обработчика событий
...
],
...
},
"withdrawalStatistics": { // Массив с информацией про общие траты обзвона
"total": "12.47", // Сумма списаний по всем категориям
"byCategories": { // Массив сумм списаний по категориям
"CALL": "0.60",
...
}
},
"taskStatusInfo": { // Информация о статусе обзвона
"millis": 1631828328839,
"status": "FINISHED",
"dateForDescription": "2021-09-08",
"durationMillis": 36253180657
}
},
...
],
"statesInfo": [ // Информация о статусах звонков обзвона
{
"state": "NEW", // ID статуса
"order": 10, // Порядковый номер
"title": "Не обработано", // Название статуса
"repeatable": false, // Доступен для автоматического повторного прозвона (поле repeatCallStates)
"refreshable": false, // Доступен для метода REFRESH
"warning": false // Свидетельствует о возможных проблемах в настройках обзвона или телефонии
},
...
]
}
Действия «Создать» и «Изменить» позволяют конфигурировать новый или существующий обзвоны соответственно. Часть параметров является общей для всех типов и режимов обзвонов. Создание и изменение обзвонов будет рассмотрено на примере одного запроса, поскольку различия незначительны:
· id — Уникальный идентификатор изменяемого обзвона не учитывается при создании
· autodialerType — Тип обзвона не учитывается при изменении
· При создании обзвона можно опционально передать перечень номеров для обработки в параметре numbers и указать необходимость их обработки в приоритетной очереди в параметре highPriority. Номера в массиве numbers необходимо указывать в международном формате, все сторонние символы будут предварительно удалены. Для добавления номеров в существующий обзвон используйте действие ADD_NUMBERS.
crmMode определяет информация о каких звонках будет передана в CRM. Доступные значения:
· DONT_SEND — Никакие
· SEND_ANSWERED — Отвеченные абонентом
· SEND_SUCCESS — Отвеченные абонентом и оператором
· ALL_CALLS — Все
clientCalledMode указывает на необходимость игнорировать номера абонентов, от которых поступали звонки. Доступные значения:
· NEVER — Никогда
· ANSWERED_CALLS — Только если звонок отвечен
· ALL_CALLS — Всегда
Пример общей части JSON запроса:
{
"action": "ADD", // Или "UPDATE"
"task": {
"id": 0, // ID существующего обзвона для "UPDATE". При "ADD" не учитывается
"name": "Обзвон", // Должно быть уникальным
"autodialerType": "AUTODIAL", // Тип обзвона. При "UPDATE" не учитывается
"autodialerMode": "FIXED", // Режим обзвона
"startDate": "2020-03-15", // Дата начала периода проведения обзвона (включительно)
"endDate": "2020-05-15", // Дата окончания периода проведения обзвона (включительно)
"timeFrom": [ // Время начала обзвона по дням недели в формате "HH:mm". Может быть null
"09:00", // Понедельник
"11:00", // Вторник
"11:00", // Среда
"11:00", // Четверг
"11:00", // Пятница
null, // Суббота, null - обзвон в этот день не работает
"14:00" // Воскресенье
],
"timeTo": [ // Время окончания обзвона по дням недели
"19:00",
"19:00",
"19:00",
"19:00",
"19:00",
null,
"17:00"
],
"outScenarioId": 567, // ID исходящего сценария, который будет использован для звонков обзвона. Может быть null
"triggerActions": { // Список событий и обработчиков за ними закрепленными. К одному событию можно прикрепить максимум 5 обработчиков
"AUTODIAL_NOANSWER": [ // Событие
2, // ID обработчика событий
...
],
...
},
"callerIdPrefix": "pref", // Префикс, который будет отображаться в SIP клиенте перед номером телефона. Может быть null
"crmMode": "DONT_SEND", // Определяет какие звонки будут отправлены в CRM
"clientCalledMode": "NEVER", // Указывает на необходимость игнорировать номера абонентов, от которых поступали звонки
"repeatCallAttempts": 3, // Количество повторных прозвонов. Доступны значения от 0 до 10. Значения 0 и null отключают повторный прозвон
"repeatCallIntervalMinutes": 10, // Минимальный интервал повторных прозвонов в минутах. Доступны значения от 5 до 1500
"repeatCallHighPriority": false, // Значение true указывает на необходимость внесения повторных прозвонов в приоритетную очередь
"repeatCallStates": [ // Список статусов звонков, которые будут повторно прозваниваться. Может быть пустым или null, если repeatCallAttempts равно 0 или null
"NOANSWER",
...
],
"displayName": true, // Показывать имя закрепленное за номером в SIP клиенте
"displayNote": false, // Показывать примечание к номеру в SIP клиенте
"removeAfterFinish": false, // Удалить обзвон после завершения
"numbers":[ // Массив номеров для обзвона. При "UPDATE" не учитывается. Может быть null
"+38(097)11-11 111",
...
],
"highPriority": true // Указывает на необходимость добавления номеров с высоким приоритетом. Такие номера обзваниваются в первую очередь. При "UPDATE" не учитывается
...
}
}
Тип создаваемого или изменяемого обзвона влияет на перечень обязательных и допустимых параметров, которые будут рассмотрены отдельно.
Для обзвонов с типом AUTODIAL обязательно наличие одного из параметров compositeAudio и scenarioId. Параметр compositeAudio должен содержать объект multiAudios который представляет собой массив, который используется для указания аудио. Каждый элемент массива multiAudios представляет собой ссылку аудиозапись в проекте (id), тишину (silenceMillis) или синтез аудио (synthesisFromDynamicValue). Синтез аудио должен содержать параметр dynamicValue, значение которого — соответствует одному из ключей соответствующего словаря. Порядок расположения аудио в массиве соответствует порядку воспроизведения. Для корректного синтеза аудио обязательно наличие одного из параметров settingsId части синтеза и ttsSettingsId обзвона.
Пример специфической для типа обзвона AUTODIAL части JSON запроса:
...
"scenarioId": 70, // ID входящего сценария, который будет активирован, если клиент останется на линии после завершения аудио
"compositeAudio": { // Содержит информацию о комбинированном аудио, которое будет воспроизведено при ответе клиентом на звонок
"multiAudios": [ // Список частей аудио
{
"silenceMillis": 500 // Длительность тишины в миллисекундах
},
{
"id": 46615 // ID аудиозаписи проекта
},
{
"synthesisFromDynamicValue": { // Данные для синтеза речи
"dynamicValue": "NO", // Динамическое значение, значение которого будет синтезировано
"settingsId": 117 // ID профиля настройки синтеза аудио, который будет использоваться вместо указанного в настройках обзвона. Может быть null
}
}
]
},
"ttsSettingsId": 18, // ID профиля настроек синтеза речи для обзвона. Может быть null
"useTaskAudioIfAudioError": true, // При ошибке аудио: true - “Использовать аудио обзвона”, false - “Завершить звонок с ошибкой”
"delay": 2, // Пауза между концом воспроизведения аудио обзвона и запуском входящего сценария в секундах. Может быть 0
...
Для обзвонов с типом GUARANTEED_DIAL обязательно указание группы внутренних линий в параметре groupId.
Пример специфической для типа обзвона GUARANTEED_DIAL части JSON запроса:
...
"moh": 255, // ID аудио, которое клиент будет слышать ожидая соединение с оператором. Может быть null
"groupId": 300, // ID отдела телефонии на который будут перенаправляться звонки обзвона
"ttsSettingsId": 18, // ID профиля настроек синтеза речи для обзвона. Может быть null
"useTaskAudioIfAudioError": true, // При ошибке аудио: true - “Использовать аудио обзвона”, false - “Завершить звонок с ошибкой”
...
Для обзвонов с типом VOICE_ROBOT обязательно указание голосового секретаря в параметре voiceSecretaryId.
Пример специфической для типа обзвона VOICE_ROBOT части JSON запроса:
...
"voiceSecretaryId": 25 // ID голосового секретаря
...
Режим создаваемого или изменяемого обзвона влияет на перечень обязательных и допустимых полей, которые будут рассмотрены отдельно.
Для обзвонов с режимом FIXED обязательно указание количества параллельных звонков (потоков) в параметре threadCount.
Пример специфической для режима обзвона FIXED части JSON запроса:
...
"threadCount": 1, // Количество параллельных звонков
"callDelay": 30, // Пауза между звонками в секундах. Учитывается только при количестве параллельных звонков - 1
"callDelayOnlyAnswered": true, // Пауза между звонками будет срабатывать только после звонков отвеченных оператором
...
Для обзвонов с режимом FREE обязательно указание группы внутренних линий в параметре groupId. Кроме того доступны дополнительные параметры:
· coldBaseStartCallsMultiplier — Изменяет количество одновременных звонков в зависимости от процента дозвона с указанным коэффициентом. Доступны значения от 0.1 до 1.5
· pauseOperatorNoAnswerLimit — Количество звонков подряд не отвеченных оператором, после которого он будет поставлен на паузу
· markAsBusySeconds — Количество секунд на которое SIP линия отмечается занятой после успешного звонка. Доступны значения от 0 до 3600
· markAsBusyMinSecondsTalk — Минимальная длительность звонка для срабатывания настройки markAsBusySeconds в секундах. Доступны значения от 0 до 3600
· reservedSipsBusyOnlyForAutodials — Определяет будут ли внутренние линии из закрепленной группы обзвона доступны для звонков, поступающих по входящим сценариям
Пример специфической для режима обзвона FREE части JSON запроса:
...
"groupId": 300, // ID отдела телефонии на который будут перенаправляться звонки обзвона
"coldBaseStartCallsMultiplier": null, // Изменяет количество одновременных звонков в зависимости от процента дозвона с указанным коэффициентом
"pauseOperatorNoAnswerLimit": 5, // Количество звонков подряд не отвеченных оператором, после которого он будет поставлен на паузу
"markAsBusySeconds":60, // Количество секунд на которое SIP линия отмечается занятой после успешного звонка
"markAsBusyMinSecondsTalk":15, // Минимальная длительность звонка для срабатывания настройки markAsBusySeconds в секундах
"reservedSipsBusyOnlyForAutodials": true, // Указывает на доступность внутренних линий для звонков, поступающих по входящим сценариям
...
Для обзвонов с режимом SMART обязательно указание группы внутренних линий в параметре groupId. Кроме того доступны дополнительны параметры:
· coldBaseStartCallsMultiplier — Изменяет количество одновременных звонков в зависимости от процента дозвона с указанным коэффициентом. Доступны значения от 0.1 до 1.5
· pauseOperatorNoAnswerLimit — Количество звонков подряд не отвеченных оператором, после которого он будет поставлен на паузу
· markAsBusySeconds — Количество секунд на которое SIP линия отмечается занятой после успешного звонка. Доступны значения от 0 до 3600
· markAsBusyMinSecondsTalk — Минимальная длительность звонка для срабатывания настройки markAsBusySeconds в секундах. Доступны значения от 0 до 3600
· reservedSipsBusyOnlyForAutodials — Определяет будут ли внутренние линии из закрепленной группы обзвона доступны для звонков, поступающих по входящим сценариям
· smartSpeed — Допустимые значения от -10 до 10 пропорционально влияют на скорость обзвона
Пример специфической для режима обзвона SMART части JSON запроса:
...
"groupId": 300, // ID отдела телефонии на который будут перенаправляться звонки обзвона
"coldBaseStartCallsMultiplier": null, // Изменяет количество одновременных звонков в зависимости от процента дозвона с указанным коэффициентом
"pauseOperatorNoAnswerLimit": 5, // Количество звонков подряд не отвеченных оператором, после которого он будет поставлен на паузу
"markAsBusySeconds":60, // Количество секунд на которое SIP линия отмечается занятой после успешного звонка
"markAsBusyMinSecondsTalk":15, // Минимальная длительность звонка для срабатывания настройки markAsBusySeconds в секундах
"reservedSipsBusyOnlyForAutodials": true, // Указывает на доступность внутренних линий для звонков, поступающих по входящим сценариям
"smartSpeed": 5, // Допустимые значения от -10 до 10 пропорционально влияют на скорость обзвона
...
Пример ответа в случае успеха:
{"status": "Success", "data": 12345}
При выполнении действия ADD в поле data передается id созданного обзвона.
Возможные ошибки:
task is null | Поле task не указано в запросе |
Please confirm phone number | Неподтвержденные проекты не могут создавать обзвоны |
Billing not allow | На данном тарифе обзвон недоступен, либо тариф не оплачен |
Task not found | Обзвон не найден по id при UPDATE |
groupId is null | Тип обзвона GUARANTEED_DIAL или режим FREE или SMART, но поле groupId не указано в запросе |
Group not found | Тип обзвона GUARANTEED_DIAL или режим FREE или SMART, но группа операторов с указанным id не найдена |
Wrong group type | Тип обзвона GUARANTEED_DIAL или режим FREE или SMART, но указанная группа не является группой внутренних линий |
Moh not found | Тип обзвона GUARANTEED_DIAL, но аудио мелодии ожидания не найдено по указанному id |
Wrong audio type: moh | Тип обзвона GUARANTEED_DIAL, но по указанному id найдено аудио другой категории |
In scenario not found | Тип обзвона AUTODIAL, но входящий сценарий по указанному id не найдено |
Not found in scenario and audio | Тип обзвона AUTODIAL, но ни аудио, ни входящий сценарий не указаны в запросе |
voiceSecretaryId is null | Тип обзвона VOICE_ROBOT, но голосовой секретарь не указан в запросе |
Voice secretary not found | Тип обзвона VOICE_ROBOT, но голосовой секретарь по указанному id не найдено |
compositeAudio | Ошибка при указании комбинированного аудио в обзвонах типа AUTODIAL. Возможные причины: · too many audio parts — в комбинированном аудио указано более 20 частей · audio not found — аудио не найдено по указанному id · audio type is not AUTODIAL — по указанному id найдено аудио другой категории · synthesis dynamicValue is null — в элементе синтеза речи не указан параметр dynamicValue · speech synthesis settings not found — по указанному settingsId не найден профиль настроек синтеза аудио · invalid silenceMillis — Значение silenceMillis не в диапазоне от 1 до 10 000 |
Wrong name | Название не может быть пустым или длиннее 45 символов |
Name already present | Обзвон с таким названием уже существует в проекте |
Not found out scenario | По указанному id не найден исходящий сценарий |
Wrong dates | Даты обзвона не указаны, или дата старта обзвона превышает дату окончания |
Wrong time ranges | В массиве timeFrom или timeTo не 7 элементов, в какой либо паре timeFrom позже чем timeTo или все элементы null |
Prefix is too long | Префикс не должен превышать 20 символов |
Handler is busy, try again later | Один проект одновременно может удалять или добавлять номера только в одном обзвоне. В этот момент в одном из обзвонов проекта происходит удаление или добавление номеров. Повторите попытку позже, когда предыдущая операция завершится. Может возникнуть только если указан параметр numbers при действии ADD |
Wrong numbers | В массиве numbers присутствуют некорректные номера. В поле data будет указан массив элементов numbers, которые не прошли валидацию |
Repeat call states is empty | repeatCallAttempts указывает на необходимость автоматического прозвона номеров, но repeatCallStates пустой или null |
Repeat call state is not allowed | В массиве repeatCallStates был передан недопустимый callState |
Not found text to speech settings | По указанному id не найден профиль настройки синтеза аудио |
Wrong trigger action event | В массиве triggerActions передан недопустимый triggerActionEvent или null |
triggerActionIds is null | В массиве triggerActions у одного из triggerActionEvent недопустимое значение null |
Too many trigger actions | В массиве triggerActions для одного из triggerActionEvent передан массив с более чем 5 обработчиками |
Trigger action not found | По одному из указанных в triggerActions id не найден обработчик |
Few trigger actions with same type | В массиве triggerActions для одного из triggerActionEvent указано 2 обработчика событий с одинаковым типом действия |
Not compatible trigger action | В массиве triggerActions для одного из triggerActionEvent указан id обработчика событий, который несовместим с этим triggerActionEvent |
crmMode is null | Поле crmMode не указано в запросе |
clientCalledMode is null | Поле clientCalledMode не указано в запросе |
Tasks limit exceeded | Превышено максимальное количество обзвонов в проекте |
Пример JSON запроса:
{
"id": 1307, // ID целевого обзвона
"action": "REMOVE"
}
Ответ в случае успеха:
{"status": "Success", "message": "Removed"}
Возможные ошибки:
Task not found | Обзвон не найден по указанному id |
Handler is busy, try again later | Один проект одновременно может удалять или добавлять номера только в одном обзвоне. В этот момент в одном из обзвонов проекта происходит удаление или добавление номеров. Повторите попытку позже, когда предыдущая операция завершится |
Действие «Прозвонить повторно» позволяет перезапустить обработку номеров находящихся в указанных статусах. Перечень статусов допустимых для использования в данном действии приведен в соответствующем словаре.
Пример JSON запроса:
{
"id": 1307, // ID целевого обзвона
"action": "REFRESH",
"callStates": [ // Массив статусов, номера в которых будут прозвонены повторно
"NOANSWER",
...
]
}
Ответ в случае успеха:
{"status": "Success"}
Успешное выполнение данного действия изменит статус выбранных номеров на NEW.
Возможные ошибки:
Task not found | Обзвон не найден по указанному id |
states is null or empty | Массив callStates пустой или null |
state is not allowed | В массиве callStates указан недопустимый для REFRESH статус |
Try again later | Предыдущее выполнение действия для указанного обзвона произошло менее минуты назад |
Numbers not found by states | Не найдено ни одного номера с указанными статусами |
Действие «Отменить обзвон» позволяет остановить обзвон, находящийся в статусе WAITING, IN_PROGRESS или PAUSED. Применение этого действия к обзвонам в статусах FINISHED и CANCELED приведет к ошибке. Применение к NEW — не приведет к каким-либо изменениям.
Пример JSON запроса:
{
"id": 1307, // ID целевого обзвона
"action": "CANCEL"
}
Ответ в случае успеха:
{"status": "Success", "message": "Cancelled"}
Успешная отмена изменит статус на CANCELED (пока в обзвоне будут незавершенные звонки), впоследствии статус изменится на FINISHED
Возможные ошибки:
Task not found | Обзвон не найден по указанному id |
Task is finished | Невозможно отменить обзвон со статусом FINISHED |
Task is canceled | Невозможно отменить обзвон со статусом CANCELED |
Действие «Поставить на паузу» позволяет приостановить обзвон, находящийся в статусе WAITING или IN_PROGRESS. Применение этого действия к обзвонам в статусах FINISHED и CANCELED приведет к ошибке. Применение к NEW или PAUSED — не приведет к каким-либо изменениям.
Пример JSON запроса:
{
"id": 1307, // ID целевого обзвона
"action": "PAUSE"
}
Ответ в случае успеха:
{"status": "Success"}
Успешная постановка на паузу изменит статус с WAITING или IN_PROGRESS на PAUSED.
Возможные ошибки:
Task not found | Обзвон не найден по указанному id |
Task is finished | Невозможно поставить на паузу обзвон со статусом FINISHED |
Task is canceled | Невозможно поставить на паузу обзвон со статусом CANCELED |
Действие «Cнять с паузы» позволяет продолжить обзвон, находящийся в статусе PAUSED. Применение этого действия к обзвонам в статусах FINISHED и CANCELED приведет к ошибке. Применение к NEW, WAITING или IN_PROGRESS — не приведет к каким-либо изменениям.
Пример JSON запроса:
{
"id": 1307, // ID целевого обзвона
"action": "UNPAUSE"
}
Ответ в случае успеха:
{"status": "Success"}
Успешное снятие с паузы изменит статус с PAUSED на WAITING или IN_PROGRESS.
Возможные ошибки:
Task not found | Обзвон не найден по указанному id |
Task is finished | Невозможно снять с паузы обзвон со статусом FINISHED |
Task is canceled | Невозможно снять с паузы обзвон со статусом CANCELED |
Действие «Добавить номера» позволяет добавить номера в обзвон двумя способами: указав только номера в массиве numbers или номера с дополнительной информацией в массиве numbersWithData. В случае если указаны оба, будут добавлены номера из обоих массивов. За один запрос возможно добавить до 100 000 номеров, но не более 1 000 000 номеров на один обзвон.
В запросе должен присутствовать один из параметров numbers и numbersWithData. Номера в массиве numbers или параметре phone необходимо указывать в международном формате, все сторонние символы будут предварительно удалены. Массив numbersWithData позволяет передавать номера в виде элементов с дополнительными параметрами, единственным обязательным параметром является phone.
Параметр audios представляет собой массив, который используется для указания аудио, которые будут воспроизведены вместо основного аудио обзвона. Каждый элемент массива audios представляет собой ссылку на аудиозапись в проекте (id) или синтез аудио (tts). В элементе должен присутствовать один из параметров id и tts, если указаны оба будет использован id. Порядок расположения аудио в массиве соответствует порядку воспроизведения. Для типа обзвона AUTODIAL максимум элементов — 5 (из которых 2 синтеза аудио), для GUARANTEED_DIAL — 1, для VOICE_ROBOT параметр игнорируется.
Для типа обзвона AUTODIAL id должен указывать на аудиозапись из раздела «Автообзвоны», для GUARANTEED_DIAL — «Мелодии ожидания». В элементе tts должен присутствовать один из параметров text и ssml, если указаны оба будет использован ssml, максимальное количество символов — 2500. Параметр ssml должен начинаться и заканчиваться тегом speak. Процесс озвучивания происходит перед стартом звонка. Синтезированные аудио хранятся до 7 дней по завершению обзвона, не более 3 месяцев с момента создания и в списке аудиозаписей проекта не отображаются. В случае, если синтезированный текст и профиль настроек совпадают — используется ранее синтезированное аудио.
Пример JSON запроса:
{
"id": 1307, // ID целевого обзвона
"action": "ADD_NUMBERS",
"refreshDuplicates": true, // Указывает на необходимость повторно обработать номера, которые уже присутствуют в обзвоне
"highPriority": true, // Указывает на необходимость обрабатывать добавляемые номера в первую очередь
"numbers": [ // Массив номеров, которые необходимо добавить
"380970000001",
...
],
"numbersWithData": [ // Массив номеров с дополнительной информацией, которые необходимо добавить
{
"phone": "380670000002",
"name": "sample_name", // Имя. Учитываются первые 100 символов. Может быть null
"note": "sample_note", // Примечание. Учитываются первые 500 символов. Может быть null
"link": "https://...", // Данные для Web Dialer. Учитываются первые 500 символов. Может быть null
"params": { // Параметры которые будут закреплены за номером в обзвоне. Может быть null
"1": "sample_value", // Номер параметра (1-10): Значение параметра. Учитываются первые 500 символов. Может быть null
...
},
"audios": [ // Массив аудиозаписей и синтеза аудио, которые будут проиграны при звонке на номер вместо основного аудио обзвона. Может быть null
{
"id": 4953, // ID целевой аудиозаписи
},
{
"tts": { // Данные для синтеза аудио
"text": "sample_text", // Текст который будет озвучен
"ssml": "<speak>sample_text</speak>", // Текст который будет озвучен в формате ssml
"settingsId": 18 // ID профиля настройки синтеза аудио, который будет использоваться вместо указанного в настройках обзвона. Может быть null
}
},
...
]
},
...
]
}
Пример ответа в случае успеха:
{"status": "Success", "message": "Numbers added"}
Успешное добавление номеров в завершенный обзвон (FINISHED) изменит статус на WAITING или IN_PROGRESS.
Возможные ошибки:
Task not found | Обзвон не найден по указанному id |
Numbers is null or empty | numbers и numbersWithData пустые или null |
Too many numbers | Превышен лимит в 100 000 номеров за одно действие |
Numbers limit exceeded | Превышен лимит в 1 000 000 номеров в обзвоне |
Handler is busy, try again later | Один проект одновременно может удалять или добавлять номера только в одном обзвоне. В этот момент в одном из обзвонов проекта происходит удаление или добавление номеров. Повторите попытку позже, когда предыдущая операция завершится |
Wrong numbers | В массиве numbers присутствуют некорректные номера. В поле data будет указан массив элементов numbers, которые не прошли валидацию |
Numbers not added | Не было сохранено ни одного номера |
Wrong audios | В массиве numbersWithData присутствуют номера с некорректным audios. В поле data будет указан массив номеров с соответствующей ошибкой аудио. Возможные причины ошибки: · Too many audios — слишком много элементов · Too many text to speech — слишком много элементов с синтезом аудио · Audio is null — присутствуют элементы со значением null · Audio not found by id — присутствуют id по которым не найдена аудиозапись · Wrong type of audio — присутствуют id который указывает аудиозапись недопустимого раздела · Text to speech ‘text’ and ‘ssml’ is null — присутствуют tts в которых оба text и ssml пустые · Text to speech ‘text’ not valid — присутствуют tts в которых text превышает 2500 символов · Text to speech ‘ssml’ not valid — присутствуют tts в которых ssml превышает 2500 символов или не начинается и заканчивается тегом speak · Text to speech settings not found by id — присутствуют tts в которых по указанному settingsId не найден профиль настроек синтеза аудио · Audio is empty — присутствуют элементы в которых оба tts и id имеют значение null |
Too many params | В params передано более 10 параметров |
Wrong parameter key | В params передан ключ, который не является числом из диапазона от 1 до 10 |
Пример JSON запроса:
{
"id": 1307, // ID целевого обзвона
"action": "GET_NUMBER",
"number": "380971234567" // Номер телефона
}
Пример ответа в случае успеха:
{
"id": 110232, // ID номера обзвона
"taskId": 18700, // ID обзвона
"phone": "380441234567", // Номер телефона
"state": "ANSWER", // Статус последнего звонка обзвона по этому номеру
"stateDateTime": "2020-09-10 05:47:15" // Дата завершения последнего звонка обзвона по этому номеру
"calledCount": 0, // Количество звонков на этот номер с последнего запуска обзвона
"realCalledCount": 0, // Количество звонков на этот номер в обзвоне
"highPriority": false, // Указывает находиться ли номер в приоритетной очереди
"name": null, // Имя закрепленное за номером в обзвоне
"note": "9049", // Заметка закрепленная за номером в обзвоне
"link": "https://...", // Данные для Web Dialer закрепленные за номером в обзвоне
"params": { // Параметры закрепленные за номером в обзвоне
"1": "sample_value", // Номер параметра (1-10): Значение параметра
...
},
"audios": [ // Аудио закрепленные за номером в обзвоне
{
"id": 46644 // ID аудиозаписи
},
{
"tts": { // Параметры синтеза речи
"text": "sample_text",
"settingsId": 107
}
}
]
}
Возможные ошибки:
Task not found | Обзвон не найден по указанному id |
Wrong phone number | Номер телефона некорректный |
Call not found | Номер не найден в обзвоне |
Для получения информации про все номера обзвона необходимо указать id целевого обзвона. Количество записей, которые будут получены при этом не превышает значение параметра limit. По умолчанию limit равен 1000, максимальное значение — 5000. Для получения следующей группы записей, необходимо в параметре offest указать сдвиг относительно начала списка. Кроме того, записи можно предварительно отфильтровать по целевым статусам номеров, перечень которых приведен в соответствующем словаре.
Пример JSON запроса:
{
"id": 1307, // ID целевого обзвона
"action": "GET_NUMBERS",
"limit": 2000, // Максимальное количество номеров, которые будут возвращены в ответе
"offset": 4000, // Сдвиг возвращаемых записей относительно начала списка
"callStates": [ // Фильтр по callState. Может быть null или пустой
"NOANSWER",
...
]
}
Пример ответа в случае успеха:
[ // Массив номеров обзвона с дополнительной информацией
{
"id": 110232, // ID номера обзвона
"taskId": 18700, // ID обзвона
"phone": "380441234567", // Номер телефона
"state": "ANSWER", // Статус последнего звонка обзвона по этому номеру
"stateDateTime": "2020-09-10 05:47:15" // Дата завершения последнего звонка обзвона по этому номеру
"calledCount": 0, // Количество звонков на этот номер с последнего запуска обзвона
"realCalledCount": 0, // Количество звонков на этот номер в обзвоне
"highPriority": false, // Указывает находиться ли номер в приоритетной очереди
"name": null, // Имя закрепленное за номером в обзвоне
"note": "9049", // Заметка закрепленная за номером в обзвоне
"link": "https://...", // Данные для Web Dialer закрепленные за номером в обзвоне
"params": { // Параметры закрепленные за номером в обзвоне
"1": "sample_value", // ID: Значение параметра
...
},
"audios": [ // Аудио закрепленные за номером в обзвоне
{
"id": 46644 // ID аудиозаписи
},
{
"tts": { // Параметры синтеза речи
"text": "sample_text",
"settingsId": 107
}
}
]
},
...
]
Возможные ошибки:
Task not found | Обзвон не найден по указанному id |
Limit range is 1-5000 | Значение limit не в диапазоне от 1 до 5000 |
Offset cannot be negative | Значение offset должно быть положительным |
Для получения информации про звонки обзвона необходимо, кроме действия, указать параметр callHistoryRequest. callHistoryRequest не может быть null, но может быть пустым. Записи возвращаются в порядке убывания id.
Количество записей, которые будут получены при этом не превышает значение параметра limit. По умолчанию limit равен 50, максимальное значение — 1000. Для получения следующей группы записей можно воспользоваться одним из двух способов:
· В параметре offest указать сдвиг относительно начала списка;
· В параметре maxId указать максимальный (включительно) id записи, которая будет возвращена.
Записи звонков можно предварительно отфильтровать параметрами:
· dateFrom — минимальная дата и время звонка (включительно) в формате “yyyy-MM-dd HH:mm:ss”;
· dateTo — максимальная дата и время звонка (невключительно) в формате “yyyy-MM-dd HH:mm:ss”.
Кроме того, записи можно предварительно отфильтровать в параметре filter по:
· states — массив статусов звонков обзвонов. Перечень приведен в соответствующем словаре;
· taskIds — массив id обзвонов;
· phone — часть номера абонента. Все сторонние символы будут предварительно удалены;
· operatorNumber — точный номер оператора. Все сторонние символы будут предварительно удалены;
· name — часть имени, закрепленного за номером обзвона на момент звонка;
· note — часть заметки, закрепленной за номером обзвона на момент звонка;
· link — часть данных для Web Dialer, закрепленных за номером обзвона на момент звонка;
· param — часть любого из параметров, закрепленных за номером обзвона на момент звонка;
· voiceSecretaryIds — массив id голосовых секретарей, которые были использованы в звонке;
· voiceSecretaryEndReasons — массив причин завершения голосового секретаря, который был использован в звонке. Перечень приведен в соответствующем словаре;
· voiceSecretaryEndNodeTypes — массив типов конечного узла голосового секретаря, который был использован в звонке. Перечень приведен в соответствующем словаре.
Пример JSON запроса:
{
"action": "GET_CALLS_HISTORY",
"callHistoryRequest": { // Обязательный параметр. Все внутренние параметры могут быть null
"dateFrom": "2023-10-24 00:00:00", // Минимальная дата и время звонка
"dateTo": "2023-10-25 00:00:00", // Максимальная дата и время звонка
"offset": 0, // Сдвиг относительно начала выборки
"limit": 50, // Максимальное количество звонков, которые будут возвращены в ответе
"maxId": 150, // Максимальный идентификатор звонка
"filter": { // Массив дополнительных фильтров. Все внутренние параметры могут быть null
"states": [ // Массив целевых статусов звонков
"ANSWER",
...
],
"taskIds": [ // Массив идентификаторов целевых обзвонов
"300",
...
],
"phone": "38097", // Часть номеров
"operatorNumber": "2045", // Номер линии целевого оператора
"name": "part of name", // Часть имени
"note": "part of note", // Часть заметки
"link": "part of data for webdialer ", // Часть данных для WebDialer
"param": "part of param", // Часть одного из параметров
"voiceSecretaryIds": [ // Массив идентификаторов целевых голосовых секретарей
"118",
...
],
"voiceSecretaryEndNodeTypes": [ // Массив целевых типов конечных узлов голосового секретаря
"END_SUCCESS",
...
],
"voiceSecretaryEndReasons": [ // Массив целевых причин завершения голосового секретаря
"NORMAL",
...
]
}
}
}
Пример ответа в случае успеха:
{
"count": 140, // Количество соответствующих результатов
"offset": 0, // Использованный сдвиг
"limit": 50, // Использованный лимит
"items": [ // Массив звонков обзвонов
{
"id": 158, // Идентификатор звонка
"taskId": 300, // Идентификатор обзвона
"phone": "380681234567", // Номер телефона
"state": "ANSWER", // Статус завершения звонка
"callEndTime": "2023-10-24 16:15:43", // Дата и время завершения звонка
"operatorNumber": "2045", // Номер оператора. Может быть null
"userId": 15, // Идентификатор оператора. Может быть null
"calledCount": 1, // Количество дозвонов
"realCalledCount": 2, // Всего дозвонов
"seconds": 3, // Тарифицируемое время звонка. Может быть null
"secondsClientWaitOperator": 5, // Время ожидания оператора. Может быть null
"secondsOperatorWaitCall": 15, // Время ожидания звонка. Может быть null
"secondsForOperatorAnswered": 2, // Время до ответа оператора. Может быть null
"secondsTalk": 10, // Время разговора. Может быть null
"rid": 1052434886, // Случайный идентификатор звонка
"name": "some name", // Имя к номеру обзвона на момент звонка. Может быть null
"note": "some note", // Заметка к номеру обзвона на момент звонка. Может быть null
"link": "some data for web dialer", // Данные для WebDialer к номеру обзвона на момент звонка. Может быть null
"params": { // Массив параметров к номеру на момент звонка. Может быть null
"1": "param 1 value", // "Номер": "Значение"
...
},
"withdrawTotal": "0.65", // Суммарная стоимость звонка. Может быть null
"withdrawByCategories": { // Массив списаний за звонок по категориям. Может быть null
"SPEECH_RECOGNITION": "0.10", // Распознавание речи
"TEXT_TO_SPEECH": "0.01", // Синтез речи
"CALL": "0.50", // Совершение звонка
"VOICE_SECRETARY": "0.02", // Голосовой секретарь
"AUTODIALER": "0.02", // Доп. стоимость за обзвон
"ANSWERING_MACHINE_DETECTION": "0.25" // Распознавание автоответчика
"MESSAGE_SERVICE_MESSAGE": "1" // Отправка сообщений
},
"executedTriggerActionIds": [ // Массив идентификаторов выполненных по звонку обработчиков. Может быть null
11,
...
],
"sendFirstMessageToClientSuccess": true, // Признак успешности отправки первого сообщения по звонку
"secretary": { // Массив данных о прохождении голосового секретаря. Может быть null
"id": 118, // Идентификатор
"duration": 3, // Длительность
"endNodeType": "INTERMEDIATE", // Тип конечного узла
"endReason": "USER_REJECT", // Причина завершения
"endNodeId": 1, // Идентификатор конечного узла
"endNodeTitle": "Action #1", // Название конечного узла
"endVoiceSecretaryId": 118, // Идентификатор секретаря завершения (может отличаться, если завершение произошло в фоновом)
"steps": [ // Массив информации о шагах секретаря
{
"nodeId": 1, // Идентификатор узла
"actionTitle": "Action #1", // Название узла
"recognizedText": "Some text", // Распознанный текст. Может быть null
"recognizedDates": [ // Массив распознанных дат. Может быть null
"2023-10-24",
...
],
"alternativeAudioIndex": "1", // Индекс альтернативного аудио, которое прослушал абонент. Может быть null
"jumpToNode": false, // Признак перехода на узел действием "Перейти на другой узел"
"startBackgroundSecretaryId": null, // Идентификатор секретаря на который был произведен переход. Может быть null
"endBackgroundSecretaryId": null // Идентификатор фонового секретаря из которого вышли. Может быть null
},
...
]
}
},
...
]
}
Возможные ошибки:
Limit range is 1-5000 | Значение limit не в диапазоне от 1 до 5000 |
Offset is less than 0 | Значение offset должно быть положительным |
callHistoryRequest is null | Не указан параметр callHistoryRequest |
Invalid date from | Некорректная дата и время «от» в фильтрах |
Invalid date to | Некорректная дата и время «до» в фильтрах |
Действие «Удалить номера» позволяет удалить номера из обзвона двумя способами: указав номера или статусы номеров на удаление. Перечень необходимых номеров указывается в параметре запроса numbers и может содержать максимум 10 000 номеров. Номера необходимо указывать в международном формате, все сторонние символы будут предварительно удалены. Статусы номеров указываются в параметре запроса callStates и приведены в соответствующем словаре. В запросе должно присутствовать одно из полей callStates и numbers, в случае когда указаны оба — используется numbers.
Пример JSON запроса:
{
"action": "REMOVE_NUMBERS",
"id": 1307, // ID целевого обзвона
"callStates": [ // Массив статусов номера в которых будут удалены
"NOANSWER",
...
],
"numbers": [ // Массив номеров которые будут удалены
"380970000001",
...
]
}
Пример ответа в случае успеха:
{
"status": "Success",
"data": [ // Массив некорректных номеров
"389833883838383838383838",
...
]
}
В случае успешного удаления хотя бы одного номера с использованием массива numbers ответ будет содержать массив некорректных номеров в поле data.
Возможные ошибки:
Task not found | Обзвон не найден по указанному id |
numbers and states is null | Оба поля numbers и callStates null или пустые |
Too many numbers | В массиве numbers передано более 10 000 номеров |
Phones not found | numbers не содержит ни одного номера |
Numbers not found | Ни один из номеров массива numbers не найден в обзвоне |
Numbers not found by states | По статусам из массива callStates не найдено ни одного номера в обзвоне |
Handler is busy, try again later | Один проект одновременно может удалять или добавлять номера только в одном обзвоне. В этот момент в одном из обзвонов проекта происходит удаление или добавление номеров. Повторите попытку позже, когда предыдущая операция завершится |
Пример JSON запроса:
{
"action": "REMOVE_ALL_NUMBERS",
"id": 1307 // ID целевого обзвона
}
Ответ в случае успеха:
{"status": "Success", "message": "Removed"}
Возможные ошибки:
Task not found | Обзвон не найден по указанному id |
Numbers not found | В указанном обзвоне отсутствуют номера |
Handler is busy, try again later | Один проект одновременно может удалять или добавлять номера только в одном обзвоне. В этот момент в одном из обзвонов проекта происходит удаление или добавление номеров. Повторите попытку позже, когда предыдущая операция завершится |
Типы обзвонов:
AUTODIAL | Автообзвон. Используется преимущественно для информирования клиентов или проведения опросов. Звонки автообзвонов проходят в соответствии с указанным входящим сценарием |
GUARANTEED_DIAL | Гарантированный дозвон. Используется преимущественно для оптимизации рабочего времени операторов. Звонки гарантированных дозвонов распределяются напрямую на операторов указанной группы внутренних линий |
VOICE_ROBOT | Голосовой робот. Используется преимущественно для информирования клиентов или проведения опросов. При звонках голосовых роботов воспроизводиться указанный голосовой секретарь |
Режимы обзвонов:
FIXED | По количеству потоков |
FREE | По свободным операторам |
SMART | Умный подбор |
Статусы обзвонов:
NO_NUMBERS | Номера не добавлены |
IN_PROGRESS | В процессе обзвона |
WAITING | В ожидании начала обзвона |
WAITING_OPERATORS | Ожидание свободных операторов |
WAITING_REPEAT | Ожидание срабатывания настройки «Повторный звонок» |
PAUSED | На паузе |
CANCELED | Отменен, но еще не успел завершиться (часть номеров обзвона находятся в статусе DIALING) |
FINISHED | Завершен |
Динамические значения для синтеза аудио:
NA | Номер обзвона: имя |
NO | Номер обзвона: заметка |
LI | Номер обзвона: данные для Web Dialer |
P1 | Номер обзвона: параметр #1 |
P2 | Номер обзвона: параметр #2 |
P3 | Номер обзвона: параметр #3 |
P4 | Номер обзвона: параметр #4 |
P5 | Номер обзвона: параметр #5 |
P6 | Номер обзвона: параметр #6 |
P7 | Номер обзвона: параметр #7 |
P8 | Номер обзвона: параметр #8 |
P9 | Номер обзвона: параметр #9 |
P10 | Номер обзвона: параметр #10 |
Состояния номера обзвона:
Статус | Название статуса | Доступен для автоматического повторного прозвона (поле repeatCallStates) | Доступен для метода REFRESH | Свидетельствует о возможных проблемах в настройках обзвона или телефонии | Является статусом звонка |
---|---|---|---|---|---|
NEW | Не обработано | — | — | — | — |
DIALING | В процессе обзвона | — | — | — | — |
ANSWER | Отвечено абонентом и оператором | — | + | — | + |
ANSW_RJCT | Отвечено абонентом и не было звонка операторам | + | + | — | + |
NOANSWER | Не отвечено | + | + | — | + |
BUSY | Занято или сброс | + | + | — | + |
FAIL | Сбой соединения | + | + | — | + |
BLOCKED | Заблокирован | — | + | — | — |
TALKING | Автоответчик: абонент разговаривает | + | + | — | + |
UNREACHABLE | Автоответчик: абонент недоступен | + | + | — | + |
NOT_EXIST | Автоответчик: номер не существует | + | + | — | + |
VOICE_MAIL | Автоответчик: голосовая почта | + | + | — | + |
CLIENT_CALLED | Абонент позвонил сам или был исходящий | — | + | — | — |
CANCEL | Отменено | — | + | — | — |
ANSW_NF_OP | Отвечено абонентом и не было свободных операторов | + | + | + | + |
ANSW_OP_NA | Отвечено абонентом и операторы не приняли звонок | + | + | + | + |
BUSYOUT | Недостаточно линий | + | + | + | + |
AUDIO_ERR | Ошибка аудио | — | + | + | + |
WRONG_DIR | Неверное направление | — | + | + | + |
AUTOCANCEL | Отменено автоматически | — | + | + | — |
События обзвонов и звонков обзвонов:
AUTODIAL_ANSWER | Звонок завершен — отвечено абонентом и оператором |
AUTODIAL_ANSW_RJCT | Звонок завершен — отвечено абонентом и не было звонка операторам |
AUTODIAL_ANSW_NF_OP | Звонок завершен — отвечено абонентом и не было свободных операторов |
AUTODIAL_ANSW_OP_NA | Звонок завершен — отвечено абонентом и операторы не приняли звонок |
AUTODIAL_NOANSWER | Звонок завершен — не отвечено |
AUTODIAL_BUSY | Звонок завершен — занято или сброс |
AUTODIAL_CALL_FAIL | Звонок завершен — сбой соединения |
AUTODIAL_TALKING | Звонок завершен — абонент разговаривает |
AUTODIAL_UNREACHABLE | Звонок завершен — вне зоны или отключён |
AUTODIAL_NOT_EXIST | Звонок завершен — номер не существует |
AUTODIAL_BUSYOUT | Звонок завершен — недостаточно линий |
AUTODIAL_WRONG_DIR | Звонок завершен — неверное направление |
AUTODIAL_AUDIO_ERR | Звонок завершен — ошибка аудио |
AUTODIAL_NUMBER_BLOCKED | Номер заблокирован настройками проекта |
AUTODIAL_REPEAT_ATTEMPTS_ENDED | Звонок завершен неуспешно и закончились попытки повторного прозвона |
AUTODIAL_CLIENT_CALLED | Абонент позвонил сам или был исходящий |
AUTODIAL_USER_PAUSED | Пользователь поставлен на паузу обзвоном. Доступно только для гарантированного дозвона |
AUTODIAL_STATUS_CHANGED | Статус обзвона изменён |
AUTODIAL_CANCEL | Обзвон отменен |
AUTODIAL_AUTOCANCEL | Обзвон отменен автоматически |
AUTODIAL_FINISH | Обзвон завершен |
Типы конечных узлов голосовых секретарей:
INTERMEDIATE | Промежуточный |
END_SUCCESS | Успешный |
END_FAIL | Неуспешный |
BACKGROUND | Фоновый |
BACKGROUND_DEFER | Фоновый — перенос звонка |
Причины завершения голосовых секретарей:
NORMAL | Закончился нормально |
USER_REJECT | Абонент завершил разговор |
GREETING_SILENCE | Абонент молчал во время приветствия |
ANSWERING_MACHINE | Распознан автоответчик |
RECOGNITION_ERROR | Распознавание речи прервалось по техническим причинам |
JUMP_LIMIT | Превышен лимит выполненных действий «Перейти на другой узел» |
NODE_LIMIT | Превышен лимит пересеченных узлов |
FAIL | Неизвестная ошибка |
Все методы инициации звонков поддерживают опциональный параметр meta. В параметре можно передать до 1000 символов любой информации, которая впоследствии будет отображена в вебхуках, что может быть использовано для присвоения собственного идентификатора звонка.
Для инициации звонка с внутренней линии необходимо указать номер внутренней линии в параметре sip и мобильный номер, на который необходимо совершить звонок, в международном формате в параметре number. Этот метод позволяет инициировать звонок без ввода номера оператором и широко применяется в интеграционных целях.
Относительный путь: /phones/directCall
Режим: POST
Content-Type: application/x-www-form-urlencoded (Также можно отправлять запрос передавая параметры в качестве параметров url, без тела)
Пример запроса:
/phones/directCall?sip=2023&number=380123456789&meta=sample.id.0001
Ответ в случае успеха:
{"status": "Success","message": "Called"}
В результате выполнения метода на указанный sip номер поступит входящий звонок от системы, по принятию которого будет осуществлен набор на number клиента.
Возможные ошибки:
Sip not found | Указанная линия не найдена в проекте |
Sip not ready | Указанная линия не может принять звонок |
Wrong phone | Номер клиента указан некорректно |
Meta info is too big | meta больше 1000 символов |
Для инициации информирующего звонка, который будет исполнен без участия оператора, необходимо указать мобильный номер, на который необходимо совершить звонок, в международном формате в параметре number. Опционально в параметре outerLine может быть указана внешняя линия в международном формате с которой будет совершен звонок, в противном случае будет использован текущий исходящий сценарий. Кроме того, запрос должен содержать как минимум один из параметров, указывающих что будет воспроизведено клиенту при ответе на звонок:
audios — Массив, который используется для указания аудио. Аудио воспроизводиться до голосового меню и секретаря. Каждый элемент массива представляет собой:
· id — Загруженное аудио в проекте из раздела «API звонки», которые можно загрузить на странице личного кабинета «Аудио файлы»;
· tts — Синтезированное аудио;
В каждом элементе audios должен присутствовать один из параметров id и tts если указаны оба будет использован id. Порядок расположения аудио в массиве соответствует порядку воспроизведения, максимум элементов — 5 (из которых 2 синтеза аудио).
В элементе tts должен присутствовать параметр settingsId один из параметров text и ssml. Если указаны оба text и ssml будет использован ssml, максимальное количество символов — 2500. Параметр ssml должен начинаться и заканчиваться тегом speak. Процесс озвучивания происходит перед стартом звонка. Синтезированные аудио хранятся до 7 дней по завершению звонка, не более 3 месяцев с момента создания и в списке аудиозаписей проекта не отображаются. В случае, если синтезированный текст и профиль настроек совпадают — используется ранее синтезированное аудио.
ivrId — id голосовое меню. В голосовом меню разрешаются только действия:
· Перевод звонка на внутреннюю линию;
· Перевод звонка на группу номеров (SIP);
· Воспроизведение голосового сообщения.
voiceSecretaryId — id голосового секретаря. В голосовом секретаре не разрешаются действия:
· Перевод звонка на GSM номер;
· Активация сценария;
· Активация голосового меню;
· Перевод звонка на отдел (GSM).
Относительный путь: /calls/originateNew
Режим: POST
Content-Type: application/json
Пример JSON запроса:
{
"phone": "380123456789", // Номер клиента
"outerLine": "380441234567", // Внешняя линия
"audios": [ // Массив аудиозаписей и синтеза аудио, которые будут проиграны при звонке на номер
{
"id": 1234 // ID целевой аудиозаписи
},
{
"tts": { // Данные для синтеза аудио
"text": "sample_text", // Текст который будет озвучен
"ssml": "<speak>sample_text</speak>", // Текст который будет озвучен в формате ssml
"settingsId": 18 // ID профиля настройки синтеза аудио
}
},
...
],
"ivrId": 123, // id голосового меню
"voiceSecretaryId": 123, // id голосового секретаря
"meta": "sample.id.0001"
}
Ответ в случае успеха:
{"status": "Success"}
Звонок завершиться по окончанию воспроизведения аудиозаписи, голосового меню или секретаря в случае, если не был выполнен перевод на линию оператора.
Возможные ошибки:
Call already in progress | Предыдущий звонок этому абоненту еще не завершился |
Outer line not found | Указанная внешняя линия не найдена в проекте |
Outer line is tracked | Указанная внешняя линия участвует в трекинге. С неё нельзя совершать исходящие |
No audio and IVR | Не указаны ни один из параметров audios, ivrId и voiceSecretaryId |
IVR can be used for SIPs only | В указанном голосовом меню присутствуют неразрешенные действия |
Service not paid | Ошибка оплаты. Возможные причины: · Тариф проекта не активен · На счету проекта нет средств · В тарифе проекта нет API звонков |
Limit of Simultaneously calls has reached | Достигнут предел в 20 одновременных звонков |
audios | Ошибка указания массива audios. Возможные причины ошибки: · Too many audios — слишком много элементов · Too many text to speech — слишком много элементов с синтезом аудио · Audio is null — присутствуют элементы со значением null · Audio not found by id — присутствуют id по которым не найдена аудиозапись · Wrong type of audio — присутствуют id который указывает аудиозапись недопустимого раздела · Text to speech ‘text’ and ‘ssml’ is null — присутствуют tts в которых оба text и ssml пустые · Text to speech ‘text’ not valid — присутствуют tts в которых text превышает 2500 символов · Text to speech ‘ssml’ not valid — присутствуют tts в которых ssml превышает 2500 символов или не начинается и заканчивается тегом speak · Text to speech settings not found by id — присутствуют tts в которых по указанному settingsId не найден профиль настроек синтеза аудио · Audio is empty — присутствуют элементы в которых оба tts и id имеют значение null · Text to speech failed — ошибка при синтезе аудио из текста |
Wrong phone | Номер клиента указан некорректно |
Meta info is too big | meta больше 1000 символов |
Для инициации звонка, аналогичного по принципу работы с Click to call без необходимости предварительного создания сайта и добавления кнопки обратного звонка, необходимо указать номер клиента в международном формате в параметре clientNumber и массив шагов переадресаций звонка на операторов в параметре steps.
Относительный путь: /calls/originateC2c
Метод: POST
Content-Type: application/json
Метод применяется, когда информация о необходимости обратного звонка, номерах клиента и операторов содержится/создается в сторонней системе. Такие звонки не будут видны в заявках и CRM системах, но будут в истории звонков и вебхуках.
Каждый элемент массива шагов переадресаций должен содержать следующие обязательные параметры:
· type — Тип переадресации. Доступные значения: GSM (Мобильный номер), SIP (Внутренняя линия) и GROUP (Группа внутренних линий);
· to — Номер оператора. Зависит от указанного в параметре type типа переадресации: GSM — Номер в международном формате, SIP — номер внутренней линии, GROUP — id группы внутренних линий;
· awaitingTime — Количество времени на одну переадресацию в секундах. Доступные значения: от 5 до 300.
Порядок расположения шагов в массиве соответствует порядку переадресаций.
Пример JSON запроса:
{
"clientNumber": "380123456789", // Номер клиента
"steps": [ // Массив шагов переадресаций
{
"type": "GSM", // Тип переадресации
"to": "380987654321", // Номер оператора
"awaitingTime": 20 // Время на шаг
},
{
"type": "SIP",
"to": "2023", // Номер внутренней линии
"awaitingTime": 20
},
{
"type": "GROUP",
"to": "123", // Номер группы внутренних линий
"awaitingTime": 60
},
...
],
"meta": "sample.id.0001"
}
Ответ в случае успеха:
{"status": "Success", "message": "Called"}
Возможные ошибки:
Call to XXXXXXXXX is already in progress | Звонок клиенту уже в процессе |
Steps is empty | Не указаны шаги переадресации в steps |
Wrong client number | clientNumber указан не в международном формате |
Client number blocked in project settings | clientNumber заблокирован в настройках проекта |
To number incorrect | Номер не является ни внутренней линией, ни мобильным номером |
Step type not set | Тип распределения не указан в поле type |
Group id is incorrect | Группа, указанная в to не найдена |
Meta info is too big | meta больше 1000 символов |
Для сброса активного звонка необходимо указать как минимум один из обязательных параметров:
· id — Уникальный идентификатор звонка. Может быть получен из истории или в вебхуках;
· number — Номер внутренней или внешней линии. Будут сброшены все найденные звонки с участием указанного номера.
Относительный путь: /calls/hangup
Режим: POST
Content-Type: application/json
Примеры JSON запросов:
{
"number": 380123456789
}
{
"id": 1234567890
}
Пример ответа в случае успеха:
{"status": "Success","message": "Found: 1"}
Возможные ошибки:
Empty request | Не указан ни id, ни number |
Для инициации подключения суфлера необходимо указать два обязательных параметра:
· target — Номер внутренней линии в звонке, к которой будет подключен суфлер;
· source — Номер внутренней линии, которая будет подключена суфлером к активному звонку.
Относительный путь: /calls/connectAsPrompter
Режим: POST
Content-Type: application/json
Права на вызов суфлера пользователями соответствующих внутренних линий не учитываются при выполнении запроса
Пример JSON запроса:
{
"target":"1111",
"source":"2222"
}
Ответ в случае успеха:
{"status": "Success"}
Возможные ошибки:
Target not found | Целевая линия не найдена в проекте |
Target is not in call | Целевая линия не находиться в звонке |
Source not found | Линия суфлера не найдена |
Source is offline | Линия суфлера не в сети |
Для активации речевой аналитики по звонку необходимо указать два обязательных параметра:
· callId — Идентификатор звонка. Может быть получен по API из истории звонков или в вебхуках по звонкам;
· profileId — Идентификатор профиля аналитики. Может быть получен на странице личного кабинета «Речевая аналитика» в шапке целевого профиля.
Относительный путь: /calls/analytics/create
Режим: POST
Content-Type: application/json
Запуск аналитики возможен только по тем звонкам, для которых были сохранены раздельные записи.
Ответ на запрос будет отправлен после окончания обработки звонка, следовательно рекомендуется значительно повысить время ожидания ответа для запросов к данному методу.
Максимально одновременных звонков в обработке — 50.
Пример JSON запроса:
{
"callId":"12345678",
"profileId":"123"
}
Пример ответа в случае успеха:
{
"profileId": 123, // Идентификатор использованного профиля речевой аналитики
"profileName": "Sample Name", // Название использованного профиля речевой аналитики
"operatorTag": "Operator", // Действующее лицо, которое считается оператором
"plainTranscription": "Operator: Hello! This is sample speech", // Транскрипция диалога
"transcription": "00:00:00,000-->00:00:15,000\nOperator: Hello! This is sample speech", // Экранированная транскрипция диалога
"sentimentAnalysis": "The dialogue consisted only of a greeting from the operator. The operator looks cheerful and interested in communication, the client’s mood is unknown", // Описание настроения диалога
"operatorSentimentAnalysis": "The operator looks cheerful and interested in communication", // Описание настроения оператора
"clientSentimentAnalysis": "The client’s mood is unknown", // Описание настроения клиента
"dialogTopic": "None", // Тема диалога
"summarizedPoints": [ // Массив ключевых моментов диалога
"The dialogue consisted only of a greeting from the operator", // Один из ключевых моментов диалога
...
],
"keywords": [ // Массив ключевых слов диалога
"Hello", // Одно из ключевых слов диалога
...
],
"dialogQualityScore": 70, // Общая оценка диалога от 0 до 100
"operatorProfessionalismScore": 9.5, // Оценка профессионализма оператора от 0 до 10
"communicationClarity": 8.0, // Оценка четкости коммуникации оператора от 0 до 10
"problemIdentification": 8.5, // Оценка качества определения проблемы оператором от 0 до 10
"issueResolutionEfficiency": 8.0, // Оценка эффективности решения проблемы оператором от 0 до 10
"empathyLevel": 7.5, // Оценка уровня эмпатии оператора от 0 до 10
"engagementLevel": 8.0, // Оценка вовлеченности оператора от 0 до 10
"adaptability": 7.5, // Оценка способности адаптироваться оператора от 0 до 10
"personalizationInteraction": 8.0, // Оценка персонализации подхода оператором от 0 до 10
"overallSatisfactionRating": 8.5, // Оценка удовлетворенности клиента от 0 до 10
"obsceneWords": [], // Массив использованной нецензурной лексики
"fillerWords": [], // Массив использованных слов-паразитов
"furtherSteps": "Contact again later", // Предложения по дальнейшим шагам в коммуникации
"operatorMistakes": "None", // Ошибки оператора
"needsAttention": false, // Признак необходимости обратить внимание на звонок
"stopWords": [ // Массив стоп-слов
{
"sourcePhrase": "We can't", // Стоп-слово
"translatedPhrase": "We can't", // Перевод стоп-слова на язык аналитики
"said": false // Признак присутствия стоп-слова в диалоге
},
...
],
"requiredPhrases": [ // Массив обязательных слов
{
"sourcePhrase": "Hello", // Обязательное слово
"translatedPhrase": "Hello", // Перевод обязательного слова на язык аналитики
"said": false // Признак присутствия обязательного слова в диалоге
}
]
}
Параметр ответа transcription содержит строки транскрипции диалога в формате:
· *Время начала промежутка реплики*—>*Время окончания промежутка реплики* — Например «00:00:00,000—>00:00:15,000»;
· *Действующее лицо*: *Транскрипция реплики* — Например «Operator: Hello! This is sample speech»;
· Следующая реплика в аналогичном форматировании;
· Временные промежутки и транскрипции реплик разделены между собой управляющими символами переноса строки («\n»);
· В параметре transcription в отличии от plainTranscription управляющие символы экранированы («\\n»), кроме того plainTranscription не содержит временных промежутков реплик.
Возможные ошибки:
Only 50 concurrent requests are allowed | Превышен лимит одновременно обрабатываемых звонков |
Call does not exist | По указанному callId не найден звонок |
Profile does not exist | По указанному profileId не найден профиль речевой аналитики |
Analytics is not available for this call | Формирование речевой аналитики невозможно, т.к. для указанного звонка отсутствуют разделённые записи |
Voice analytics is already in progress | Обработка речевой аналитики по указанному звонку уже запущена |
Voice analytics is not available | Услуга речевой аналитики недоступна |
Insufficient funds | На балансе проекта недостаточно средств |
Для добавления аудио в проект в multipart запросе необходимо указать следующие параметры:
· name (String) — Название аудио файла, который будет добавлен. Должно быть уникальным в рамках одного раздела. Максимум 200 символов;
· type (String) — Указатель раздела, в который будет добавлен аудио файл. Доступные значения: GENERAL (Сценарии), IVR (Голосовые меню), MELODY (Мелодии ожидания на линии и очередей), AUTODIAL (Автообзвоны), VOICE_SECRETARY (Голосовые секретари), VOICE_QUEUE (Очереди звонков с голосовым сопровождением) и API (API звонки);
· file (File) — Аудио или видео файл любого формата. Максимальный размер — 15 мб. Дорожка аудио из файла будет конвертирована и нормализирована. Максимальная длительность итогового аудио будет обрезана в соответствии с типом: IVR — до 90 сек., AUTODIAL, MELODY и API — до 300 сек., GENERAL — до 30 сек.
Относительный путь: /audio/upload
Режим: POST
Content-Type: multipart/form-data
Опционально к запросу можно добавить параметр temp (Boolean), значение true которого будет указывать на необходимость отметить файл как временный и удалить в 04:00.
Пример ответа в случае успеха:
{"status": "Success","message": "123"}
Параметр ответа message будет содержать id добавленного аудио файла.
Для добавления в проект синтезированных аудио необходимо указать массив данных для синтеза в параметре data. Максимальная длинна массива — 5 элементов. Каждый элемент должен содержать следующие параметры:
· name — Название аудио файла, который будет добавлен. Должно быть уникальным в рамках одного раздела. Максимум 200 символов;
· type — Указатель раздела, в который будет добавлен аудио файл. Доступные значения: GENERAL (Сценарии), IVR (Голосовые меню), MELODY (Мелодии ожидания на линии и очередей), AUTODIAL (Автообзвоны), VOICE_SECRETARY (Голосовые секретари), VOICE_QUEUE (Очереди звонков с голосовым сопровождением) и API (API звонки);
· tts — Данные для синтеза аудио. В элементе tts должен присутствовать параметр settingsId один из параметров text и ssml. Если указаны оба text и ssml будет использован ssml, максимальное количество символов — 2500. Параметр ssml должен начинаться и заканчиваться тегом speak.
Относительный путь: /audio/tts
Режим: POST
Content-Type: application/json
Пример JSON запроса:
{
"data": [ // Массив данных для синтеза аудио
{
"name": "sample_name", // Название с которым аудио будет добавлено в проект
"type": "AUTODIAL", // Раздел аудио в который будет добавлена аудиозапись
"tts": { // Данные для синтеза аудио
"text": "sample_text", // Текст который будет озвучен
"ssml": "<speak>sample_text</speak>", // Текст который будет озвучен в формате ssml
"settingsId": 18 // ID профиля настройки синтеза аудио
}
},
...
]
}
Пример ответа:
{
"status": "Success",
"message": "Success",
"data": [ // Массив результатов синтеза
{ // Пример успешного синтеза (присутствует id, error - null)
"name": "sample_name", // Название аудио
"id": 4962 // id с которым аудио было добавлено в проект
},
{ // Пример неудачного синтеза (присутствует error, id - null)
"name": "sample_name",
"error": "Same name already present"
}
]
}
Возможные ошибки синтеза отдельных аудио (error):
type is null | Не указан раздел добавляемого аудио |
name is empty | Название добавляемого аудио не указано или пустое |
name length more than 200 chars | Длина названия добавляемого аудио превышает 200 символов |
Same name already present | Аудио с таким именем уже присутствует в указанном разделе |
tts is null | Параметр tts не указан |
Text to speech ‘text’ and ‘ssml’ is null | В tts не указано ни text, ни ssml |
Text to speech ‘text’ not valid | Параметр text превышает 2500 символов |
Text to speech ‘ssml’ not valid | Параметр ssml превышает 2500 символов или не начинается и заканчивается тегом speak |
Text to speech ‘settingsId’ is null | В tts не указан профиль настроек синтеза аудио в параметре settingsId |
Text to speech settings not found by id | В tts по указанному settingsId не найден профиль настроек синтеза аудио |
Text to speech failed | Ошибка при синтезе аудио из текста |
Возможные ошибки:
Allowed only one simultaneous text to speech request per project | Один и тот же проект не может вызывать этот метод одновременно несколько раз. Подождите пока завершится предыдущий запрос. |
data is null | В запросе отсутствует параметр data |
data is empty | В параметре data нет элементов |
Too many elements in data | Количество элементов в параметре data превышает 5 |
Service not paid | Ошибка оплаты. Возможные причины: · Тариф проекта не активен · На счету проекта нет средств |
Работа с списками осуществляется с помощью действий, метод:
Относительный путь: /lists
Режим: POST
Content-Type: application/json
Целевой список указывается в теле запроса в обязательном параметре list. Перечень существующих списков:
· BLOCKED_PHONES — Список заблокированных номеров в международном формате, взаимодействие с которыми отклоняется;
· BLOCKED_FOR_AUTODIAL_PHONES — Список номеров в международном формате, которые нельзя добавить в обзвоны.
Действия указываются в теле запроса в обязательном параметре operation. Перечень существующих действий:
· GET — Получение текущего списка;
· ADD — Добавление элементов в список;
· REMOVE — Удаление элементов из списка.
Для действий ADD и REMOVE обязательно указание массива элементов которые будут добавлены или удалены в параметре items. Максимальное количество элементов в массиве items — 100.
Список заблокированных номеров в международном формате, взаимодействие с которыми отклоняется. Для работы с списком заблокированных номеров в обязательном параметре list необходимо указать «BLOCKED_PHONES». Для действий ADD и REMOVE параметр items должен представлять собой массив номеров в международном формате.
Пример JSON GET запроса:
{
"list": "BLOCKED_PHONES"
"operation": "GET"
}
Пример ответа:
["380123456789", ...]
Пример JSON ADD запроса:
{
"list": "BLOCKED_PHONES",
"operation": "ADD",
"items": ["380123456789", ...]
}
Пример JSON REMOVE запроса:
{
"list": "BLOCKED_PHONES",
"operation": "REMOVE",
"items": ["380123456789", ...]
}
Ответ для ADD и REMOVE запросов:
{"status": "Success"}
Список номеров в международном формате, которые нельзя добавить в обзвоны. Для работы с списком номеров, которые нельзя добавить в обзвоны, в обязательном параметре list необходимо указать «BLOCKED_FOR_AUTODIAL_PHONES». Для действий ADD и REMOVE параметр items должен представлять собой массив номеров в международном формате.
Пример JSON GET запроса:
{
"list": "BLOCKED_FOR_AUTODIAL_PHONES",
"operation": "GET"
}
Пример ответа:
["380123456789", ...]
Пример JSON ADD запроса:
{
"list": "BLOCKED_FOR_AUTODIAL_PHONES",
"operation": "ADD",
"items": ["380123456789", ...]
}
Пример JSON REMOVE запроса:
{
"list": "BLOCKED_FOR_AUTODIAL_PHONES",
"operation": "REMOVE",
"items": ["380123456789", ...]
}
Ответ для ADD и REMOVE запросов:
{"status": "Success"}
POST /users/list
Возвращает список пользователей.
[
{
"email": "example@gmail.com",
"firstName": "Александр",
"lastName": "Александрович",
"middleName": "Александров",
"phone": "380501234567",
"role": "ADMIN",
"id": 12579,
"workStatus": "WORK"
},
{
"email": "example@unitalk.cloud",
"firstName": "Владимир",
"lastName": "Владимирович",
"middleName": "null",
"phone": "380935551133",
"role": "OWNER",
"id": 5701,
"workStatus": "WORK"
}
]
/users/getStatus
Выдаёт список всех пользователей с указанием их внутренней или мобильной линии и состоянием работы.
[
{
"firstName": "Василий",
"middleName": "Александрович",
"lastName": "Иванов",
"phone": "4035",
"workStatus": "WORK"
}
]
workStatus может быть:
WORK (работает),
PAUS (на паузе),
STOP (работа окончена/еще не начал работать)
у пользователей без расширенного функционала, workStatus всегда WORK
/phones/inner/setStatus
Режим: POST
Передавать параметры
number — номер линии оператора
status — новое состояние (WORK, PAUS, STOP)
Пример: /phones/inner/setStatus?number=9999&status=WORK
В случае успеха ответ:
{"status": "Success", "message": "Success"}
Для получения списка внутренних линий и текущего их статуса необходимо отправить пустой запрос. В ответе будет возвращен ассоциативный массив, где ключ — номер внутренней линии, а значение — её текущий статус. Возможные статусы: online (линия в сети и не занята), busy (линия в сети и занята звонком) и offline (линия не в сети).
Относительный путь: /phones/inner
Режим: POST
Content-Type: —
Пример ответа:
{
"2022": "offline"
"2023": "busy",
"2024": "online",
...
}
POST /groups/action
Пример body JSON запроса:
{
"action": "GET"
}
Ответ:
{
"status": "Success",
"data": [
{
"id": 455, // id группы
"name": "Отдел продаж", // имя группы
"phones": [ // массив номеров которые содержит группа
{
"number": "4030", // номер
"firstName": "Александр", // имя пользователя, если он есть
"lastName": "Максимов" // фамилия пользователя, если он есть
}
]
}
]
}
POST /groups/action
Пример body JSON запроса:
{
"action": "REMOVE_NUMBER",
"groupId": 141, // id группы
"number": "2561" // номер, который необходимо удалить
}
Успех:
{"status": "Success"}
Возможные ошибки:
Group not found | указанная группа не найдена |
Cant delete the last number from group | нельзя удалить последний номер из группы |
The group does not contain specified number | группа не содержит указанный номер |
Для получения статистики по операторам проекта необходимо указать начало и конец интересующего периода в параметрах dateFrom и dateTo соответственно, в формате “yyyy-MM-dd HH:mm:ss”.
Относительный путь: /operator/statistic
Режим: POST
Content-Type: application/json
Кроме того, записи можно предварительно отфильтровать в опциональном параметре filter по:
· callTypes — Список типов звонков, по которым будет сформирована статистика. Перечень допустимых значений приведен в соответствующем словаре;
· innerPhones — Список номеров внутренних линий, по которым будет сформирована статистика;
· minTimeSeconds — Минимальная длительность разговора в секундах;
· minTimeAwaitingSeconds — Минимальная длительность ожидания в секундах;
· maxTimeAwaitingSeconds — Максимальная длительность ожидания в секундах.
Пример JSON запроса:
{
"from": "2024-01-30 00:00:00",
"to": "2024-02-05 23:59:59",
"filter": {
"callTypes": [
"REGULAR",
...
],
"innerPhones": [
"1234",
...
],
"minTimeSeconds": 1,
"minTimeAwaitingSeconds": 1,
"maxTimeAwaitingSeconds": 60
}
}
Пример ответа в случае успеха:
[
{
"operatorName": "1234 (Sample Name)", // Общая статистика: Оператор
"operatorPhone": "1234", // Номер оператора
"totalCount": 123, // Общая статистика: Звонков
"inCount": 123, // Общая статистика: Входящих
"outCount": 123, // Общая статистика: Исходящих
"totalDuration": "59:59", // Общая статистика: Длительность разговоров
"inUniqueCount": 123, // Общая статистика: Уникальных входящих
"answOpNaCount": 0, // Общая статистика: Пропущенных неотвеченных
"outAnsweredCount": 123, // По исходящим: Успешных
"outAnsweredPercentage": "100.0%", // По исходящим: Процент отвеченных звонков
"outMissedCount": 0, // По исходящим: Количество неуспешных звонков
"outUniqueCount": 123, // По исходящим: На уникальные номера
"outUniqueAnsweredCount": 123, // По исходящим: Количество успешных звонков на уникальные номера
"outUniqueAnsweredPercentage": "100.0%", // По исходящим: Процент успешных звонков на уникальные номера от общего кол-во исходящих
"outDuration": "59:59", // По исходящим: Длительность разговоров
"outAverageDuration": "05:30", // По исходящим: Среднее время разговора
"inAnsweredCount": 123, // По входящим: Отвеченных
"inAnsweredPercentage": "100.0%", // По входящим: Процент отвеченных звонков
"inMissedCount": 0, // По входящим: Пропущенных неотвеченных
"inUniqueAnsweredCount": 123, // По входящим: Отвеченных звонков с уникальных номеров
"inUniqueAnsweredPercentage": "100.0%", // По входящим: Процент отвеченных звонков с уникальных номеров
"inAnsweredNewLeadCount": 123, // По входящим: Отвеченных от новых клиентов
"inLostCount": 0, // По входящим: Потерянных
"inAverageAwaitingTime": "00:15", // По входящим: Среднее время ожидания при ответе
"inTotalAwaitingTime": "02:30", // По входящим: Общее время ожидания при ответе
"inDuration": "59:59", // По входящим: Длительность разговоров
"inAverageDuration": "05:30", // По входящим: Среднее время разговора
"inUniqueRegularCount": 123, // По уникальным: Прямой звонок
"inUniqueTrackingCount": 123, // По уникальным: Call tracking
"inUniqueC2cButtonCount": 123, // По уникальным: Click to call
"inUniqueC2cFormCount": 123, // По уникальным: Форма
"inUniqueC2cApiCount": 123, // По уникальным: Click to call API
"inUniqueAutodialCount": 123, // По уникальным: Обзвон
"inUniqueCallbackCount": 123, // По уникальным: Callback
"inUniqueAutoCallbackCount": 123, // По уникальным: Автоперезвон
"inUniqueApiCount": 123, // По уникальным: API звонок
"inRegularCount": 123, // По источникам: Прямой звонок
"inTrackingCount": 123, // По источникам: Call tracking
"inC2cButtonCount": 123, // По источникам: Click to call
"inC2cFormCount": 123, // По источникам: Форма
"inC2cApiCount": 123, // По источникам: Click to call API
"inAutodialCount": 123, // По источникам: Обзвон
"inCallbackCount": 123, // По источникам: Callback
"inAutoCallbackCount": 123, // По источникам: Автоперезвон
"inApiCount": 123, // По источникам: API звонок
"inMissedAnsweredCount": 0, // По пропущенным: Пропущенных отвеченных
"inMissedNewLeadCount": 0, // По пропущенным: Пропущенных от новых клиентов
"inMissedPercentage": "0.0%", // По пропущенным: Процент пропущенных звонков от всего звонков
"inMissedAverageAwaitingTime": "00:00", // По пропущенным: Среднее время ожидание ответа оператора
"logInTime": "2024-01-30 08:40:00", // Логин
"logOutTime": "2024-02-05 18:30:00", // Логаут
"availableNotInWorkTime": "02:30:00", // Общий Available
"pauseTime": "05:30:00", // Пауза
"wrapUpTime": "", // Общий Wrap-up Time
"compoundTime": 123 // Общий Compound Time
},
...
]
Статистика представляет собой список объектов информации о всех операторах и о каждом в отдельности, соответствующей табличной выгрузке на странице личного кабинета «По операторам» раздела «Статистика« с аналогичными критериями поиска.
Возможные ошибки:
Wrong FROM date | Не указаны или некорректны дата и время начала целевого периода |
Wrong TO date | Не указаны или некорректны дата и время конца целевого периода |
Типы источников звонков:
AUTO_CB | Автоперезвон |
AUTODIAL | Обзвон |
REGULAR | Прямой звонок |
C2C_FORM | Форма обратного звонка |
API | API звонок |
TRACKING | Call Tracking |
CALLBACK | Callback |
C2C_BUTTON | Кнопка обратного звонка |
C2C_API | API обратный звонок |
Для получения истории звонков проекта необходимо указать начало и конец интересующего периода в параметрах dateFrom и dateTo соответственно, в формате “yyyy-MM-dd HH:mm:ss”. Записи возвращаются в порядке убывания id. Количество записей, которые будут получены при этом не превышает значение обязательного параметра limit. Допустимый диапазон limit — от 1 до 1000. Для получения следующей группы записей необходимо в параметре offest указать сдвиг относительно начала списка.
Относительный путь: /history/get
Режим: POST
Content-Type: application/json
Кроме того, записи можно предварительно отфильтровать в опциональном параметре filter по:
· direction — Направление звонков. Допустимые значения: IN — входящие, OUT — исходящие, INNER — внутренние;
· minDuration — Минимальная длительность разговора в секундах;
· calledFrom — Массив частей номеров с которых звонили;
· calledTo — Массив частей номеров на которые звонили;
· outerNum — Массив номеров внешних линий на которые поступали или через которые осуществлялись звонки;
· exactPhone — Массив полных номеров, которые осуществляли или принимали звонки;
· newLead — Признак первого звонка по номеру клиента. Допустимые значения: true — только первые, false — только не первые;
· answered — Признак отвеченного звонка. Допустимые значения: true — только отвеченные, false — только не отвеченные;
· lost — Признак потерянного звонка (пропущенного, на которые не перезвонили). Допустимые значения: true — только потерянные, false — только не потерянные;
· voiceMessage — Признак оставленного голосового сообщения в звонке. Допустимые значения: true — только с голосовым сообщением, false — только без.
Пример JSON запроса:
{
"dateFrom": "2023-12-12 00:00:00",
"dateTo": "2024-01-01 00:00:00",
"limit": 50,
"offset": 0,
"filter": {
"direction": "IN",
"minDuration": 10,
"calledFrom": ["3809533"],
"calledTo": ["33"],
"outerNum": ["380800123123"],
"exactPhone": ["3333", "380955555555"],
"newLead": false,
"answered": true,
"lost": false,
"voiceMessage": false
}
}
Пример ответа в случае успеха:
{
"count": 100, // Количество звонков по указанным критериям
"calls": [ // Массив звонков
{
"id": 19990701, // Случайный id звонка
"dbid": 603, // id звонка в проекте
"date": "2023-12-20 15:28:00", // Дата и время звонка
"source": "REGULAR", // Источник звонка
"direction": "IN", // Направление звонка
"from": "380955555555", // Номер звонившего
"to": ["3333"], // Массив номеров на которые поступил звонок
"lastGroupName": "Sales managers", // Название последней группы внутренних линий, на которую был переведен звонок
"secondsFullTime": 300, // Полная длительность звонка
"secondsTalk": 285, // Длительность разговора
"link": "https://api.unitalk.cloud:8443/tracking/rec/1531144732.920/2023-12-20", // Ссылка на запись звонка
"comment": "That one was successful!", // Комментарий
"state": "ANSWER", // Состояние звонка
"cause": 16, // Код причины завершения
"callback": false, // Признак автоперезвона
"utmSource": "google", // Метка аналитики
"utmMedium": "search", // Метка аналитики
"utmCampaign": "web", // Метка аналитики
"utmTerm": "best+product", // Метка аналитики
"utmContent": "content", // Метка аналитики
"outerNumber": "site.ua", // Метка аналитики
"googleId": "1182768620.1182768620", // Метка аналитики
"facebookClientId": "fb.1.1234567890", // Метка аналитики
"referer": "google.com" // Метка аналитики
},
...
]
}
Возможные ошибки:
Wrong FROM date | Не указаны или некорректны дата и время начала целевого периода |
Wrong TO date | Не указаны или некорректны дата и время конца целевого периода |
Limit range is 1-1000 | Не указан или некорректный параметр limit |
Вы можете использовать систему вебхуков для получения информации о событиях телефонии. Кроме того, UniTalk поддерживает входящие вебхуки.
Вебхук «Движение по балансу» предоставляет информацию по каждой операции изменения баланса проекта и не может быть конфигурирован, поскольку события данной категории обрабатываются системой автоматически. Для работы с этим вебхуком Ваше веб-приложение должно принимать JSON методом POST по указанному на странице личного кабинета «API» URL.
Есть всего 5 типов операций:
MAIN_REFILL | Пополнение основного счёта |
BONUS_REFILL | Пополнение бонусного счёта |
CALL | Списание за платный звонок |
SMS | Списание за отправку SMS |
SERVICES | Списание за услуги |
Пример отправляемого JSON:
{
"date": "2022-11-12 19:12:50", // Время проведения операции
"type": "MAIN_REFILL", // Тип операции
"sum": 500000, // Сумма операции. 1000 соответствует единице валюты проекта
"sumV2": 500000000, // Сумма операции. 1000,000 соответствует единице валюты проекта
"mainBalance": 15500000, // Основной баланс по завершению операции. 1000 соответствует единице валюты проекта
"mainBalanceV2": 15500000000, // Основной баланс по завершению операции. 1000,000 соответствует единице валюты проекта
"bonusBalance": 350000, // Бонусный баланс по завершению операции. 1000 соответствует единице валюты проекта
"description": "Пополнение баланса на 500.00 UAH через LiqPay" // Описание операции
}
Отправка вебхука может быть выбрана в качестве типа действия при создании или редактировании действий на странице личного кабинета «Обработка событий». При конфигурации действия данного типа можно указать:
1) URL на который будет отправлен вебхук;
2) HTTP метод, который будет использован;
3) Заголовки HTTP;
4) URL параметры;
5) Тип тела запроса (Для POST, PUT, PATCH);
6) Содержимое тела запроса (Для типов «Указанный JSON» и «Форма (urlencoded)»).
События, за которыми можно закрепить действия, существуют 4 типов:
Типы событий
События в обзвонах номеров | Настраиваются для каждого отдельного обзвона номеров при создании или редактировании через API или в соответствующем разделе личного кабинета, например, “Обзвон завершен”. |
События в голосовых меню | Настраиваются для каждого отдельного голосового меню при создании или редактировании на странице личного кабинета «Голосовое меню», например, нажатие клиентом клавиши “1” |
События звонков | Настраиваются на странице личного кабинета «API», например “Завершение звонка”. Обратите внимание, действие закрепляется за событием звонка вне зависимости от внешней линии, которая при этом задействована |
Событие очереди с голосовым сопровождением | Доступно при создании или редактировании входящего сценария на странице личного кабинета «Входящие сценарии», при выборе перенаправления на “Очередь с сопровождением” и активации опции “Специальное действие” |
Более подробно с процессом обработки событий можно ознакомиться в инструкции по обработке событий.
Отправка вебхука с типом тела «Стандартный JSON» подразумевает формирование тела запроса на основании типа события, по которому был отправлен вебхук:
Стандартный JSON для событий звонков:
{
"event": "CALL_END", // Событие, по которому был отправлен вебхук
"call": { // Массив данных о звонке
"id": 1091944, // Случайно генерируемый id звонка для связи его с другими событиями звонков
"dbid": 275, // id под которым этот звонок был сохранён в базу данных. Впоследствии звонок обладает именно эти id
"from": "380505557182", // Номер с которого был совершен звонок
"to": [ // Массив номеров, на которые был переадресован звонок
"2000"
],
"lastGroupName": "Sales managers", // Название последней группы внутренних линий, на которую был переведен звонок
"outerNumber": "site.ua", // Внешняя линия, которая была использована для совершения или получения звонка. Содержит название сайта в случае обратного звонка
"direction": "IN", // Направление звонка: "IN" - входящий, "OUT" - исходящий, "INNER" - внутренний
"date": "2018-07-09 16:58:52", // Дата и время принятия звонка
"secondsFullTime": 19, // Полное время звонка. Известно только в событии CALL_END
"secondsTalk": 9, // Время общения. Известно только в событии CALL_END
"utmSource": "google", // Метка аналитики. Может быть null
"utmMedium": "search", // Метка аналитики. Может быть null
"utmCampaign": "web", // Метка аналитики. Может быть null
"utmTerm": "ковры", // Метка аналитики. Может быть null
"utmContent": "content", // Метка аналитики. Может быть null
"googleId": "1182768620.1530916891", // Метка аналитики. Может быть null
"facebookClientId": "fb.1.1234567890", // Метка аналитики. Может быть null
"referer": "google.com", // Метка аналитики. Может быть null
"callback": true, // Указывает является ли этот звонок обратным. Устарело. Используйте поле "source"
"comment": "комментарий к звонку",
"state": "ANSWER", // Состояние звонка. Для событий CALL_NEW и CALL_REDIRECT - null
"source": "REGULAR", // Источник звонка
"link": "https://api.unitalk.cloud:8443/tracking/rec/1531144732.920/2018-07-09", // Ссылка на запись звонка. Присутствует только в случае поле state - "ANSWER"
"meta": "some info", // Дополнительная информация, которая может быть задана при инициации звонка через API
"cause": 16 // Код завершения звонка
}
}
Массив «to»
При событии CALL_NEW входящего звонка | Всегда пуст |
При событии CALL_REDIRECT | Содержит один или более номеров |
При событии CALL_ANSWER | Содержит один номер |
При событии CALL_END | Может быть пуст или содержать номера операторов, которым поступил звонок |
Для API звонков | Может отсутствовать, если звонок не был ни на кого перенаправлен |
Поле «state»
ANSWER | Звонок был принят |
BUSY | Линия была занята |
FAIL | Сбой |
NOANSWER | Звонок не был принят |
CHANUNAVAIL | Вызываемый номер был недоступен |
NOMONEY | Недостаточно средств для совершения звонка |
BUSYOUT | Во время совершения звонка все внешние линии были заняты |
WRONGDIR | Неверное направление звонка |
BLOCKED | Звонок был заблокирован согласно настройкам проекта |
DIALING | Идет вызов |
UNREACHABLE | Абонент недоступен или находится вне зоны действия сети |
NOT_EXIST | Вызываемый номер не существует |
Поле «source»
REGULAR | Обычный прямой звонок |
TRACKING | Звонок коллтрекинга |
CLICK2CALL | Обратный звонок с кнопки |
LEAD_CATCHER | Обратный звонок с попапа |
FORM | Обратный звонок с формы |
CALLBACK | Звонок по признаку callback на внешнем номере |
AUTO_CB | Автоматический обратный звонок на пропущенный вызов |
AUTODIAL | Звонок из обзвона номеров |
API_CALL | Звонок инициированный через API |
C2C_API | с2с звонок инициированный через API |
Стандартный JSON для событий голосовых меню:
{
"ivrName":"Распределение по отделам", // Название голосового меню
"from":"380971234567", // Номер телефона абонента
"outerNumber":"380441234567", // Внешняя линия, которая была использована для совершения или получения звонка. Содержит название сайта в случае обратного звонка
"pressedDigit":2, // Цифра на которую нажал абонент. Может быть null
"actionType": "MAIN", // Тип действия. "MAIN" - основное действие, "NO_CHOICE" - действие отсутствия выбора, "WRONG_DIGIT" - действие неправильного выбора
"projectName": "myproject", // Название проекта
"utmCampaign": "sale2021", // Метка аналитики. Может быть null
"utmSource": "google", // Метка аналитики. Может быть null
"utmMedium": "email", // Метка аналитики. Может быть null
"utmTerm": "term", // Метка аналитики. Может быть null
"utmContent": "content", // Метка аналитики. Может быть null
"googleId": "11111.11111", // Метка аналитики. Может быть null
"facebookClientId": "fb.1.1234567890" // Метка аналитики. Может быть null
}
Стандартный JSON для событий завершения звонков обзвонов номеров:
{
"from": "380971234567", // Номер телефона абонента
"operatorNumber": "2040", // Внутренняя линия оператора. Может быть null
"callName": "Владимир", // Имя закрепленное за номером обзвона
"callNote": "покупал окна", // Заметка к номеру обзвона
"calledCount": 1, // Количество звонков на данный номер в обзвоне
"callState": "ANSWER", // Статус завершения звонка. Детальнее в разделе "Обзвон номеров" - "Общие сведенья"
"dialName": "обзвон-окна", // Название обзвона
"totalCount": 2000, // Количество номеров в обзвоне
"doneCount": 537, // Количество обработанных номеров обзвона
"projectName": "myproject" // Название проекта
}
Стандартный JSON для событий обзвона, не связанных со звонками
{}
Стандартный JSON для события очереди с голосовым сопровождением
{
"from":"380971234567", // Номер телефона абонента
"projectName":"my-project", // Название проекта
"utmCampaign": "sale2021", // Метка аналитики. Может быть null
"utmSource": "google", // Метка аналитики. Может быть null
"utmMedium": "email", // Метка аналитики. Может быть null
"utmTerm": "term", // Метка аналитики. Может быть null
"utmContent": "content", // Метка аналитики. Может быть null
"googleId": "11111.11111", // Метка аналитики. Может быть null
"facebookClientId": "fb.1.1234567890", // Метка аналитики. Может быть null
"gclid": "gclid..." // Метка аналитики. Может быть null
"cdid": "cdid...", // Метка аналитики. Может быть null
"referer": "https://unitalk.cloud", // Метка аналитики. Может быть null
"ip": "111.111.111.111" // !
}
UniTalk может принимать вебхуки с определенной структурой и выполнять по ним действия.
Доступные на данный момент действия:
1) «AUTODIAL_ADD» — Добавление номера телефона в обзвон номеров;
2) «AUTODIAL_REMOVE» — Удаление номера телефона из обзвона номеров.
Для использования входящих вебхуков на странице личного кабинета «API« необходимо:
1) Сгенерировать токен:
2) Нажать кнопку «Сгенерировать ссылку«:
3) Выбрать действие, обзвон к которому оно применится, указать дополнительные опции и нажать кнопку «Сгенерировать«:
4) Заполнить параметры ссылки и отправить на неё POST запрос.
Параметры, которые заполняются при генерации автоматически:
token | Токен для входящих вебхуков |
action | Тип действия вебхука |
id | id обзвона номеров |
Пример сгенерированной ссылки:
https://api.unitalk.cloud:8443/tracking/webhook/event?token=LrqN7GRb1Y1Qx5wRoZHY&action=AUTODIAL_ADD&id=20461&name=¬e=&link=&phones=
Параметры, которые необходимо заполнить:
phones | Номер телефона или список номеров телефона через запятую которые необходимо добавить в обзвон |
name | Имя, которое будет закреплено за добавляемыми номерами. Максимум 100 символов. Не обязательное поле |
note | Заметка, которая будет закреплена за добавляемыми номерами. Максимум 500 символов. Не обязательное поле |
link | Данные для Web Dialer, которые будут закреплены за добавляемыми номерами. Максимум 500 символов. Не обязательное поле |
Пример заполненной ссылки:
https://api.unitalk.cloud:8443/tracking/webhook/event?token=LrqN7GRb1Y1Qx5wRoZHY&action=AUTODIAL_ADD&id=20461&name=vasya¬e=okna&phones=380971234567
При отправке POST запроса по этой ссылке, в обзвон с id «20461» будет добавлен номер телефона «380971234567», с именем «vasya» и заметкой «okna».
В случае успеха:
{"status": "Success"}
Возможные ошибки:
Token not found | Переданный токен не найден в UniTalk |
Action not found | Отсутствует параметр action в ссылке |
Id is null | Отсутствует параметр id в ссылке |
Autodial not found | Не найден обзвон по id |
Empty phones | Параметр phones не указан или пустой |
Phones not found | Параметр phones не пустой, но в нем не найден хотя бы один корректный номер телефона |
Phones not added | Не получилось добавить номера в обзвон. Возможно номера уже были добавлены в обзвон |
Пример сгенерированной ссылки:
https://api.unitalk.cloud:8443/tracking/webhook/event?token=LrqN7GRb1Y1Qx5wRoZHY&action=AUTODIAL_REMOVE&id=20461&phones=
Параметры, которые необходимо заполнить:
phones | Номер телефона или список номеров телефона через запятую которые необходимо добавить в обзвон |
Пример заполненной ссылки:
https://api.unitalk.cloud:8443/tracking/webhook/event?token=LrqN7GRb1Y1Qx5wRoZHY&action=AUTODIAL_REMOVE&id=20461&phones=380971234567,380670001000
При отправке POST запроса по этой ссылке, из обзвона с id «20461» будут удалены номера «380971234567» и «380670001000».
В случае успеха:
{"status": "Success"}
Возможные ошибки:
Token not found | Переданный токен не найден в UniTalk |
Action not found | Отсутствует параметр action в ссылке |
Id is null | Отсутствует параметр id в ссылке |
Autodial not found | Не найден обзвон по id |
Empty phones | Параметр phones не указан или пустой |
Phones not found | Параметр phones не пустой, но в нем не найден хотя бы один корректный номер телефона |
Calls not found | Не получилось удалить ни один номер. Возможно в обзвоне не было ни одного из указанных номеров |
Вебхук «Перевод звонка на ответственного оператора» позволяет получить информацию о звонке для последующего выбора ответственного оператора Вашей системой. Для работы с этим вебхуком Ваше веб-приложение должно принимать JSON методом POST по указанному при создании или редактировании входящего сценария на странице личного кабинета «Входящие сценарии», при выборе перенаправления на «На ответственного менеджера» и активации опции «Запрос в Ваш API» URL.
При выполнении данного перенаправления, на указанный URL будет отправлен запрос с следующим содержимым:
{
"event": "ROUTE",
"call": {
"from": "380505557182" // Номер звонящего абонента
}
}
В ответ Ваше приложение должно отправить JSON следующей структуры:
{
"operatorNumber": "2048", // Номер телефона ответственного оператора. Можно указать SIP или GSM. Может быть null
"callerName": "Александр", // Имя абонента, которое будет отображено в SIP клиенте
"ivrId": 487 // id голосового меню, которое необходимо воспроизвести абоненту. Может быть null
}
Предварительно проверять свободен ли в данный момент оператор не нужно: если он занят, перенаправление звонка на него будет пропущено.
Вебхук «Управление очередью с голосовым сопровождением» позволяет получить информацию о звонке для последующей приоритезации обработки клиентов Вашей системой. Для работы с этим вебхуком Ваше веб-приложение должно принимать JSON методом POST по указанному при создании или редактировании входящего сценария на странице личного кабинета «Входящие сценарии», при выборе перенаправления на «Очередь с сопровождением» и активации опции «Вебхук для управления» URL.
При выполнении данного перенаправления, на указанный URL отправлен будет запрос с следующим содержимым:
{
"outerNumber": "380440000001", // Внешняя линия, на которую поступил звонок
"from": "380501234567", // Номер абонента
"utmSource": null, // Метка аналитики. Может быть null
"utmMedium": null, // Метка аналитики. Может быть null
"utmCampaign": null, // Метка аналитики. Может быть null
"utmTerm": null, // Метка аналитики. Может быть null
"utmContent": null, // Метка аналитики. Может быть null
"googleId": null, // Метка аналитики. Может быть null
"facebookClientId": null, // Метка аналитики. Может быть null
"gclid": null, // Метка аналитики. Может быть null
"cdid": null, // Метка аналитики. Может быть null
"referer": null // Метка аналитики. Может быть null
}
Очередь с приоритетом состоит из 10 очередей, которые обрабатываются в порядке уменьшения номера. По умолчанию, UniTalk определяет все звонки в очередь с номером 5.
Ваше приложение может изменить номер очереди, отправив в ответ JSON следующей структуры:
{
"setPriority": 7 // Номер очереди от 1 до 10
}
Для отправки сообщений через SMS и Viber на странице личного кабинета «Сервис отправки сообщений» раздела «Интеграция» должна быть подключена интеграция с сервисом отправки сообщений. Доступность типов сообщений и направлений зависит от настройки этой интеграции. Максимальная длинна текста для Viber — 1000 символов, для SMS — зависит от сервиса отправки сообщений.
Относительный путь: /message/send
Режим: POST
Content-Type: application/json
Пример JSON запроса:
{
"messageType" : "SMS", // Тип сообщения. "SMS" или "VIBER"
"to" : "380971234567", // Номер телефона получателя в международном формате
"text" : "Lorem ipsum dolor sit amet, consectetuer adipiscing elit." // Текст сообщения
}
Пример ответа в случае успеха:
{"status": "Success", "data": 12345}
Идентификатор сообщения, возвращаемый в data, может быть использован для последующего получения информации о статусе отправки сообщения.
Возможные ошибки:
Message service not connected | Не подключен сервис отправки сообщений |
Validation error | Ошибки валидации. Возможные причины: · Неправильный номер телефона получателя · Отправка сообщений по данному направлению не разрешена настройками интеграции с сервисом отправки сообщений · Не выбран тип сообщения · Отправка SMS отключена в настройках сервиса отправки сообщений · Отправка сообщений в Viber отключена в настройках сервиса отправки сообщений · Сообщение не может быть пустым · Сообщение слишком длинное · Сообщение содержит недопустимые символы |
UniTalk did not allow sending | UniTalk не разрешил отправку. Возможные причины: · Недоступное направление для отправки · На балансе недостаточно средств · Проект не активен |
Service response | Ответ сервиса. Возможные причины: · Неверные данные авторизации · Недостаточно средств на балансе · Превышен лимит запросов · Дубль сообщения · IP адрес не разрешен в сервисе отправки сообщений · Имя отправителя заблокировано получателем · Недоступная страна получателя · Номер получателя заблокирован · Недопустимое имя отправителя · Имя отправителя на модерации · Недопустимый номер получателя · Недопустимый текст · Отправка сообщений в Viber недоступна · Данные некорректны · Сервис отправки сообщений временно недоступен |
Unknown error | Неизвестная ошибка |
Для отправки нескольких сообщений одним запросом может быть использована массовая отправка сообщений. Максимальное количество сообщений — 100. Запрос может быть осуществлен в двух вариантах:
· С указанием общего текста сообщений в параметре text и списка номеров телефонов получателей в международном формате в параметре recipients;
· С указанием номеров телефонов получателей в международном формате и соответствующих текстов сообщений парами в массиве messages, где ключ — номер телефона, а значение — текст сообщения.
Если в запросе одновременно указаны параметры обоих способов, будет использован параметр messages.
Относительный путь: /message/sendBulk
Режим: POST
Content-Type: application/json
Примеры JSON запросов:
{
"messagesType": "SMS", // Тип сообщений. "SMS" или "VIBER"
"recipients": [ // Номера телефонов получателей в международном формате
"380971234567",
"380981234567",
...
],
"text": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit." // Текст сообщений
}
{
"messagesType": "SMS", // Тип сообщений. "SMS" или "VIBER"
"messages": { // Массив сообщений
"380971234567": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit. 1", // "Номер телефона": "Текст сообщения"
"380981234567": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit. 2", // "Номер телефона": "Текст сообщения"
...
}
}
Пример ответа в случае успеха:
{
"status": "Success",
"data": {
"380971234567": { // Отправлено
"id": 123451, // Идентификатор сообщения
"error": null // Текст ошибки отправки сообщения
},
"380981234567": { // Не отправлено
"id": 123452, // Идентификатор сообщения
"error": "Sample error text" // Текст ошибки отправки сообщения
},
...
}
}
Массив, возвращаемый в data, содержит идентификатор и текст ошибки каждого из оправляемых сообщений. Идентификатор может быть использован для последующего получения информации о статусе отправки сообщения.
Возможные ошибки:
Message service not connected | Не подключен сервис отправки сообщений |
messagesType is null | Не выбран тип сообщений |
Messages not specified | В запросе не указано ни параметр messages, ни recipients |
Too many messages | Массив messages содержит более 100 пар |
messages is empty | Массив messages пустой |
messages contains null key | В массиве messages присутствует пустой ключ |
messages contains null value | В массиве messages присутствует пустое значение |
Too many recipients | Список recipients содержит более 100 номеров |
recipients is empty | Список recipients пустой |
recipients contains null | В списке recipients присутствует пустое значение |
text is null or empty | Для отправки используется список recipients, но текст не указан |
Для получения статуса отправки сообщения необходимо указать идентификатор, полученный при его отправке, в параметре id.
Относительный путь: /message/getStatus
Режим: POST
Content-Type: application/x-www-form-urlencoded (Также можно отправлять запрос передавая параметры в качестве параметров url, без тела)
Пример запроса:
/message/getStatus?id=12345
Пример ответа в случае успеха:
{
"status": "Success",
"data": {
"messageStatus": "ERROR", // Статус отправки сообщения
"errorText": "Service response: invalid authorization data" // Текст ошибки. Если статус не ERROR - null
}
}
Массив, возвращаемый в data, содержит статус отправки сообщения и текст ошибки отправки, если статус отправки — ERROR.
Статусы отправки:
· SENT — Отправлено. Информация о доставке отсутствует;
· DELIVERED — Доставлено;
· NOT_DELIVERED — Не доставлено;
· ERROR — Ошибка отправки.
Возможные ошибки:
Invalid id | Параметр id отсутствует или некорректный |
Message not found | По указанному id не найдено сообщение |
Для получения списка рассылок и связанной информации необходимо отправить пустой запрос.
Относительный путь: /messageDistribution/getAll
Режим: POST
Content-Type: —
Пример ответа:
[
{
"id": 123, // Идентификатор рассылки
"name": "Sample_name", // Название
"messageType": "SMS", // Тип сообщений. "SMS" или "VIBER"
"text": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit.", // Текст рассылки
"startTime": "2024-07-07 12:00:00", // Время запуска. Если запущена сразу - null
"paused": false, // Признак паузы. "true" - на паузе, "false" - нет
"totalNumbersCount": 10, // Количество номеров в рассылке
"currentNumbersCount": 10, // Количество необработанных номеров
"status": "WAITING_START_TIME" // Статус рассылки
},
...
]
Статусы рассылок:
· COMPLETED — Рассылка завершена;
· PAUSED — На паузе;
· WAITING_START_TIME — Ожидание времени запуска;
· IN_PROGRESS — В процессе рассылки;
· MESSAGE_SERVICE_NOT_CONNECTED — Не подключен сервис отправки сообщений.
Для создания рассылки в запросе необходимо указать обязательные параметры:
· name — Уникальное название новой рассылки. Максимальная длинна — 45 символов;
· messageType — Тип сообщений. «SMS» или «VIBER«;
· numbers — Список номеров телефонов получателей в международном формате. Максимальное количество номеров — 10000;
· text — Текст рассылки. Ограничения зависят от типа сообщений и сервиса отправки сообщений.
Опционально в параметре startTime можно указать дату и время отложенного запуска в формате “yyyy-MM-dd HH:mm:ss”.
Относительный путь: /messageDistribution/create
Режим: POST
Content-Type: application/json
Пример JSON запроса:
{
"name": "Sample_name", // Название
"messageType": "SMS", // Тип сообщений. "SMS" или "VIBER"
"numbers": [ // Номера телефонов получателей в международном формате
"380971234567",
"380671234567",
...
],
"text": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit.", // Текст рассылки
"startTime": "2024-07-07 12:00:00" // Дата и время отложенного запуска. Может быть null, в таком случае будет запущена сразу
}
Пример ответа в случае успеха:
{"status": "Success", "data": 1234}
Идентификатор рассылки, возвращаемый в data, может быть использован для последующего взаимодействия с ней.
Возможные ошибки:
The project does not have a messaging service connected | Не подключен сервис отправки сообщений |
The name cannot be empty or contain more than 45 characters | Название рассылки не указано или превышает 45 символов |
The name already exists | Рассылка с таким называнием уже существует |
No customer numbers are listed | Номера в списке numbers не указаны |
There can be no more than 10000 numbers in the message distribution | Количество номеров в списке numbers превышает 10000 |
Wrong numbers | В списке numbers присутствуют некорректные номера. В параметре ответа data будет возвращен список некорректных номеров |
Incorrect time format | Некорректный формат параметра startTime |
Validation error | Ошибки валидации. Возможные причины: · Не выбран тип сообщения · Отправка SMS отключена в настройках сервиса отправки сообщений · Отправка сообщений в Viber отключена в настройках сервиса отправки сообщений · Сообщение не может быть пустым · Сообщение слишком длинное · Сообщение содержит недопустимые символы |
Для изменения рассылки в запросе необходимо указать обязательные параметры:
· id — Идентификатор рассылки;
· name — Уникальное название рассылки. Максимальная длинна — 45 символов;
· messageType — Тип сообщений. «SMS» или «VIBER«;
· text — Текст рассылки. Ограничения зависят от типа сообщений и сервиса отправки сообщений.
Опционально в параметре startTime можно указать дату и время отложенного запуска в формате “yyyy-MM-dd HH:mm:ss”.
Относительный путь: /messageDistribution/update
Режим: POST
Content-Type: application/json
Пример JSON запроса:
{
"id": 1234, // Идентификатор рассылки
"name": "Sample_name", // Название
"messageType": "SMS", // Тип сообщений. "SMS" или "VIBER"
"text": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit.", // Текст рассылки
"startTime": "2024-07-07 12:00:00" // Дата и время отложенного запуска. Может быть null, в таком случае будет запущена сразу
}
Ответ в случае успеха:
{"status": "Success"}
Возможные ошибки:
The project does not have a messaging service connected | Не подключен сервис отправки сообщений |
id is not specified | Обязательный параметр id не указан |
Message distribution not found | Рассылка не найдена по указанному id |
Message distribution completed | Рассылка уже завершена |
The name cannot be empty or contain more than 45 characters | Название рассылки не указано или превышает 45 символов |
The name already exists | Рассылка с таким называнием уже существует |
Incorrect time format | Некорректный формат параметра startTime |
Validation error | Ошибки валидации. Возможные причины: · Не выбран тип сообщения · Отправка SMS отключена в настройках сервиса отправки сообщений · Отправка сообщений в Viber отключена в настройках сервиса отправки сообщений · Сообщение не может быть пустым · Сообщение слишком длинное · Сообщение содержит недопустимые символы |
Для удаления рассылки необходимо указать её идентификатор в параметре id.
Относительный путь: /messageDistribution/remove
Режим: POST
Content-Type: application/x-www-form-urlencoded (Также можно отправлять запрос передавая параметры в качестве параметров url, без тела)
Пример запроса:
/messageDistribution/remove?id=1234
Ответ в случае успеха:
{"status": "Success"}
Возможные ошибки:
id is not specified | Обязательный параметр id не указан |
Для приостановки или возобновления рассылки необходимо указать её идентификатор в параметре id и действие в параметре paused:
· true — Поставить на паузу;
· false — Снять с паузы.
Относительный путь: /messageDistribution/setPaused
Режим: POST
Content-Type: application/x-www-form-urlencoded (Также можно отправлять запрос передавая параметры в качестве параметров url, без тела)
Пример запроса:
/messageDistribution/setPaused?id=1234&id=true
Ответ в случае успеха:
{"status": "Success"}
Возможные ошибки:
id is not specified | Обязательный параметр id не указан |
Message distribution not found | Рассылка не найдена по указанному id |
Message distribution completed | Рассылка уже завершена |
Для работы с виджетом Chrome (далее Web Dialer) используются методы сгруппированные по пути /widget/
Для отправки уведомлений в Web Dialer необходимо указать id пользователей, которым необходимо отобразить уведомление, в параметре userIds и указать как минимум один параметр объекта data.
Относительный путь: /widget/sendNotification
Режим: POST
Content-Type: application/json
Пример JSON запроса:
{
"userIds": [ // Массив id пользователей
5701, 5800, 4560
],
"data": { // Объект параметров уведомления
"contactName": "John", // Имя контакта
"contactLink": "https://www.example-crm.com/leads/1", // Ссылка на контакт
"entityName": "Best deal", // Имя связанной с контактом сущности
"entityLink": "https://www.example-crm.com/deals/1", // Ссылка на связанную сущность
"responsible": "Manager #1" // Имя ответственного менеджера
}
}
Пример ответа в случае успеха:
{
"status":"Success",
"data": {
"notificationId": 1985837794 // id отправленного уведомления
}
}
Параметр notificationId, возвращаемый в data, может быть использован для последующего сокрытия отправленных уведомлений.
Возможные ошибки:
No users was specified for notifications send | Не было указано ни одного пользователя для отправки уведомления |
Data fields is all null | Не указано значение ни одного параметра объекта data |
User with id *xxxx* not found | Пользователь с указанным id не был найден |
No users with connected chrome extension was found | Указанные пользователи не подключили Web Dialer |
Для сокрытия отправленных уведомлений в Web Dialer необходимо указать id пользователей, у которых необходимо скрыть уведомление, в параметре userIds и notificationId, полученный при отправке уведомления.
Относительный путь: /widget/hideNotification
Режим: POST
Content-Type: application/json
Пример JSON запроса:
{
"userIds": [ // Массив id пользователей
5701, 5800, 4560
],
"notificationId": 1551593033 // id целевого уведомления
}
Ответ в случае успеха:
{"status": "Success"}
Возможные ошибки:
No users was specified for notifications hide | Не было указано ни одного пользователя для скрытия уведомления |
NotificationId not specified | notificationId не указан |
The specified users are not found or chrome extension not connected | Указанные пользователи не найдены или у них не подключен Web Dialer |