Про API
Сopied
Для работы Вам понадобится ключ (токен) доступа к API.
Ключ позволяет идентифицировать Ваш проект и получать к нему доступ с максимальными привилегиями без необходимости предварительной авторизации каждый раз.
На странице личного кабинета «API» необходимо создать ключ:
Этот ключ необходимо указывать при каждом запросе в заголовке Authorization.
Все относительные пути всех методов, описанных в этой документации, имеют пути относительно: https://api.unitalk.cloud/api
Все запросы к методам API выполняются в режиме POST.
Пример указания режима, необходимого заголовка авторизации и адреса метода для запроса в Postman выглядит следующим образом:
Также можно отправлять ключ в формате «Bearer *Ваш ключ*»
В случае если заголовок или ключ в нем авторизации будет отсутствовать или указан неверно, результат выполнения метода
будет следующим:
{"status": "Error", "message": "Authorization invalid"}Любой метод из описанного API может вернуть ошибку:
{"status": "Error", "message": "Internal error"}О таких ошибках сообщайте, пожалуйста, в техническую поддержку.
В общем случае ошибки выполнения методов имею следующую структуру:
{
"status": "Error",
"message": "*Текст ошибки*",
"data": "*Дополнительная информация*"
}Далее в этой инструкции будут рассматриваться поля message и data (если присутствует).
Запросы, в которых используются URL параметры, можно также отправлять передавая соответствующие параметре в теле и используя:
Content-Type: application/x-www-form-urlencoded
Да, мы знаем что в JSON не может быть комментариев, но уверены что так понять будет проще 🙂
Тарификация
Сopied
Наше API довольно быстрое, и большинство ваших запросов будет занимать миллисекунды, потому что мы любим кэшировать все, что только можно. Но некоторые могут быть сложнее, поэтому обращайте внимание на время их выполнения.
Обработка до 50 мс — считается одним запросом.
<200 мс — 2 запроса
<500 мс — 3 запроса
<1000 мс — 4 запроса
>1000 мс — 5 запросов
Рекомендации по снижению стоимости и увеличению скорости:
Обратите внимание, что вы можете иногда кардинально ускорить обработку, если используете фильтр по полному совпадению, а не частичному. Или иногда запросить больше информации и отфильтровать результат может оказаться быстрее, чем сделать несколько запросов со сложными фильтрами. Не обходите стороной пакетные запросы, как в обзвонах, ведь добавить 1000 номеров в обзвон одним запросом значительно быстрее и дешевле и вам, и нам, чем делать 1000 запросов (а если все они еще и прилетят одновременно — у нас и DOS-защита может сработать). А иногда можно использовать кэш, как это любим мы 😊
Информацию об использовании запросов по вашему тарифу вы можете посмотреть в разделе «Мой тариф» в личном кабинете.
Лимиты
Сopied
Для избежания излишней нагрузки в результате нецелевых, вредоносных или избыточных запросов существуют ограничения. Если представленные ограничения недостаточны для полноценного использования услуг или привели к случайно блокировке, обратитесь в техническую поддержку.
Ограничения количества любых HTTP запросов:
· Более 30 запросов за 10 секунд — временная блокировка;
· Повторное первышение — временная блокировка повышенной длительности;
· Более 100 запросов за 10 секунд — постоянная блокировка.
Ограничение одновременных API звонков: 20 одновременных звонков.
Ограничение запросов API звонков: 15 за секунду.
Обзвон номеров
Сopied
Работа с обзвонами выполняется с помощью действий, метод :
Относительный путь: /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 | Неверно указано целевое действие |
Получение списка обзвонов
Сopied
JSON запроса:
{
"action": "GET_LIST"
}Пример ответа в случае успеха:
[ // Массив обзвонов
{
"id": 111, // Уникальный идентификатор обзвона
"name": "Sample_name", // Название обзвона
"type": "AUTODIAL" // Тип обзвона
},
...
]Существующие типы обзвонов приведены в соответствующем словаре.
Получение полной информации про обзвоны с дополнительными данными
Сopied
Действие «Получить список обзвонов с дополнительными данными» позволяет получить детальную информацию о текущей конфигурации обзвонов проекта в массиве 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 запроса:markAsBusyMinSecondsTalkJSON запроса:
{
"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": 6, // Количество завершенных звонков
"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
"pseudoGroupOperators": [ // Список SIP линий на который будут перенаправляться звонки обзвона. Присутствует в обзвонах с типом GUARANTEED_DIAL или режимами FREE и SMART
"1000",
"1001"
],
"scenarioId": 70, // ID входящего сценария, который будет активирован, если клиент останется на линии после завершения аудио. Может быть null. Присутствует в обзвонах с типом AUTODIAL
"outScenarioId": 567, // ID исходящего сценария, который будет использован для звонков обзвона. Может быть null
"dialToClientTimeout": 55, // Таймаут вызова абоненту. Может быть null
"pauseOperatorNoAnswerLimit": 5, // Количество звонков подряд не отвеченных оператором, после которого он будет поставлен на паузу. Может быть null. Присутствует в обзвонах с режимами FREE и SMART
"ttsSettingsId": 18, // ID профиля настроек синтеза речи. Может быть null. Присутствует в обзвонах с типами AUTODIAL и GUARANTEED_DIAL
"useTaskAudioIfAudioError": false, // При ошибке аудио: true - “Использовать аудио обзвона”, false - “Завершить звонок с ошибкой”. Присутствует в обзвонах с типами AUTODIAL и GUARANTEED_DIAL
"repeatCallsSettings": { // Настройки повторного прозвона. Может быть null
"earlyStart": true, // Отвечает за ранний повторный обзвон. Если false или в обзвоне более 1 000 000 номеров - повторный обзвон начнет срабатывать только когда закончатся необработанные номера
"highPriority": true, // Отвечает за необходимость внесения повторных прозвонов в приоритетную очередь
"statesSettings": { // Массив статусов звонков, которые будут повторно прозваниваться. Может быть пустым или null, если repeatCallAttempts null
"ANSWER": {
"attempts": 2, // Количество повторных прозвонов. Доступны значения от 0 до 10. Значения 0 и null отключают повторный прозвон
"intervalMinutes": 15, // Минимальный интервал повторных прозвонов в минутах. Доступны значения от 5 до 1500
"secondsThreshold": 20 // Прозвонить повторно, если разговор длился менее чем
},
"NOANSWER": {
"attempts": 30, // Количество повторных прозвонов. Доступны значения от 0 до 10. Значения 0 и null отключают повторный прозвон
"intervalMinutes": 60 // Минимальный интервал повторных прозвонов в минутах. Доступны значения от 5 до 1500
},
...
}
},
"callerIdPrefix": "pref", // Префикс, который будет отображаться в SIP клиенте перед номером телефона. Может быть null
"crmMode": "DONT_SEND", // Определяет какие звонки будут отправлены в CRM
"clientCalledMode": "NEVER", // Указывает на необходимость игнорировать номера абонентов, от которых поступали звонки
"displayName": false, // Показывать имя закрепленное за номером в SIP клиенте
"displayNote": false, // Показывать примечание к номеру в SIP клиенте
"removeAfterFinish": false, // Удалить обзвон после завершения
"markAsBusySeconds": 60, // Количество секунд на которое SIP линия отмечается занятой после успешного звонка. Присутствует в обзвонах с режимами FREE и SMART
"markAsBusyMinSecondsTalk": 15, // Количество секунд на которое SIP линия отмечается занятой после успешного звонка. Присутствует в обзвонах с режимами FREE и SMART
"reservedSipsBusyOnlyForAutodials": true, // Указывает на доступность внутренних линий для звонков, поступающих по входящим сценариям. Присутствует в обзвонах с режимами FREE и SMART
"triggerActions": { // Список событий и обработчиков за ними закрепленными
"AUTODIAL_NOANSWER": [ // "Событие": Массив закрепленных обработчиков
2, // ID обработчика событий
...
]
},
"withdrawalStatistics": { // Массив с информацией про общие траты обзвона
"total": "12.47", // Сумма списаний по всем категориям
"byCategories": { // Массив сумм списаний по категориям
"CALL": "0.60",
...
}
},
"repeatCallAttempts": 30, // [Устаревший параметр] Количество повторных прозвонов. Доступны значения от 0 до 10. Значения 0 и null отключают повторный прозвон
"repeatCallIntervalMinutes": 60, // [Устаревший параметр] Минимальный интервал повторных прозвонов в минутах. Доступны значения от 5 до 1500
"repeatCallStates": [ // [Устаревший параметр] Массив статусов звонков, которые будут повторно прозваниваться. Может быть пустым или null, если repeatCallAttempts равно 0 или null
"NOANSWER",
...
],
"repeatCallHighPriority": true, // [Устаревший параметр] Значение true указывает на необходимость внесения повторных прозвонов в приоритетную очередь
"repeatCallEarly": true, // [Устаревший параметр] // Значение true указывает на необходимость запуска повторных звонков
"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 // Свидетельствует о возможных проблемах в настройках обзвона или телефонии
},
...
]
}
Создание и изменение обзвонов
Сopied
Действия «Создать» и «Изменить» позволяют конфигурировать новый или существующий обзвоны соответственно. Часть параметров является общей для всех типов и режимов обзвонов. Создание и изменение обзвонов будет рассмотрено на примере одного запроса, поскольку различия незначительны:
· 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"
"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
"dialToClientTimeout": null, // Таймаут вызова абоненту. Допустимые значения от 10 до 55. Может быть null (по умолчанию 55 секунд).
"triggerActions": { // Список событий и обработчиков за ними закрепленными. К одному событию можно прикрепить максимум 5 обработчиков
"AUTODIAL_NOANSWER": [ // "Событие": Массив закрепленных обработчиков
2, // ID обработчика событий
...
],
...
},
"callerIdPrefix": "pref", // Префикс, который будет отображаться в SIP клиенте перед номером телефона. Может быть null
"crmMode": "DONT_SEND", // Определяет какие звонки будут отправлены в CRM
"clientCalledMode": "NEVER", // Указывает на необходимость игнорировать номера абонентов, от которых поступали звонки
"repeatCallsSettings": { // Настройки повторного прозвона. Может быть null
"earlyStart": true, // Отвечает за ранний повторный обзвон. Если false или в обзвоне более 1 000 000 номеров - повторный обзвон начнет срабатывать только когда закончатся необработанные номера
"highPriority": true, // Отвечает за необходимость внесения повторных прозвонов в приоритетную очередь
"statesSettings": { // Массив статусов звонков, которые будут повторно прозваниваться.
"ANSWER": {
"attempts": 2, // Количество повторных прозвонов. Доступны значения от 0 до 10. Значения 0 и null отключают повторный прозвон
"intervalMinutes": 15, // Минимальный интервал повторных прозвонов в минутах. Доступны значения от 5 до 1500
"secondsThreshold": 20 // Прозвонить повторно, если разговор длился менее чем
},
"NOANSWER": {
"attempts": 30, // Количество повторных прозвонов. Доступны значения от 0 до 10. Значения 0 и null отключают повторный прозвон
"intervalMinutes": 60 // Минимальный интервал повторных прозвонов в минутах. Доступны значения от 5 до 1500
},
...
}
},
"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 или в параметре pseudoGroupOperators.
Пример специфической для типа обзвона GUARANTEED_DIAL части JSON запроса:
...
"moh": 255, // ID аудио, которое клиент будет слышать ожидая соединение с оператором. Может быть null
"groupId": 300, // ID отдела телефонии на который будут перенаправляться звонки обзвона
"pseudoGroupOperators": ["1000", ...], // Список SIP линий на который будут перенаправляться звонки обзвона.
"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 или в параметре pseudoGroupOperators. Кроме того доступны дополнительные параметры:
· coldBaseStartCallsMultiplier — Изменяет количество одновременных звонков в зависимости от процента дозвона с указанным коэффициентом. Доступны значения от 0.1 до 1.5
· pauseOperatorNoAnswerLimit — Количество звонков подряд не отвеченных оператором, после которого он будет поставлен на паузу
· markAsBusySeconds — Количество секунд на которое SIP линия отмечается занятой после успешного звонка. Доступны значения от 0 до 3600
· markAsBusyMinSecondsTalk — Минимальная длительность звонка для срабатывания настройки markAsBusySeconds в секундах. Доступны значения от 0 до 3600
· reservedSipsBusyOnlyForAutodials — Определяет будут ли внутренние линии из закрепленной группы обзвона доступны для звонков, поступающих по входящим сценариям
Пример специфической для режима обзвона FREE части JSON запроса:
...
"groupId": 300, // ID отдела телефонии на который будут перенаправляться звонки обзвона
"pseudoGroupOperators": ["1000", ...], // Список SIP линий на который будут перенаправляться звонки обзвона.
"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 отдела телефонии на который будут перенаправляться звонки обзвона
"pseudoGroupOperators": ["1000", ...], // Список SIP линий на который будут перенаправляться звонки обзвона.
"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 and pseudoGroupOperators is null | Тип обзвона GUARANTEED_DIAL или режим FREE или SMART, но поле groupId или pseudoGroupOperators не указано в запросе |
| Operator not found: … | В поле pseudoGroupOperators указано некорректные или отсутствующие SIP-линии |
| 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 | Превышено максимальное количество обзвонов в проекте |
Удаление обзвона
Сopied
Пример JSON запроса:
{
"id": 1307, // ID целевого обзвона
"action": "REMOVE"
}Ответ в случае успеха:
{"status": "Success", "message": "Removed"}Возможные ошибки:
| Task not found | Обзвон не найден по указанному id |
| Handler is busy, try again later | Один проект одновременно может удалять или добавлять номера только в одном обзвоне. В этот момент в одном из обзвонов проекта происходит удаление или добавление номеров. Повторите попытку позже, когда предыдущая операция завершится |
Прозвонить повторно
Сopied
Действие «Прозвонить повторно» позволяет перезапустить обработку номеров находящихся в указанных статусах. Перечень статусов допустимых для использования в данном действии приведен в соответствующем словаре.
Пример 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 | Не найдено ни одного номера с указанными статусами |
Отмена обзвона
Сopied
Действие «Отменить обзвон» позволяет остановить обзвон, находящийся в статусе 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 |
Постановка на паузу
Сopied
Действие «Поставить на паузу» позволяет приостановить обзвон, находящийся в статусе 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 |
Снятие с паузы
Сopied
Действие «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 |
Добавление номеров
Сopied
Действие «Добавить номера» позволяет добавить номера в обзвон двумя способами: указав только номера в массиве 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 |
| Not found in scenario and audio | В автообзвоне не указаны ни аудио, ни входящий сценарий |
| Voice secretary not found | В обзвоне голосовым роботом не указан голосовой робот |
| Group not found | В предиктивном обзвоне не указана группа операторов |
| Too many params | В params передано более 10 параметров |
| Wrong parameter key | В params передан ключ, который не является числом из диапазона от 1 до 10 |
| Billing not allow | Тариф проекта неактивен или недостаточный баланс |
Получение информации про номер обзвона
Сopied
Пример JSON запроса:
{
"id": 1307, // ID целевого обзвона
"action": "GET_NUMBER",
"number": "380971234567" // Номер телефона
}Пример ответа в случае успеха:
{
"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 | Номер не найден в обзвоне |
Получение информации про все номера обзвона
Сopied
Для получения информации про все номера обзвона необходимо указать id целевого обзвона. Количество записей, которые будут получены при этом не превышает значение параметра limit. По умолчанию limit равен 1000, максимальное значение — 5000. Для получения следующей группы записей, необходимо в параметре offest указать сдвиг относительно начала списка. Кроме того, записи можно предварительно отфильтровать по целевым статусам номеров, перечень которых приведен в соответствующем словаре.
Пример JSON запроса:
{
"id": 1307, // ID целевого обзвона
"action": "GET_NUMBERS",
"limit": 2000, // Максимальное количество номеров, которые будут возвращены в ответе
"offset": 4000, // Сдвиг возвращаемых записей относительно начала списка
"callStates": [ // Массив целевых статусов звонков. Может быть null или пустой
"NOANSWER",
...
]
}Пример ответа в случае успеха:
[ // Массив номеров обзвона с дополнительной информацией
{
"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 должно быть положительным |
Получение информации про звонки обзвона
Сopied
Для получения информации про звонки обзвона необходимо, кроме действия, указать id целевого обзвона и параметр 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 — массив статусов звонков обзвонов. Перечень приведен в соответствующем словаре;
· phone — часть номера абонента. Все сторонние символы будут предварительно удалены;
· operatorNumber — точный номер оператора. Все сторонние символы будут предварительно удалены;
· name — часть имени, закрепленного за номером обзвона на момент звонка;
· note — часть заметки, закрепленной за номером обзвона на момент звонка;
· link — часть данных для Web Dialer, закрепленных за номером обзвона на момент звонка;
· param — часть любого из параметров, закрепленных за номером обзвона на момент звонка;
· voiceSecretaryIds — массив id голосовых роботов, которые были использованы в звонке;
· voiceSecretaryEndReasons — массив причин завершения голосового робота, который был использован в звонке. Перечень приведен в соответствующем словаре;
· voiceSecretaryEndNodeTypes — массив типов конечного узла голосового робота, который был использован в звонке. Перечень приведен в соответствующем словаре.
Пример JSON запроса:
{
"action": "GET_CALLS_HISTORY",
"id": 300, // Обязательный параметр. Идентификатор целевого обзвона
"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",
...
],
"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, // Идентификатор звонка
"phone": "380681234567", // Номер телефона
"state": "ANSWER", // Статус завершения звонка
"callEndTime": "2023-10-24 16:15:43", // Дата и время завершения звонка
"operatorNumber": "2045", // Номер оператора. Может быть null
"userId": 15, // Идентификатор оператора. Может быть null
"calledCount": 1, // Количество дозвонов
"realCalledCount": 2, // Всего дозвонов
"seconds": 3, // Тарифицируемое время звонка. Может быть null
"secondsForClientAnswered": 16, // Время ожидания до ответа клиента на звонок. Может быть null
"secondsDialToClient": 16, // Время набора номера до того, как клиент ответит или отклонит вызов. Может быть 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
},
...
]
}
},
...
]
}Возможные ошибки:
| Task not found | Обзвон не найден по указанному id или параметр id не указан |
| Limit range is 1-5000 | Значение limit не в диапазоне от 1 до 5000 |
| Offset is less than 0 | Значение offset должно быть положительным |
| callHistoryRequest is null | Не указан параметр callHistoryRequest |
| Invalid date from | Некорректная дата и время «от» в фильтрах |
| Invalid date to | Некорректная дата и время «до» в фильтрах |
Удаление номеров
Сopied
Действие «Удалить номера» позволяет удалить номера из обзвона двумя способами: указав номера или статусы номеров на удаление. Перечень необходимых номеров указывается в параметре запроса 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 | Один проект одновременно может удалять или добавлять номера только в одном обзвоне. В этот момент в одном из обзвонов проекта происходит удаление или добавление номеров. Повторите попытку позже, когда предыдущая операция завершится |
Удаление всех номеров
Сopied
Пример 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 | Один проект одновременно может удалять или добавлять номера только в одном обзвоне. В этот момент в одном из обзвонов проекта происходит удаление или добавление номеров. Повторите попытку позже, когда предыдущая операция завершится |
Словари
Сopied
autodialerType
Сopied
Типы обзвонов:
| AUTODIAL | Автообзвон. Используется преимущественно для информирования клиентов или проведения опросов. Звонки автообзвонов проходят в соответствии с указанным входящим сценарием |
| GUARANTEED_DIAL | Гарантированный дозвон. Используется преимущественно для оптимизации рабочего времени операторов. Звонки гарантированных дозвонов распределяются напрямую на операторов указанной группы внутренних линий |
| VOICE_ROBOT | Голосовой робот. Используется преимущественно для информирования клиентов или проведения опросов. При звонках голосовым роботом воспроизводиться указанный голосовой робот |
autodialerMode
Сopied
Режимы обзвонов:
| FIXED | По количеству потоков |
| FREE | По свободным операторам |
| SMART | Умный подбор |
taskStatus
Сopied
Статусы обзвонов:
| NO_NUMBERS | Номера не добавлены |
| IN_PROGRESS | В процессе обзвона |
| WAITING | В ожидании начала обзвона |
| WAITING_OPERATORS | Ожидание свободных операторов |
| WAITING_REPEAT | Ожидание срабатывания настройки «Повторный звонок» |
| PAUSED | На паузе |
| CANCELED | Отменен, но еще не успел завершиться (часть номеров обзвона находятся в статусе DIALING) |
| FINISHED | Завершен |
audioSynthesisDynamicValues
Сopied
Динамические значения для синтеза аудио:
| 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 |
callState
Сopied
Состояния номера обзвона:
| Статус | Название статуса | Доступен для автоматического повторного прозвона (поле 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 | Отменено автоматически | — | + | + | — |
triggerActionEvent
Сopied
События обзвонов и звонков обзвонов:
| 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 | Обзвон завершен |
voiceSecretaryEndNodeTypes
Сopied
Типы конечных узлов голосовых роботов:
| INTERMEDIATE | Промежуточный |
| END_SUCCESS | Успешный |
| END_FAIL | Неуспешный |
| BACKGROUND | Фоновый |
| BACKGROUND_DEFER | Фоновый — перенос звонка |
voiceSecretaryEndReasons
Сopied
Причины завершения голосовых роботов:
| NORMAL | Закончился нормально |
| USER_REJECT | Абонент завершил разговор |
| GREETING_SILENCE | Абонент молчал во время приветствия |
| ANSWERING_MACHINE | Распознан автоответчик |
| RECOGNITION_ERROR | Распознавание речи прервалось по техническим причинам |
| JUMP_LIMIT | Превышен лимит выполненных действий «Перейти на другой узел» |
| NODE_LIMIT | Превышен лимит пересеченных узлов |
| FAIL | Неизвестная ошибка |
Управление звонками
Сopied
Все методы инициации звонков поддерживают опциональный параметр meta. В параметре можно передать до 1000 символов любой информации, которая впоследствии будет отображена в вебхуках, что может быть использовано для присвоения собственного идентификатора звонка.
Прямой вызов SIP -> GSM
Сopied
Для инициации звонка с внутренней линии необходимо указать номер внутренней линии в параметре sip и мобильный номер, на который необходимо совершить звонок, в международном формате в параметре number. Этот метод позволяет инициировать звонок без ввода номера оператором и широко применяется в интеграционных целях.
Относительный путь: /phones/directCall
Режим: POST
Content-Type: —
Пример запроса:
/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 символов |
Информирующий звонок
Сopied
Для инициации информирующего звонка, который будет исполнен без участия оператора, необходимо указать мобильный номер, на который необходимо совершить звонок, в международном формате в параметре 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 символов |
Независимый Сlick to call
Сopied
Для инициации звонка, аналогичного по принципу работы с 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 символов |
Сброс звонка
Сopied
Для сброса активного звонка необходимо указать как минимум один из обязательных параметров:
· id — Уникальный идентификатор звонка. Может быть получен из истории или в вебхуках;
· number — Номер внутренней или внешней линии. Будут сброшены все найденные звонки с участием указанного номера.
Относительный путь: /calls/hangup
Режим: POST
Content-Type: application/json
Примеры JSON запросов:
{
"number": 380123456789
}{
"id": 1234567890
}Пример ответа в случае успеха:
{"status": "Success","message": "Found: 1"}Возможные ошибки:
| Empty request | Не указан ни id, ни number |
Вызов суфлера
Сopied
Для инициации подключения суфлера необходимо указать два обязательных параметра:
· 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 | Линия суфлера не в сети |
Речевая аналитика
Сopied
Для активации речевой аналитики по звонку необходимо указать два обязательных параметра:
· callId — Идентификатор звонка. Может быть получен по API из истории звонков или в вебхуках по звонкам;
· profileId — Идентификатор профиля аналитики. Может быть получен на странице личного кабинета «Речевая аналитика — Профили» в списке профилей аналитики.
Относительный путь: /calls/analytics/create
Режим: POST
Content-Type: —
Запуск аналитики возможен только по тем звонкам, для которых были сохранены раздельные записи.
Ответ на запрос будет отправлен после окончания обработки звонка, следовательно рекомендуется значительно повысить время ожидания ответа для запросов к данному методу.
Максимально одновременных звонков в обработке — 50.
Пример запроса:
/calls/analytics/create?callId=1234&profileId=123
Пример ответа в случае успеха:
{
"profileId": 123, // Идентификатор профиля, который использовался для запроса речевой аналитики
"profileName": "Sample Name", // Название использованного профиля речевой аналитики
"transcription": "00:00:00,000-->00:00:15,000\nOperator: Hello! This is sample speech", // Экранированная транскрипция диалога
"operatorTag": "Operator", // Действующее лицо, которое считается оператором
"analyticsJson": "{\"dialogTopic\":{\"metricId\":1234,\"metricName\":\"Dialog topic\",\"value\":\"Voice message\",\"position\":0}, ... }",
// Экранированная cтрока, содержащая JSON с результатом аналитики (метриками) по звонку.
// Каждый ключ (например, "dialogTopic" и т.д.) представляет метрику,
// имеющую следующие параметры:
// - metricId: уникальный идентификатор метрики;
// - metricName: название метрики;
// - value: значение метрики (число, строка, логическое да/нет, список или объект);
// - position: позиция метрики для сортировки или отображения.
"analyticsSchema": "{\"$schema\":\"http://json-schema.org/draft-04/schema#\",\"type\":\"object\",\"properties\":{\"dialogTopic\":{\"type\":\"object\",\"properties\":{\"metricId\":{\"type\":\"integer\"},\"metricName\":{\"type\":\"string\"},\"value\":{\"type\":\"string\"},\"position\":{\"type\":\"integer\"}}}, ... }}",
// Строка, содержащая JSON Schema, описывающую структуру объекта analyticsJson.
// Схема используется для валидации метрик и содержит описание типов для каждого параметра.
"languageData": { // Объект, в котором содержатся данные о языках аналитики
"operatorLanguage": "english", // Язык речи оператора
"clientLanguage": "english", // Язык речи клиента
"transcriptionLanguageCode": "en", // ISO код языка полученной транскрипции
"analyticsLanguageCode": "en", // ISO код языка, на котором были сформированы результаты аналитики
"translatedLangCode": null, // ISO код языка, на который был осуществлен перевод аналитики. Если перевод не производился, значение null.
"translatedLangName": null // Название языка, на который был осуществлен перевод аналитики. Если перевод не производился, значение null.
},
"plainTranscription": "Operator: Hello! This is sample speech" // Транскрипция диалога
}Параметр ответа 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 | На балансе проекта недостаточно средств |
Аудио
Сopied
Добавление аудио файлов в проект
Сopied
Для добавления аудио в проект в 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 добавленного аудио файла.
Синтез аудио
Сopied
Для добавления в проект синтезированных аудио необходимо указать массив данных для синтеза в параметре 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 | Ошибка оплаты. Возможные причины: · Тариф проекта не активен · На счету проекта нет средств |
Списки
Сopied
Работа с списками осуществляется с помощью действий, метод:
Относительный путь: /lists
Режим: POST
Content-Type: application/json
Целевой список указывается в теле запроса в обязательном параметре list. Перечень существующих списков:
· BLOCKED_PHONES — Список заблокированных номеров в международном формате, взаимодействие с которыми отклоняется;
· BLOCKED_FOR_AUTODIAL_PHONES — Список номеров в международном формате, которые нельзя добавить в обзвоны.
Действия указываются в теле запроса в обязательном параметре operation. Перечень существующих действий:
· GET — Получение текущего списка;
· ADD — Добавление элементов в список;
· REMOVE — Удаление элементов из списка.
Для действий ADD и REMOVE обязательно указание массива элементов которые будут добавлены или удалены в параметре items. Максимальное количество элементов в массиве items — 100.
Заблокированные номера
Сopied
Список заблокированных номеров в международном формате, взаимодействие с которыми отклоняется. Для работы с списком заблокированных номеров в обязательном параметре 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"}
Исключенные из обзвонов номера
Сopied
Список номеров в международном формате, которые нельзя добавить в обзвоны. Для работы с списком номеров, которые нельзя добавить в обзвоны, в обязательном параметре 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"}
Пользователи
Сopied
История работы
Сopied
История работы позволяет получить суммированную информацию о длительности пребывания пользователей в разных статусах работы за определенную дату. Для этого необходимо указать целевую дату в обязательном параметре date в формате «yyyy-MM-dd».
Относительный путь: /users/workHistory
Режим: POST
Content-Type: —
Пример запроса:
/users/workHistory?date=2024-01-01
Пример ответа в случае успеха:
{
"users": {
"12345": { // "Уникальный идентификатор пользователя": Массив с информацией о соответствующем пользователе
"firstName": "John", // Имя пользователя
"lastName": "Callid", // Фамилия пользователя. Может быть null
"phone": 1234, // Номер закрепленный за пользователем. Может быть null
"userTimeSeconds": { // Массив с информацией о времени пребывания в разных статусах
"byPauses": { // Массив с информацией о времени пребывания в разных видах пауз
"Launch": 1800, // "Название вида статуса ": Количество секунд проведенных в соответствующем виде статуса
...
},
"byWork": { // Массив с информацией о времени пребывания в разных видах статуса "Работает"
"Cold Calling": 18000, //"Название вида статуса ": Количество секунд проведенных в соответствующем виде статуса
...
},
"byStop": { // Массив с информацией о времени пребывания в разных видах статуса "Не работает"
"Non-working hours": 54000, // "Название вида статуса ": Количество секунд проведенных в соответствующем виде статуса
...
},
"stop": 54000, // Количество секунд в статусе "Не работает"
"work": 28800, // Количество секунд в статусе "Работает"
"pause": 3600 // Количество секунд на паузе
},
"middleName": "Triple" // Отчество. Может быть null
},
...
}
}Отсчет количества секунд проведенных пользователем в определенном статусе начинается с первого изменения статуса после создания и добавления пользователя в проект.
Возможные ошибки:
| Future data is absent | Указана будущая дата, соответствующие данные отсутствуют |
Список пользователей
Сopied
Для получения списка пользователей и данных о них необходимо отправить пустой запрос.
Относительный путь: /users/list
Режим: POST
Content-Type: —
Пример ответа:
[
{
"email": "example@gmail.com",
"firstName": "John", // Имя пользователя
"lastName": "Callid", // Фамилия пользователя. Может быть null
"middleName": "Triple" // Отчество. Может быть null
"phone": 1234, // Номер закрепленный за пользователем. Может быть null
"role": "ADMIN", // Роль пользователя в проекте
"id": 12345, // Уникальный идентификатор пользователя
"workStatus": "WORK", // Статус работы пользователя
"workStatusName": "Cold Calling" // Название вида статуса. Может быть null
},
...
]
Получение статусов пользователей
Сopied
Для получения списка пользователей и данных о их статусе работы необходимо отправить пустой запрос.
Относительный путь: /users/getStatus
Режим: POST
Content-Type: —
Пример ответа:
[
{
"firstName": "John", // Имя пользователя
"lastName": "Callid", // Фамилия пользователя. Может быть null
"middleName": "Triple" // Отчество. Может быть null
"phone": 1234, // Номер закрепленный за пользователем. Может быть null
"workStatus": "WORK", // Статус работы пользователя
"workStatusName": "Cold Calling" // Название вида статуса. Может быть null
},
...
]
Изменение статуса работы
Сopied
Для изменения статуса работы пользователя необходимо указать нормер линии оператора в параметре number, новый статус работы в параметре status. Допустимые значения: WORK («Работает»), STOP («Не работает»), PAUS («Пауза»). Опционально в параметре statusName можно указать название статуса работы, которое должно полностью совпадать с одним из существующих в проекте.
Относительный путь: /phones/inner/setStatus
Режим: POST
Content-Type: —
Пример запроса:
/phones/inner/setStatus?number=1234&status=WORK&statusName=Cold Calling
Ответ в случае успеха:
{"status": "Success", "message": "Success"}
Внутренние линии
Сopied
Для получения списка внутренних линий и текущего их статуса необходимо отправить пустой запрос. В ответе будет возвращен ассоциативный массив, где ключ — номер внутренней линии, а значение — её текущий статус. Возможные статусы: online (линия в сети и не занята), busy (линия в сети и занята звонком) и offline (линия не в сети).
Относительный путь: /phones/inner
Режим: POST
Content-Type: —
Пример ответа:
{
"2022": "offline"
"2023": "busy",
"2024": "online",
...
}
Отделы
Сopied
Получение групп
Сopied
POST /groups/action
Пример body JSON запроса:
{
"action": "GET"
}Ответ:
{
"status": "Success",
"data": [
{
"id": 455, // id группы
"name": "Отдел продаж", // имя группы
"phones": [ // Массив номеров которые содержит группа
{
"number": "4030", // номер
"firstName": "Александр", // имя пользователя, если он есть
"lastName": "Максимов" // фамилия пользователя, если он есть
}
]
}
]
}
Удаление номера из группы
Сopied
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 | группа не содержит указанный номер |
Добавление номера в группу
Сopied
POST /groups/action
Пример body JSON запроса:
{
"action": "ADD_NUMBER",
"groupId": "5859",
"number": "2222"
}Успех:
{"status": "Success"}Возможные ошибки:
| Group not found | указанный id ссылается на неизвестную группу |
| GSM number is not valid | в группу GSM добавляется номер в неверном формате |
| Group is already contains specified number | линия уже в группе |
| Project does not contain the specified sip number | линия не найдена |
Создание группы
Сopied
POST /groups/action
Создает группу SIP-линий с указанными номерами
Пример body JSON запроса:
{
"action": "CREATE",
"name": "Group name",
"numbers": ["2224"]
}Успех:
{
"status": "Success",
"data": {
"id": 2925,
"name": "Group name",
"phones": [
{
"number": "2224",
"firstName": "John",
"lastName": "Dou"
}
]
}
}Возможные ошибки:
| Group already exists | группа с таким названием уже существует |
| Numbers is empty | не указаны номера линий |
| Not found: 2224 | SIP-линия 2224 не найдена в проекте |
Статистика по операторам
Сopied
Для получения статистики по операторам проекта необходимо указать начало и конец интересующего периода в параметрах from и to соответственно, в формате “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, // По входящим: Пропущенных неотвеченных
"inHangupByOperatorCount": 123, // Количество входящих, скинутых оператором
"inHangupByClientCount": 123, // Количество входящих, скинутых клиентом
"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 | Не указаны или некорректны дата и время конца целевого периода |
callType
Сopied
Типы источников звонков:
| AUTO_CB | Автоперезвон |
| AUTODIAL | Обзвон |
| REGULAR | Прямой звонок |
| C2C_FORM | Форма обратного звонка |
| API | API звонок |
| TRACKING | Call Tracking |
| CALLBACK | Callback |
| C2C_BUTTON | Кнопка обратного звонка |
| C2C_API | API обратный звонок |
История звонков
Сopied
Для получения истории звонков проекта необходимо указать начало и конец интересующего периода в параметрах dateFrom и dateTo соответственно, в формате “yyyy-MM-dd HH:mm:ss”. Записи возвращаются в порядке убывания id. Количество записей, которые будут получены при этом не превышает значение обязательного параметра limit. Допустимый диапазон limit — от 1 до 1000. Для получения следующей группы записей необходимо в параметре offset указать сдвиг относительно начала списка.
Относительный путь: /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 |
Вебхуки
Сopied
Вы можете использовать систему вебхуков для получения информации о событиях телефонии. Кроме того, UniTalk поддерживает входящие вебхуки.
Движение по балансу
Сopied
Вебхук «Движение по балансу» предоставляет информацию по каждой операции изменения баланса проекта и не может быть конфигурирован, поскольку события данной категории обрабатываются системой автоматически. Для работы с этим вебхуком Ваше веб-приложение должно принимать 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" // Описание операции
}
Обработка событий
Сopied
Отправка вебхука может быть выбрана в качестве типа действия при создании или редактировании действий на странице личного кабинета «Обработка событий». При конфигурации действия данного типа можно указать:
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" // !
}
Удаление отложенных обработчиков событий
Сopied
Для удаления отложенных обработчиков событий необходимо указать список телефонных номеров в международном формате, обрабочики событий для которых будут удалены.
Относительный путь: /api/eventHandlers/removeScheduledByPhones
Метод: POST
Content-Type: application/json
Пример JSON запроса:
{
"phones": [ // Массив номеров клиентов
"380123456789",
...
]
}Пример ответа в случае успеха:
{"status": "Success", "data": 12345}В случае успешного выполнения запроса, в параметре data будет возвращено количество удаленных обработчиков.
Возможные ошибки:
| Phones is not specified | Параметр phones не указан или пустой |
| Too many phones | В параметре phones передали более 100 элементов |
| Invalid phones | В параметре phones присутствуют некорректные номера. В параметре ответа data будет указан массив элементов phones, которые не прошли валидацию |
| Wait until the previous request is processed | Один проект одновременно может запустить только один процесс удаления отложенных обработчиков событий. В этот момент в проекте происходит удаление. Повторите попытку позже, когда предыдущая операция завершится |
Входящие вебхуки
Сopied
UniTalk может принимать вебхуки с определенной структурой и выполнять по ним действия.
Доступные на данный момент действия:
1) «AUTODIAL_ADD» — Добавление номера телефона в обзвон номеров;
2) «AUTODIAL_REMOVE» — Удаление номера телефона из обзвона номеров.
Для использования входящих вебхуков на странице личного кабинета «API« необходимо:
1) Сгенерировать токен:
2) Нажать кнопку «Сгенерировать ссылку«:
3) Выбрать действие, обзвон к которому оно применится, указать дополнительные опции и нажать кнопку «Сгенерировать«:
4) Заполнить параметры ссылки и отправить на неё POST запрос.
Параметры, которые заполняются при генерации автоматически:
| token | Токен для входящих вебхуков |
| action | Тип действия вебхука |
| id | id обзвона номеров |
Добавить номера в обзвон
Сopied
Пример сгенерированной ссылки:
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 | Не получилось добавить номера в обзвон. Возможно номера уже были добавлены в обзвон |
Удалить номера с обзвона
Сopied
Пример сгенерированной ссылки:
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 | Не получилось удалить ни один номер. Возможно в обзвоне не было ни одного из указанных номеров |
Перевод звонка на ответственного оператора
Сopied
Вебхук «Перевод звонка на ответственного оператора» позволяет получить информацию о звонке для последующего выбора ответственного оператора Вашей системой. Для работы с этим вебхуком Ваше веб-приложение должно принимать JSON методом POST по указанному при создании или редактировании входящего сценария на странице личного кабинета «Входящие сценарии», при выборе перенаправления на «На ответственного менеджера» и активации опции «Запрос в Ваш API» URL.
При выполнении данного перенаправления, на указанный URL будет отправлен запрос с следующим содержимым:
{
"event": "ROUTE",
"call": {
"from": "380505557182", // Номер звонящего абонента
"outerNumber": "380442949168" // Внешняя линия, на которую был принят звонок
}
}В ответ Ваше приложение должно отправить JSON следующей структуры:
{
"operatorNumber": "2048", // Номер телефона ответственного оператора. Можно указать SIP или GSM. Может быть null
"callerName": "Александр", // Имя абонента, которое будет отображено в SIP клиенте
"ivrId": 487 // id голосового меню, которое необходимо воспроизвести абоненту. Может быть null
}Предварительно проверять свободен ли в данный момент оператор не нужно: если он занят, перенаправление звонка на него будет пропущено.
Управление очередью с голосовым сопровождением
Сopied
Вебхук «Управление очередью с голосовым сопровождением» позволяет получить информацию о звонке для последующей приоритезации обработки клиентов Вашей системой. Для работы с этим вебхуком Ваше веб-приложение должно принимать 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
}
Сообщения
Сopied
Для отправки сообщений через SMS и Viber на странице личного кабинета «Сервис отправки сообщений» раздела «Интеграция» должна быть подключена интеграция с сервисом отправки сообщений. Доступность типов сообщений и направлений зависит от настройки этой интеграции. Максимальная длина текста для Viber — 1000 символов, для SMS — зависит от сервиса отправки сообщений.
Отправка сообщения
Сopied
Относительный путь: /message/send
Режим: POST
Content-Type: application/json
Пример JSON запроса для SMS:
{
"messageType": "SMS", // Тип сообщения "SMS" (обязательно)
"alfaName": "YourSmsAlphaName", // Альфа-имя отправителя. Релевантно только для провайдера Unitalk, если у вас подключено >1 альфа имени (необязательный параметр)
"to": "380971234567", // Номер телефона получателя в международном формате (обязательно)
"text": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit" // Текст сообщения (обязательно)
}Пример JSON запроса для Viber:
{
"messageType": "VIBER", // Тип сообщения "VIBER" (обязательно)
"alfaName": "YourViberAlphaName", // Альфа-имя отправителя. Релевантно только для провайдера Unitalk, если у вас подключено >1 альфа имени (необязательный параметр)
"to": "380971234567", // Номер телефона получателя в международном формате (обязательно)
"text": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit" // Текст сообщения (обязательно)
}Пример ответа в случае успеха:
{
"status": "Success",
"message": null,
"rus": null,
"data": 1234
}Идентификатор сообщения, возвращаемый в data, может быть использован для последующего получения информации о статусе отправки сообщения.
Возможные ошибки:
| Message service not connected | Не подключен сервис отправки сообщений |
| Validation error | Ошибки валидации. Возможные причины: · Неправильный номер телефона получателя · Отправка сообщений по данному направлению не разрешена настройками интеграции с сервисом отправки сообщений · Не выбран тип сообщения · Отправка SMS отключена в настройках сервиса отправки сообщений · Отправка сообщений в Viber отключена в настройках сервиса отправки сообщений · Сообщение не может быть пустым · Сообщение слишком длинное · Сообщение содержит недопустимые символы |
| UniTalk did not allow sending | UniTalk не разрешил отправку. Возможные причины: · Недоступное направление для отправки · На балансе недостаточно средств · Проект не активен |
| Service response | Ответ сервиса. Возможные причины: · Неверные данные авторизации · Недостаточно средств на балансе · Превышен лимит запросов · Дубль сообщения · IP адрес не разрешен в сервисе отправки сообщений · Имя отправителя заблокировано получателем · Недоступная страна получателя · Номер получателя заблокирован · Недопустимое имя отправителя · Имя отправителя на модерации · Недопустимый номер получателя · Недопустимый текст · Отправка сообщений в Viber недоступна · Данные некорректны · Сервис отправки сообщений временно недоступен |
| Unknown error | Неизвестная ошибка |
Массовая отправка сообщений
Сopied
Для отправки нескольких сообщений одним запросом может быть использована массовая отправка сообщений. Максимальное количество сообщений — 100. Запрос может быть осуществлен в двух вариантах:
· С указанием общего текста сообщений в параметре text и списка номеров телефонов получателей в международном формате в параметре recipients;
· С указанием номеров телефонов получателей в международном формате и соответствующих текстов сообщений парами в массиве messages, где ключ — номер телефона, а значение — текст сообщения.
Если в запросе одновременно указаны параметры обоих способов, будет использован параметр messages.
Относительный путь: /message/sendBulk
Режим: POST
Content-Type: application/json
Примеры JSON запросов:
{
"messagesType": "SMS", // Тип сообщения "SMS"
"recipients": [ // Номера телефонов получателей в международном формате
"380971234567",
"380981234567",
...
],
"text": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit." // Текст сообщения
}{
"messagesType": "SMS", // Тип сообщения "SMS"
"messages": { // Массив сообщений
"380971234567": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit. 1", // "Номер телефона1": "Текст сообщения1"
"380981234567": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit. 2", // "Номер телефона2": "Текст сообщения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, но текст не указан |
Получение статуса отправки сообщения
Сopied
Для получения статуса отправки сообщения необходимо указать идентификатор, полученный при его отправке, в параметре id.
Относительный путь: /message/getStatus
Режим: POST
Content-Type: —
Пример запроса:
/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 не найдено сообщение |
Получение списка расссылок
Сopied
Для получения списка рассылок и связанной информации необходимо отправить пустой запрос.
Относительный путь: /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 — Не подключен сервис отправки сообщений.
Создание рассылки
Сopied
Для создания рассылки в запросе необходимо указать обязательные параметры:
· name — Уникальное название новой рассылки. Максимальная длина — 45 символов;
· messageType — Тип сообщений. «SMS» или «VIBER«;
· numbers — Список номеров телефонов получателей в международном формате. Максимальное количество номеров — 10000;
· text — Текст рассылки. Ограничения зависят от типа сообщений и сервиса отправки сообщений.
Опционально в параметре startTime можно указать дату и время отложенного запуска в формате “yyyy-MM-dd HH:mm:ss”.
Относительный путь: /messageDistribution/create
Режим: POST
Content-Type: application/json
Пример JSON запроса для SMS рассылки:
{
"name": "SmsDistributionName", // Название рассылки (обязательно)
"messageType": "SMS", // Тип рассылки "SMS" (обязательно)
"alphaName": "YourSmsAlphaName", // Альфа-имя отправителя. Релевантно только для провайдера Unitalk, если у вас подключено >1 альфа имени (необязательно)
"numbers": [ // Номера телефонов получателей в международном формате (обязательно)
"380971234567",
"380671234567",
...
],
"content": {
"text": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit" // Текст рассылки (обязательно)
},
"startTime": "2029-07-07 12:00:00" // Дата и время отложенного запуска. Может быть null, в таком случае будет запущена сразу (необязательно)
}Пример JSON запроса для Viber Promo рассылки:
{
"name": "ViberDistributionName", // Название рассылки (обязательно)
"messageType": "VIBER", // Тип рассылки "VIBER" (обязательно)
"viberMessageType": "PROMO", // Тип Viber сообщений "PROMO" (обязательно)
"alphaName": "YourViberAlphaName", // Альфа-имя отправителя. Релевантно только для провайдера Unitalk, если у вас подключено >1 альфа имени (необязательно)
"numbers": [ // Номера телефонов получателей в международном формате (обязательно)
"380971234567",
"380671234567",
...
],
"content": {
"text": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit.", // Текст рассылки (обязательно)
"image": {
"base64Image": "iVBORw0KGgoAAA....", // Картинка в формате base64, которая будет отправлена в рассылке (необязательно)
"mimeType": "image/png", // mimeType для вашего base64 изображения (обязательно, если используется base64Image)
"fileName": "promo_image" // Название файла с изображением до 20 символов, может быть использовано как метаданные (обязательно, если используется base64Image)
},
"buttonText": "Buy", // Текст кнопки, до 30 символов (необязательно)
"buttonUrl": "https://example.com" // Ссылка, которая откроется при нажатии на кнопку (обязательно, если используется buttonText)
},
"viberTTL": 3600, // "Time to Live" Viber сообщения - сколько секунд сообщение может ждать доставки. Указывается в секундах, может быть от 60 до 86400 (обязательно)
"startTime": "2029-07-07 12:00:00" // Дата и время отложенного запуска. Может быть null, в таком случае будет запущена сразу (необязательно)
}Пример JSON запроса для Viber Transactional рассылки:
{
"name": "ViberDistributionName", // Название рассылки (обязательно)
"messageType": "VIBER", // Тип рассылки "VIBER" (обязательно)
"viberMessageType": "TRANSACTIONAL", // Тип Viber сообщений "TRANSACTIONAL" (обязательно)
"alphaName": "YourViberAlphaName", // Альфа-имя отправителя. Релевантно только для провайдера Unitalk, если у вас подключено >1 альфа имени (необязательно)
"numbers": [ // Номера телефонов получателей в международном формате (обязательно)
"380971234567",
"380671234567",
...
],
"content": {
"text": "Your verification code is: 1234" // Текст рассылки (обязательный параметр)
},
"viberTTL": 3600, // "Time to Live" Viber сообщения - сколько секунд сообщение может ждать доставки. Указывается в секундах, может быть от 60 до 86400 (обязательно)
"startTime": "2029-07-07 12:00:00" // Дата и время отложенного запуска. Может быть null, в таком случае будет запущена сразу (необязательно)
}Пример JSON запроса для Viber Carousel рассылки:
{
"name": "ViberDistributionName", // Название рассылки (обязательно)
"messageType": "VIBER", // Тип рассылки "VIBER" (обязательно)
"viberMessageType": "CAROUSEL", // Тип Viber сообщений "CAROUSEL" (обязательно)
"alphaName": "YourViberAlphaName", // Альфа-имя отправителя. Релевантно только для провайдера Unitalk, если у вас подключено >1 альфа имени (необязательно)
"numbers": [ // Номера телефонов получателей в международном формате (обязательно)
"380971234567",
"380671234567",
...
],
"content": {
"text": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit.", // Текст рассылки (обязательно)
"carouselItems": [ // Количество элементов в карусели, от 2 до 5 (обязательно)
{
"title": "Sneakers A1", // Название первого элемента, от 2 до 38 символов (обязательно)
"image": {
"base64Image": "iVBORw0KGgoAA...", // Картинка в формате base64 (обязательно)
"mimeType": "image/png", // mimeType для вашего base64 изображения (обязательно)
"fileName": "a1_carousel" // Название файла с изображением до 20 символов, может быть использовано как метаданные (обязательно)
},
"primaryButton": { // Настройки главной кнопки
"label": "Buy", // Текст, до 10 символов (обязательно)
"actionUrl": "https://example.com/a1" // Ссылка, которая откроется при нажатии на кнопку (обязательно)
},
"secondaryButton": { // Настройки второй кнопки (необязательно)
"label": "Details", // Текст, до 12 символов (необязательно)
"actionUrl": "https://example.com/a1/info" // Ссылка, которая откроется при нажатии на кнопку (необязательно)
}
},
{
"title": "Sneakers B2",
"image": {
"base64Image": "iVBORw0KGgoAA...",
"mimeType": "image/png",
"fileName": "b2_carousel"
},
"primaryButton": {
"label": "Buy",
"actionUrl": "https://example.com/b2"
}
}
]
},
"viberTTL": 3600, // "Time to Live" Viber сообщения - сколько секунд сообщение может ждать доставки. Указывается в секундах, может быть от 60 до 86400 (обязательно)
"startTime": "2029-07-07 12:00:00" // Дата и время отложенного запуска. Может быть null, в таком случае будет запущена сразу (необязательно)
}Пример JSON запроса для Viber+SMS fallback рассылки:
{
"name": "ViberWithSmsFallback", // Название рассылки (обязательно)
"messageType": "VIBER", // Тип рассылки "VIBER" (обязательно)
"viberMessageType": "PROMO", // Тип Viber сообщений "PROMO", "TRANSACTIONAL" или "CAROUSEL" (обязательно)
"alphaName": "YourViberAlphaName", // Альфа-имя отправителя. Релевантно только для провайдера Unitalk, если у вас подключено >1 альфа имени (необязательно)
"numbers": [ // Номера телефонов получателей в международном формате (обязательно)
"380971234567",
"380671234567",
...
],
"content": {
"text": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit" // Текст Viber рассылки (обязательно)
},
"viberTTL": 3600, // "Time to Live" Viber сообщения - сколько секунд сообщение может ждать доставки. Указывается в секундах, может быть от 60 до 86400 (обязательно)
...
// Для каждого типа viberMessageType наследуются все описанные выше соответствующие параметры
"sendSmsAfterViber": true, // Параметр, который отвечает за активацию Viber+SMS fallback рассылки (обязательно)
"smsText": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit", // Текст SMS рассылки (обязательно)
"smsAlphaName": "YourSmsAlphaName", // Альфа-имя отправителя. Релевантно только для провайдера Unitalk, если у вас подключено >1 альфа имени (необязательно)
"startTime": "2029-07-07 12:00:00" // Дата и время отложенного запуска. Может быть null, в таком случае будет запущена сразу (необязательно)
}Пример ответа в случае успеха:
{
"status": "Success",
"message": null,
"rus": null,
"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 отключена в настройках сервиса отправки сообщений · Сообщение не может быть пустым · Сообщение слишком длинное · Сообщение содержит недопустимые символы |
Изменение рассылки
Сopied
Для изменения рассылки в запросе необходимо указать обязательные параметры:
· id — Идентификатор рассылки;
· name — Уникальное название рассылки. Максимальная длина — 45 символов;
· messageType — Тип сообщений. «SMS» или «VIBER«;
· text — Текст рассылки. Ограничения зависят от типа сообщений и сервиса отправки сообщений.
Опционально в параметре startTime можно указать дату и время отложенного запуска в формате “yyyy-MM-dd HH:mm:ss”.
Относительный путь: /messageDistribution/update
Режим: POST
Content-Type: application/json
Пример JSON запроса для SMS:
{
"id": 123, // Идентификатор рассылки
"name": "Sample_name", // Название SMS рассылки
"messageType": "SMS", // Тип рассылки "SMS"
"content": {
"text": "Lorem ipsum dolor sit amet, consectetuer adipiscing elit" // Текст рассылки
},
"startTime": "2029-07-07 12:00:00" // Дата и время отложенного запуска. Может быть null, в таком случае будет запущена сразу
}Пример JSON запроса для Viber:
{
"id": 123,
"name": "ViberPromoText", // Название Viber рассылки
"messageType": "VIBER", // Тип рассылки "VIBER"
"viberMessageType": "PROMO", // Тип Viber рассылки "PROMO", "TRANSACTIONAL" или "CAROUSEL" (обязательно)
"content": {
"text": "Some updated text" // Текст рассылки
},
"viberTTL": 7200, // "Time to Live" Viber сообщения - сколько секунд сообщение может ждать доставки. Указывается в секундах, может быть от 60 до 86400 (обязательно)
"startTime": "2029-07-07 12:00:00" // Дата и время отложенного запуска. Может быть null, в таком случае будет запущена сразу
}Ответ в случае успеха:
{
"status": "Success",
"message": null,
"rus": null,
"data": null
}Возможные ошибки:
| 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 отключена в настройках сервиса отправки сообщений · Сообщение не может быть пустым · Сообщение слишком длинное · Сообщение содержит недопустимые символы |
Удаление рассылки
Сopied
Для удаления рассылки необходимо указать её идентификатор в параметре id.
Относительный путь: /messageDistribution/remove
Режим: POST
Content-Type: —
Пример запроса:
/messageDistribution/remove?id=1234
Ответ в случае успеха:
{
"status": "Success",
"message": null,
"rus": null,
"data": null
}Возможные ошибки:
| id is not specified | Обязательный параметр id не указан |
Приостановка или возобновление рассылки
Сopied
Для приостановки или возобновления рассылки необходимо указать её идентификатор в параметре id и действие в параметре paused:
· true — Поставить на паузу;
· false — Снять с паузы.
Относительный путь: /messageDistribution/setPaused
Режим: POST
Content-Type: —
Пример запроса:
/messageDistribution/setPaused?id=1234&paused=true
Ответ в случае успеха:
{
"status": "Success",
"message": null,
"rus": null,
"data": null
}Возможные ошибки:
| id is not specified | Обязательный параметр id не указан |
| Message distribution not found | Рассылка не найдена по указанному id |
| Message distribution completed | Рассылка уже завершена |
Web Dialer
Сopied
Для работы с виджетом Chrome (далее Web Dialer) используются методы сгруппированные по пути /widget/
Отправка уведомлений в Web Dialer
Сopied
Для отправки уведомлений в Web Dialer необходимо указать:
· Массив ID пользователей, которым необходимо отобразить уведомление, в параметре userIds;
· Как минимум один параметр уведомления в объекте data.
Относительный путь: /widget/sendNotification
Режим: POST
Content-Type: application/json
Пример JSON запроса:
{
"userIds": [ // Массив ID пользователей
1234,
...
],
"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": 1234567890 // 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
Сopied
Для сокрытия отправленных уведомлений в Web Dialer необходимо указать:
· Массив ID пользователей, у которых необходимо скрыть уведомление, в параметре userIds;
· notificationId, полученный при отправке уведомления.
Относительный путь: /widget/hideNotification
Режим: POST
Content-Type: application/json
Пример JSON запроса:
{
"userIds": [ // Массив ID пользователей
1234,
...
],
"notificationId": 1234567890 // 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 |
Словари
Сopied
Основные сущности
Сopied
Получение id и названий сущностей проекта:
POST: /dictionary?type=…
Возможные значения параметра type:
| IVR | id и название голосовых меню |
| INNER_PHONE | номер SIP-линии и имя оператора, закреплённого за ней |
| USER | id и имя пользователей |
| SITE | id и название сайтов |
| IN_SCENARIO | id и название входящих сценариев |
| OUT_SCENARIO | id и название исходящих сценариев |
| TTS_PROFILE | id и название профилей настройки синтеза аудио |
| STT_PROFILE | id и название профилей настройки распознавания речи |
| PHONE_GROUP | id и название отделов телефонии |
| TRIGGER_ACTION | id и название обработчиков событий |
| VOICE_ROBOT | id и название голосовых роботов |
| MESSAGE_DISTRIBUTION | id и название рассылок сообщений |
| CONTACT_FORMS | id и название контактных форм |
| VOICE_ANALYTICS_PROFILE | id и название профилей речевой аналитики |
| AUDIO_ALL | id и название всех типов аудио |
| AUDIO_GENERAL | id и название аудио типа “Сценарии” |
| AUDIO_IVR | id и название аудио типа “Голосовые меню” |
| AUDIO_AUTODIAL | id и название аудио типа “Обзвоны” |
| AUDIO_MELODY | id и название аудио типа “Мелодии ожидания и очередей” |
| AUDIO_API | id и название аудио типа “API звонки” |
| AUDIO_VOICE_ROBOT | id и название аудио типа “Голосовые роботы” |
| AUDIO_VOICE_QUEUE | id и название аудио типа “Очереди звонков с голосовым сопровождением” |
| AUTODIAL_ALL | id и название всех типов обзвонов |
| AUTODIAL_AUTODIALER | id и название обзвонов типа “Автообзвон” |
| AUTODIAL_PREDICTIVE | id и название обзвонов типа “Предиктивный дозвон” |
| AUTODIAL_ROBOT | id и название обзвонов типа “Обзвон голосовым роботом” |
| SALE_SCRIPTS | id и название скриптов продаж |
Тело ответа:
{
"734": "ivr name 1",
"2135": "ivr name 2"
}