Для работы Вам понадобится ключ (токен) для доступа к API.
Ключ позволяет идентифицировать Ваш проект и получать к нему доступ с максимальными привилегиями без предварительной авторизации каждый раз.
На странице https://my.unitalk.cloud/new/index.html#api необходимо создать ключ
Этот ключ необходимо указывать при каждом запросе в header.
То есть «Authorization»:{Ваш ключ}
Любой метод из описанного API может вернуть ошибку:
{"status":"Error","message":"Internal error"}
О таких ошибках сообщайте, пожалуйста, в техническую поддержку.
Все пути всех методов, описанных в этой документации, имеют пути относительно https://cstat.nextel.com.ua:8443/tracking/api
В Postman это указывается здесь:
Также можно отправлять хедер Authorization в формате Bearer 9F8Etrbb37Fq
Все действия с автообзвоном выполняются только одним методом:
POST /autodial/action
В теле запроса всегда должен быть JSON с обязательным полем действия, которое Вы хотите выполнить.
Минимальный JSON выглядит так:
{
"action": "GET_WITH_DATA"
}
Прежде чем продолжать изучать эту инструкцию, а она на первый взгляд может показаться сложной, мы рекомендуем Вам настроить один или более автообзвонов в личном кабинете Nextel, после чего выполнить запрос с JSON в примере выше.
Если Вы уже видите ответ который только что получили, предлагаем ознакомится с четырьмя ключевыми полями, а после этого ниже, мы пройдёмся более детально по структуре.
action:
GET_WITH_DATA | получение списка всех обзвонов с полными данными (в том числе данными для создания и редактирования обзвонов) |
ADD | добавление нового автообзвона или гарантированного дозвона |
UPDATE | обновление обзвона. |
REMOVE | удаление обзвона. |
REFRESH | прозвонить повторно номера с указанными статусами |
CANCEL | отмена обзвона. Недоступен для FINISHED и CANCELLED обзвона. |
PAUSE | пауза. В случае успеха статус обзвона изменится на PAUSED. Недоступен для FINISHED и CANCELED обзвона. |
UNPAUSE | снятие с паузы. Недоступен для FINISHED и CANCELED обзвона. |
ADD_CALLS | добавление номеров. После удачного добавления звонков в завершенный обзвон (FINISHED) изменит статус на WAITING или IN_PROGRESS. |
GET_CALLS | получение номеров обзвона с текущим статусом и остальными данными |
GET_CALL | получение номера обзвона с текущим статусом и остальными данными |
REMOVE_CALLS | удаление номеров из обзвона или по указанным статусам или по указанным номерам |
REMOVE_ALL_CALLS | удаление всех номеров из обзвона |
state:
NEW | номера не добавлены |
IN_PROGRESS | в процессе обзвона в текущий момент |
WAITING | в ожидании начала обзвона |
PAUSED | на паузе |
CANCELED | отменен, но еще не успел завершиться (в этом состоянии обзвон будет не долго — пока не завершатся все текущие звонки) |
FINISHED | завершен |
callState:
id статуса | Название статуса | Доступен в поле repeatCallStates (Настройка «Повторный обзвон») | Доступен для метода REFRESH | Наличие звонков с этим статусом говорит о возможном наличии проблем в настройках обзвона или телефонии |
---|---|---|---|---|
NEW | Не обработано | — | — | — |
DIALING | В процессе обзвона | — | — | — |
ANSWER | Отвечено абонентом и оператором | — | + | — |
ANSW_RJCT | Отвечено абонентом и не было звонка операторам | + | + | — |
NOANSWER | Не отвечено | + | + | — |
BUSY | Занято или сброс | + | + | — |
FAIL | Сбой соединения | + | + | — |
TALKING | Автоответчик: абонент разговаривает | + | + | — |
UNREACHABLE | Автоответчик: абонент недоступен | + | + | — |
NOT_EXIST | Автоответчик: номер не существует | + | + | — |
CLIENT_CALLED | Абонент позвонил сам или был исходящий | — | + | — |
CANCEL | Отменено | — | + | — |
ANSW_NF_OP | Отвечено абонентом и не было свободных операторов | + | + | + |
ANSW_OP_NA | Отвечено абонентом и операторы не приняли звонок | + | + | + |
BUSYOUT | Недостаточно линий | + | + | + |
AUDIO_ERR | Ошибка аудио | — | + | + |
WRONG_DIR | Неверное направление | — | + | + |
AUTOCANCEL | Отменено автоматически | — | + | + |
algorithm:
FIXED_A | Автообзвон: по количеству потоков |
FIXED_G | Гарантированный дозвон: по количеству потоков |
FREE_G | Гарантированный дозвон: по свободным операторам |
SMART_G | Гарантированный дозвон: умный подбор |
triggerActionEvent (События обзвона):
AUTODIAL_REPEAT_ATTEMPTS_ENDED | Звонок завершен неуспешно и закончились попытки повторного обзвона (Настройка «Повторный обзвон») |
AUTODIAL_NOANSWER | Звонок завершен — не отвечено |
AUTODIAL_USER_PAUSED | Пользователь поставлен на паузу обзвоном. Событие доступно только для гарантированного обзвона! |
AUTODIAL_ANSW_RJCT | Звонок завершен — отвечено и сброшено абонентом |
AUTODIAL_FINISH | Обзвон завершен |
AUTODIAL_CANCEL | Обзвон отменен |
AUTODIAL_BUSYOUT | Звонок завершен — недостаточно линий |
AUTODIAL_WRONG_DIR | Звонок завершен — неверное направление |
AUTODIAL_ANSWER | Звонок завершен — отвечено |
AUTODIAL_ANSW_NF_OP | Звонок завершен — не было свободных операторов |
AUTODIAL_ANSW_OP_NA | Звонок завершен — операторы не приняли звонок |
AUTODIAL_AUDIO_ERR | Звонок завершен — ошибка аудио |
AUTODIAL_AUTOCANCEL | Обзвон отменен автоматически |
AUTODIAL_CLIENT_CALLED | Абонент позвонил сам |
AUTODIAL_BUSY | Звонок завершен — занято или сброс |
AUTODIAL_TALKING | Звонок завершен — абонент разговаривает |
AUTODIAL_UNREACHABLE | Звонок завершен — вне зоны или отключён |
AUTODIAL_NOT_EXIST | Звонок завершен — номер не существует |
AUTODIAL_CALL_FAIL | Звонок завершен — сбой соединения |
Каждое действие может вернуть определённую ошибку. Ошибки выглядят как:
{"status":"Error","message":"Текст ошибки"}
Мы будем описывать только то, что может лежать в поле message.
Например если не указано действие — вы получите message Action is null
{
"action": "GET_WITH_DATA"
}
Ответ в случае успеха:
Да, мы знаем что в JSON не может быть комментариев, но уверены что так понять будет проще 🙂
{
"tasks": [ //массив всех обзвонов, со всеми настройками
{
"id": 1125, //id
"name": "Обзвон окна", //название
"type": "GUARANTEED_DIAL", //тип обзвона (гарантированный дозвон) может быть еще AUTODIAL (автообзвон)
"state": "FINISHED", //текущее состояние обзвона
"statistics": {
"totalCount": 10, //всего номеров в обзвоне
"doneCount": 6, //обработано номеров
"repeatCount": 2 //повторных звонков
"statesCount": { //количество номеров по каждому статусу
"NEW": 3, //не обработано
"DIALING": 1, //в процессе обзвона
"ANSWER": 3, //отвечено
"NOANSWER": 2, //неотвечено
"BUSY": 1 //занято
}
},
"finishedDate": "2020-04-21", //дата когда обзвон завершился (не null только если состояние обзвона FINISHED)
"threadCount": 1, // “Потоков” - количество параллельных звонков. Есть в FIXED_A и FIXED_G
"delay": 2, // “Задержка” - Пауза после воспроизведения аудиозаписи и перед запуском сценария, если он указан. Измеряется в секундах. Есть в FIXED_A
"smartSpeed": 0, //”Регулятор скорости обзвона” - Может принимать значения от -10 до 10. Позволяет ускорить или замедлить обзвон при умном алгоритме обзвона. Меньше - медленее, больше - быстрее. Есть в SMART_G
"callDelay": 0, // ”Интервал звонков” - Пауза между звонками. Работает только когда количество потоков равно 1. Измеряется в секундах. Есть в FIXED_A и FIXED_G
"callDelayOnlyAnswered": true, // если включено - “интервал звонков” будет срабатывать только после звонков отвеченных оператором. Есть в FIXED_A и FIXED_G
"audioId": null, // “Аудиофайл” - Аудио, которое будет слышать клиент, когда ответит на звонок. Может быть null. Есть в FIXED_A
"moh": 53, // “Аудио вместо гудков” - Аудио, которое клиент будет слышать во время дозвона операторам. Может быть null. Есть в FIXED_G, FREE_G, SMART_G
"startDate": "2020-03-15", //дата начала обзвона (включительно)
"endDate": "2020-05-15", //дата окончания обзвона (включительно)
"groupId": 300, // “Операторы” - id группы внутренних линий на которую будут перенаправляться звонки обзвона. Может быть null. Есть в FIXED_G, FREE_G, SMART_G
"scenarioId": null, // “Входящий сценарий” - id сценария, который будет активирован, если клиент останется на линии после завершения аудио. Может быть null. Есть в FIXED_A
"outScenarioId": null, // “Исходящий сценарий” - id сценария, по которому будут совершаться исходящие звонки этого обзвона. Может быть null.
"pauseOperatorNoAnswerLimit": 5, //"Количество звонков подряд не отвеченных оператором, после которого он будет поставлен на паузу", речь идет о звонках завершенных со статусом "Операторы не приняли звонок". Может быть null (пользователь не будет ставиться на паузу). Возможные значения от 1 до 9999. Есть в FREE_G, SMART_G
"ttsSettingsId": 18, // “Настройки синтеза речи” - id настроек синтеза речи, с помощью которых будет происходить синтез аудио из текста указанного в звонках. Может быть null.
"useTaskAudioIfAudioError": false, // настройка “При ошибке аудио”, true - “Использовать аудио обзвона”, false - “Завершить звонок с ошибкой”
"repeatCallAttempts": 3, // “Количество повторных прозвонов”. От 1 до 10. Если 0 или null - повторный обзвон не включен.
"repeatCallIntervalMinutes": 30, // “Минимальный интервал повторных прозвонов”, измеряется в минутах, от 5 до 1500.
"repeatCallHighPriority": false, // “Вносить повторные прозвоны в приоритетную очередь”. Если включено, то повторные звонки будут совершаться с высоким приоритетом.
"repeatCallStates": [“NOANSWER”, “ANSW_NF_OP”], // “Статусы звонков для повторного прозвона”, callState которые будут повторно прозваниваться. Доступные значения можно посмотреть в описании статусов обзвона или в методе GET_WITH_DATA в поле statesInfo. Не может быть пустым или null, если repeatCallAttempts > 0.
"callerIdPrefix": null, // “Префикс для SIP” - преффикс который будет отображаться в SIP клиенте перед номером телефона. Может быть null.
"crmMode": "DONT_SEND", // "Какие звонки отправлять в CRM" - может принимать значения "DONT_SEND" (Никакие), "SEND_ANSWERED" (Отвеченные абонентом), "SEND_SUCCESS" (Отвеченные абонентом и оператором). Не может быть null
"clientCalledMode": "NEVER", // "Не звонить абоненту если он позвонил сам" - может принимать значения "NEVER" (Никогда), "ANSWERED_CALLS" (Только если звонок отвечен), "ALL_CALLS" (Всегда). Не может быть null.
"scenarioWithoutOperators": false, // "Во входящем сценарии нет операторов". Есть только в FIXED_A
"displayName": false, // “Показывать имя в SIP клиенте”
"displayNote": false, // “Показывать примечание в SIP клиенте”
"algorithm": "FREE_G", // “Режим обзвона” - алгоритм обзвона, для автообзвона всегда FIXED_A, для гарантированного дозвона FIXED_G, FREE_G, SMART_G
"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"
],
"markAsBusySeconds":60, // "Помечать SIP линию занятой после успешного звонка на (сек)", от 0 до 3600. Есть в FREE_G, SMART_G
"markAsBusyMinSecondsTalk":15, // "Помечать SIP линию занятой если разговор длился минимум (сек)", от 0 до 3600. Есть в FREE_G, SMART_G
"reservedSipsBusyOnlyForAutodials":true, //"Резервировать внутренние линии только для звонков обзвонов". Есть в FREE_G, SMART_G
"triggerActions": { //список событий, к которым прикреплены обработчики события. К одному событию можно прикрепить максимум 5 обработчиков событий. К одному событию нельзя прикрепить 2 обработчика с одинаковым типом действия
"AUTODIAL_NOANSWER": [ //событие
2, //id обработчика событий
3 //id обработчика событий
],
"AUTODIAL_ANSWER": [
2,
3
]
}
}
],
"audios": { //аудио для автообзвонов
"259": "аудио для автообзвона" // id - название
},
"moh": { //аудио вместо гудков для гарантированных дозвонов
"267": "гудки для гаранитрованного дозвона" // id - название
},
"groups": { //группы операторов для гарантированных дозвонов
"300": "sipki" // id - название
},
"scenarios": { //входящие сценарии для автообзвонов
"70": "Будни" // id - название
},
"outScenarios": { //исходящие сценарии
"567": "test", // id - название
"14": "исходящий2"
},
"ttsSettings": { //настройки синтеза аудио
"17": "гугл озвучка", // id - название
"19": "яндекс премиум озвучка"
},
"statesInfo": [ //информация о статусах звонков обзвона
{
"state": "NEW", //id статуса
"order": 1, //порядковый номер
"title": "Не обработано", //название статуса
"repeatable": false, //если true - может использоваться в параметре repeatCallStates (настройка "Повторный обзвон")
"refreshable": false, //если true - может использоваться в методе REFRESH
"warning": false //если true - наличие звонков с таким статусом говорит о том, что с обзвоном может быть что либо не так. Возможно надо изменить настройки, например если есть звонки завершившиеся со статусом "Недостаточно линий" - то нужно расширить канальность номеров использующихся в этом обзвоне
},
{
"state": "DIALING",
"order": 2,
"title": "В процессе обзвона",
"repeatable": false,
"refreshable": false,
"warning": false
},
{
"state": "ANSWER",
"order": 3,
"title": "Отвечено",
"repeatable": false,
"refreshable": true,
"warning": false
},
{
"state": "ANSW_RJCT",
"order": 4,
"title": "Отвечено (сброс)",
"repeatable": true,
"refreshable": true,
"warning": false
},
{
"state": "NOANSWER",
"order": 5,
"title": "Не отвечено",
"repeatable": true,
"refreshable": true,
"warning": false
},
{
"state": "BUSY",
"order": 6,
"title": "Занято",
"repeatable": true,
"refreshable": true,
"warning": false
},
{
"state": "FAIL",
"order": 7,
"title": "Звонок неудачен",
"repeatable": true,
"refreshable": true,
"warning": false
},
{
"state": "UNREACHABLE",
"order": 8,
"title": "Абонент недоступен",
"repeatable": true,
"refreshable": true,
"warning": false
},
{
"state": "NOT_EXIST",
"order": 9,
"title": "Номер не существует",
"repeatable": true,
"refreshable": true,
"warning": false
},
{
"state": "CLIENT_CALLED",
"order": 10,
"title": "Абонент позвонил сам",
"repeatable": false,
"refreshable": true,
"warning": false
},
{
"state": "CANCEL",
"order": 11,
"title": "Отменено",
"repeatable": false,
"refreshable": true,
"warning": false
},
{
"state": "ANSW_NF_OP",
"order": 12,
"title": "Не было свободных операторов",
"repeatable": true,
"refreshable": true,
"warning": true
},
{
"state": "ANSW_OP_NA",
"order": 13,
"title": "Операторы не приняли звонок",
"repeatable": true,
"refreshable": true,
"warning": true
},
{
"state": "BUSYOUT",
"order": 14,
"title": "Недостаточно линий",
"repeatable": true,
"refreshable": true,
"warning": true
},
{
"state": "AUDIO_ERR",
"order": 17,
"title": "Ошибка аудио",
"repeatable": true,
"refreshable": true,
"warning": true
},
{
"state": "WRONG_DIR",
"order": 16,
"title": "Неверное направление",
"repeatable": false,
"refreshable": true,
"warning": true
},
{
"state": "AUTOCANCEL",
"order": 18,
"title": "Отменено (обзвон невозможен)",
"repeatable": false,
"refreshable": true,
"warning": true
}
],
"triggerActionEvents": { //все доступные события для обзвонов и названий этих событий
"AUTODIAL_AUTOCANCEL": "Обзвон отменен автоматически",
"AUTODIAL_REPEAT_ATTEMPTS_ENDED": "Звонок завершен неуспешно и закончились попытки повторного прозвона",
"AUTODIAL_ANSW_RJCT": "Звонок завершен - отвечено и сброшено абонентом",
"AUTODIAL_WRONG_DIR": "Звонок завершен - неверное направление",
"AUTODIAL_UNREACHABLE": "Звонок завершен - вне зоны или отключён",
"AUTODIAL_CANCEL": "Обзвон отменен",
"AUTODIAL_CALL_FAIL": "Звонок завершен - звонок неудачен",
"AUTODIAL_NOT_EXIST": "Звонок завершен - номер не существует",
"AUTODIAL_BUSY": "Звонок завершен - занято или сброс",
"AUTODIAL_ANSW_OP_NA": "Звонок завершен - операторы не приняли звонок",
"AUTODIAL_USER_PAUSED": "Пользователь поставлен на паузу обзвоном",
"AUTODIAL_NOANSWER": "Звонок завершен - не отвечено",
"AUTODIAL_AUDIO_ERR": "Звонок завершен - ошибка аудио",
"AUTODIAL_ANSW_NF_OP": "Звонок завершен - не было свободных операторов",
"AUTODIAL_CLIENT_CALLED": "Абонент позвонил сам",
"AUTODIAL_FINISH": "Обзвон завершен",
"AUTODIAL_ANSWER": "Звонок завершен - отвечено",
"AUTODIAL_BUSYOUT": "Звонок завершен - недостаточно линий"
},
"triggerActionEventsAndTriggerActions": { //события обзвона и список доступных обработчиков событий для этого события. Другие обработчики к событию нельзя будет прикрепить.
"AUTODIAL_REPEAT_ATTEMPTS_ENDED": { //событие
"2": "[CRM] битрикс коммент", //id обработчика события : название обработчика (в квадратных скобках автоматически добавляется тип обработчика)
"3": "[Telegram] сообщение менеджерам"
},
"AUTODIAL_NOANSWER": {
"2": "[CRM] битрикс коммент",
"3": "[Telegram] сообщение менеджерам"
},
"AUTODIAL_USER_PAUSED": {
"3": "[Telegram] сообщение менеджерам"
},
"AUTODIAL_ANSW_RJCT": {
"2": "[CRM] битрикс коммент",
"3": "[Telegram] сообщение менеджерам"
},
"AUTODIAL_FINISH": {
"3": "[Telegram] сообщение менеджерам"
},
"AUTODIAL_CANCEL": {
"3": "[Telegram] сообщение менеджерам"
},
"AUTODIAL_BUSYOUT": {
"2": "[CRM] битрикс коммент",
"3": "[Telegram] сообщение менеджерам"
},
"AUTODIAL_WRONG_DIR": {
"2": "[CRM] битрикс коммент",
"3": "[Telegram] сообщение менеджерам"
},
"AUTODIAL_ANSWER": {
"2": "[CRM] битрикс коммент",
"3": "[Telegram] сообщение менеджерам"
},
"AUTODIAL_ANSW_NF_OP": {
"2": "[CRM] битрикс коммент",
"3": "[Telegram] сообщение менеджерам"
},
"AUTODIAL_ANSW_OP_NA": {
"2": "[CRM] битрикс коммент",
"3": "[Telegram] сообщение менеджерам"
},
"AUTODIAL_AUDIO_ERR": {
"2": "[CRM] битрикс коммент",
"3": "[Telegram] сообщение менеджерам"
},
"AUTODIAL_AUTOCANCEL": {
"3": "[Telegram] сообщение менеджерам"
}
}
}
Данные для создания автообзвона и различных типов гарантированного обзвона немного отличаются.
Примеры JSON приведены для ADD. А в случае если Вы делаете UPDATE — есть 3 отличия:
action должен быть UPDATE
игнорируется массив numbers (для добавления номеров в существующий обзвон используйте ADD_CALLS) и параметр highPriority
id должно быть не 0.
Автообзвон (FIXED_A)
Запрос:
{
"action": "ADD",
"task": {
"id": 0,
"name": "Копия новый обзвон",
"algorithm": "FIXED_A",
"numbers":[ //массив номеров для обзвона в международном формате, все символы кроме цифр и пробелы удаляются
"+38(097)11-11-111",
"38 097 222 2 222"
],
"highPriority": true, //при true, номера из массива numbers будут добавлены с высоким приоритетом. Номера с высоким приоритетом обзваниваются раньше, чем номера с обычным приоритетом
"threadCount": 1,
"audioId": 2599,
"scenarioId": 70,
"outScenarioId": 567,
"ttsSettingsId": 18,
"useTaskAudioIfAudioError": true,
"delay": 2,
"callDelay": 30,
"callDelayOnlyAnswered": true,
"startDate": "2020-04-25",
"endDate": "2020-05-25",
"timeFrom": [
"09:00",
"09:00",
"09:00",
"09:00",
"09:00",
null,
null
],
"timeTo": [
"18:00",
"18:00",
"18:00",
"18:00",
"18:00",
null,
null
],
"triggerActions": { //список событий, к которым прикреплены обработчики события. К одному событию можно прикрепить максимум 5 обработчиков событий. К одному событию нельзя прикрепить 2 обработчика с одинаковым типом действия
"AUTODIAL_NOANSWER": [ //событие
2, //id обработчика событий
3 //id обработчика событий
],
"AUTODIAL_ANSWER": [
2,
3
]
},
"callerIdPrefix": "pref",
"crmMode": "DONT_SEND",
"clientCalledMode": "NEVER",
"scenarioWithoutOperators": true,
"repeatCallAttempts": 3,
"repeatCallIntervalMinutes": 10,
"repeatCallHighPriority": false,
"repeatCallStates": ["NOANSWER"],
"displayName": true,
"displayNote": false
}
}
Гарантированный дозвон по количеству потоков (FIXED_G)
Запрос:
{
"action": "ADD",
"task": {
"id": 0,
"name": "Копия новый обзвон",
"algorithm": "FIXED_G",
"numbers":[ //список номеров для обзвона в международном формате, все символы кроме цифр и пробелы удаляются
"+38(097)11-11-111",
"38 097 222 2 222"
],
"highPriority": true, //при true, номера из массива numbers будут добавлены с высоким приоритетом. Номера с высоким приоритетом обзваниваются раньше, чем номера с обычным приоритетом
"threadCount": 1,
"moh": 255,
"groupId": 300,
"outScenarioId": 567,
"ttsSettingsId": 18,
"useTaskAudioIfAudioError": true,
"callDelay": 30,
"callDelayOnlyAnswered": true,
"startDate": "2020-04-25",
"endDate": "2020-05-25",
"timeFrom": [
"09:00",
"09:00",
"09:00",
"09:00",
"09:00",
null,
null
],
"timeTo": [
"18:00",
"18:00",
"18:00",
"18:00",
"18:00",
null,
null
],
"triggerActions": { //список событий, к которым прикреплены обработчики события. К одному событию можно прикрепить максимум 5 обработчиков событий. К одному событию нельзя прикрепить 2 обработчика с одинаковым типом действия
"AUTODIAL_NOANSWER": [ //событие
2, //id обработчика событий
3 //id обработчика событий
],
"AUTODIAL_ANSWER": [
2,
3
]
},
"callerIdPrefix": "pref",
"crmMode": "DONT_SEND",
"clientCalledMode": "NEVER",
"repeatCallAttempts": 3,
"repeatCallIntervalMinutes": 10,
"repeatCallHighPriority": false,
"repeatCallStates": ["NOANSWER"],
"displayName": true,
"displayNote": false
}
}
Гарантированный дозвон по свободным операторам (FREE_G)
Запрос:
{
"action": "ADD",
"task": {
"id": 0,
"name": "Копия новый обзвон",
"algorithm": "FREE_G",
"numbers":[ //список номеров для обзвона в международном формате, все символы кроме цифр и пробелы удаляются
"+38(097)11-11-111",
"38 097 222 2 222"
],
"highPriority": true, //при true, номера из массива numbers будут добавлены с высоким приоритетом. Номера с высоким приоритетом обзваниваются раньше, чем номера с обычным приоритетом
"moh": 54,
"groupId": 300,
"outScenarioId": 567,
"pauseOperatorNoAnswerLimit": 5,
"ttsSettingsId": 18,
"useTaskAudioIfAudioError": true,
"startDate": "2020-04-25",
"endDate": "2020-05-25",
"timeFrom": [
"09:00",
"09:00",
"09:00",
"09:00",
"09:00",
null,
null
],
"timeTo": [
"18:00",
"18:00",
"18:00",
"18:00",
"18:00",
null,
null
],
"markAsBusySeconds":60,
"markAsBusyMinSecondsTalk":15,
"reservedSipsBusyOnlyForAutodials":true,
"triggerActions": { //список событий, к которым прикреплены обработчики события. К одному событию можно прикрепить максимум 5 обработчиков событий. К одному событию нельзя прикрепить 2 обработчика с одинаковым типом действия
"AUTODIAL_NOANSWER": [ //событие
2, //id обработчика событий
3 //id обработчика событий
],
"AUTODIAL_ANSWER": [
2,
3
]
},
"callerIdPrefix": "pref",
"crmMode": "DONT_SEND",
"clientCalledMode": "NEVER",
"repeatCallAttempts": 3,
"repeatCallIntervalMinutes": 10,
"repeatCallHighPriority": false,
"repeatCallStates": ["NOANSWER"],
"displayName": true,
"displayNote": false
}
}
Гарантированный дозвон — умный подбор (SMART_G)
Запрос:
{
"action": "ADD",
"task": {
"id": 0,
"name": "Копия новый обзвон",
"algorithm": "SMART_G",
"numbers":[ //список номеров для обзвона в международном формате, все символы кроме цифр и пробелы удаляются
"+38(097)11-11-111",
"38 097 222 2 222"
],
"highPriority": true, //при true, номера из массива numbers будут добавлены с высоким приоритетом. Номера с высоким приоритетом обзваниваются раньше, чем номера с обычным приоритетом
"moh": null,
"groupId": 300,
"smartSpeed": 5,
"outScenarioId": 567,
"pauseOperatorNoAnswerLimit": 5,
"ttsSettingsId": 18,
"useTaskAudioIfAudioError": true,
"startDate": "2020-04-25",
"endDate": "2020-05-25",
"timeFrom": [
"09:00",
"09:00",
"09:00",
"09:00",
"09:00",
null,
null
],
"timeTo": [
"18:00",
"18:00",
"18:00",
"18:00",
"18:00",
null,
null
],
"markAsBusySeconds":60,
"markAsBusyMinSecondsTalk":15,
"reservedSipsBusyOnlyForAutodials":true,
"triggerActions": { //список событий, к которым прикреплены обработчики события. К одному событию можно прикрепить максимум 5 обработчиков событий. К одному событию нельзя прикрепить 2 обработчика с одинаковым типом действия
"AUTODIAL_NOANSWER": [ //событие
2, //id обработчика событий
3 //id обработчика событий
],
"AUTODIAL_ANSWER": [
2,
3
]
},
"callerIdPrefix": "pref",
"crmMode": "DONT_SEND",
"clientCalledMode": "NEVER",
"repeatCallAttempts": 3,
"repeatCallIntervalMinutes": 10,
"repeatCallHighPriority": false,
"repeatCallStates": ["NOANSWER"],
"displayName": true,
"displayNote": false
}
}
В случае успеха:
{"status": "Success"}
Возможные ошибки:
task is null | отсутствует task в json |
Please confirm phone number | не подтвержденные проекты не могут создавать обзвоны |
algorithm is null | не указан алгоритм обзвона |
Billing not allow | На данном тарифе обзвон недоступен, либо тариф не оплачен |
Task not found | обзвон не найден по id при UPDATE |
Algorithm not allowed | нельзя менять тип обзвона с автообзвона на гарантированный дозвон (алгоритм c FIXED_A на FIXED_G или FREE_G или SMART_G) и наоборот |
groupId is null | не указана группа операторов. При FIXED_G, FREE_G или SMART_G |
Group not found | не найдена по id группа операторов. При FIXED_G, FREE_G или SMART_G |
Wrong group type | группа операторов не является группой внутренних линий. При FIXED_G, FREE_G или SMART_G |
Moh not found | Аудио вместо гудков не найдено по id. При FIXED_G, FREE_G или SMART_G |
Wrong audio type: moh | если передать в moh id не из moh, а из audios. При FIXED_G, FREE_G или SMART_G |
In scenario not found | не найден входящий сценарий по id. При FIXED_A |
Audio not found | Аудио не найдено по id. При FIXED_A |
Wrong audio type: audio | есть передать в audioId id не из audios, а из moh. При FIXED_A |
Not found in scenario and audio | не указано ни аудио, ни входящий сценарий при FIXED_A, должно быть указано хотя бы одно из двух. |
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, data:[123, 999999999999999999, abc]} | в массиве numbers есть неправильные номера. В массиве data будут указаны все элементы массива numbers не прошедшие валидацию. |
Repeat call states is empty | repeatCallAttempts > 0, но repeatCallStates пустые или null. |
Repeat call state is not allowed | в repeatCallStates был передан неразрешенный callState. |
Not found text to speech settings | не найдены настройки синтеза речи по id |
Wrong trigger action event | в triggerActions передан неправильный triggerActionEvent или triggerActionEvent null |
triggerActionIds is null | в triggerActions у одного из переданных эвентов значение null (вместо массива id обработчиков событий) |
Too many trigger actions | в triggerActions для одного из событий передан массив более чем из 5 id обработчиков событий |
Trigger action not found | не найден один из переданных в triggerActions обработчиков событий по id |
Few trigger actions with same type | в triggerActions у одного из переданных эвентов в списке id указано 2 обработчика событий с одинаковым типом действия (например 2 обработчика, которые отправляют сообщение в телеграм) |
Not compatible trigger action | в triggerActions у одного из эвентов в списке id указано id обработчика событий, который несовместим с этим эвентом |
crmMode is null | не указан параметр crmMode |
clientCalledMode is null | не указан параметр clientCalledMode |
Tasks limit exceeded | Превышено максимальное количество обзвонов в проекте |
{
"id": 1307,
"action": "REMOVE"
}
В случае успеха:
{"status": "Success"}
Возможные ошибки:
Task not found | обзвон не найден по id |
Handler is busy, try again later | Один проект одновременно может удалять или добавлять номера только в одном обзвоне. Данная ошибка говорит о том, что в этот момент в одном из обзвонов проекта в процессе удаление или добавление номеров. Просто повторите попытку позже, когда предыдущая операция завершится |
{
"id": 1307,
"action": "REFRESH",
"callStates": [
"NOANSWER",
"BUSY"
]
}
В случае успеха:
{"status": "Success"}
Возможные ошибки:
Task not found | обзвон не найден по id |
states is null or empty | не указаны или пустые callStates |
state is not allowed | в callStates указан статус неразрешенный для REFRESH |
Try again later | выполнять действие REFRESH можно не чаще чем раз в 1 минуту для одного и того же обзвона. Ошибка говорит о том, что с момента последнего вызова REFRESH, для обзвона с указанными id, еще не прошла минута |
Numbers not found by states | не найдено ни одного звонка с указанными статусами (не обновили ни один номер) |
{
"id": 1307,
"action": "CANCEL"
}
В случае успеха:
{"status": "Success"}
Возможные ошибки:
Task not found | обзвон не найден по id |
Task is finished | нельзя отменить обзвон со статусом FINISHED |
Task is canceled | нельзя отменить обзвон со статусом CANCELED |
{
"id": 1307,
"action": "UNPAUSE"
}
В случае успеха:
{"status": "Success"}
Возможные ошибки:
Task not found | обзвон не найден по id |
Task is finished | нельзя поставить на паузу или снять с паузы обзвон со статусом FINISHED |
Task is canceled | нельзя поставить на паузу или снять с паузы обзвон со статусом CANCELED |
{
"id": 1307,
"action": "PAUSE"
}
В случае успеха:
{"status": "Success"}
Возможные ошибки:
Task not found | обзвон не найден по id |
Task is finished | нельзя поставить на паузу или снять с паузы обзвон со статусом FINISHED |
Task is canceled | нельзя поставить на паузу или снять с паузы обзвон со статусом CANCELED |
{
"id": 1307,
"action": "ADD_CALLS",
"refreshDuplicates": true, //при true - номера, которые уже присутствуют в обзвоне и уже обработаны, будут обработаны повторно (снова будут прозваниваться), при этом если обзвон происходит в текущий момент времени - эти номера будут прозваниваться первыми. При false - номера из numbers, которые уже присутствуют в обзвоне, будут просто игнорироваться
"highPriority": true, //при true - добавляемые номера будут добавлены с высоким приоритетом. Номера с высоким приоритетом обзваниваются раньше, чем номера с обычным приоритетом
"numbers": [ //массив номеров в международном формате, которые будут добавлены в обзвон, пробелы/тире/скобки убираются автоматически. Дубликаты не сохраняются. Необязательный параметр если передается numbersWithData. Можно передавать вместе с numbersWithData, номера будут добавлены из обеих массивов
"380970000001",
"380970000002",
"380970000003"
],
"numbersWithData": [ //массив номеров в международном формате c именем и примечанием и аудиозаписями, которые будут добавлены в обзвон, пробелы/тире/скобки из номеров убираются автоматически. Дубликаты номеров не сохраняются. Необязательный параметр если передается numbers. Можно передавать вместе с numbers
{
"phone": "380670000001",
"name": "Иван", //имя, максимум 100 символов, если больше - обрезается. Может быть null
"note": "окна", //примечание, максимум 500 символов, если больше - обрезается. Может быть null
"audios": [ //массив аудиозаписей и текста для озвучивания, которые будут проиграны для этого звонка вместо основного аудио обзвона. В каком порядке аудио находятся в массиве, в таком будут воспроизводиться. Для автообзвона максимум 5 элементов, из них максимум озвучиваний 2; для гарантированного дозвона максимум 1 элемент. Процесс озвучивания происходит перед стартом звонка, эти аудиозаписи хранятся не более 7 дней после завершения обзвона и не более 3 месяцев с момента создания, в списке аудиозаписей проекта не отображаются. Может быть null.
{
"id": 4953, //id аудиозаписи, для автообзвона можно указывать только аудио из раздела “Автообзвон” (GET_WITH_DATA audios), а для гарантированного дозвона из раздела “Мелодии ожидания” (GET_WITH_DATA moh). Может быть null, в таком случае tts не должно быть null. Если и id и tts не null, использоваться будет id.
"tts": null //данные для озвучивания текста, могут быть null, если указано id
},
{
"id": null,
"tts": { //данные для озвучивания текста, могут быть null, если указано id
"text": "текст для озвучивания", //текст который будет озвучен, не может превышать 4960 символов. Можем быть null, если указано ssml
"ssml": null, //альтернатива полю text - текст в формате ssml. Не может превышать 5000 символов. Должен начинаться и заканчиваться тегом speak. Может быть null, если указано поле text.
"settingsId": 18 //настройки синтеза речи, которые будут использоваться при озвучивании. Может быть null, в таком случае в настройках обзвона должны быть выбраны “Настройки синтеза речи”, если не выбрать - звонок будет сохранен со статусом “Ошибка аудио”.
}
},
{
"id": null,
"tts": {
"text": null,
"ssml": "текст для озвучивания",
"settingsId": null
}
}
]
},
{
"phone": "380670000002",
"name": null,
"note": null,
"audios": null
}
]
}
В случае успеха:
{"status": "Success"}
Возможные ошибки:
Task not found | обзвон не найден по id |
Numbers is null or empty | не указаны или пустые numbers и numbersWithData |
Too many numbers | за раз можно добавить не больше 100 000 номеров |
Numbers limit exceeded | нельзя добавить в обзвон больше 1 000 000 номеров |
Handler is busy, try again later | Один проект одновременно может удалять или добавлять номера только в одном обзвоне. Данная ошибка говорит о том, что в этот момент в одном из обзвонов проекта в процессе удаление или добавление номеров. Просто повторите попытку позже, когда предыдущая операция завершится |
Wrong numbers, data: [688-26, notNumber] | в списке номеров были обнаружены некорректные номера, все некорректные элементы вернутся в массиве data |
Numbers not added | Не было сохранено ни одного номера (например все номера были корректны, но уже присутствовали в обзвоне) |
{"status": "Error", "message": "Wrong audios", "data": [ //массив ошибок в формате "номер телефона: текст ошибки связанной с полем audios"
"380970000001: Too many audios", //в массиве audios слишком много элементов
"380970000002: Too many text to speech", //в массиве audios слишком много элементов с озвучиванием текста (tts)
"380970000003: Audio is null", //в массиве audios есть null элемент
"380970000004: Audio not found by id", //аудиозапись не найдена в проекте по указанному id
"380970000005: Wrong type of audio", //аудиозапись найдена в проекте, но раздел аудио неправильный
"380970000006: Text to speech 'text' and 'ssml' is null", //в tts поля text и ssml пустые, хотя бы одно должно быть не null
"380970000007: Text to speech 'text' not valid", //в tts поле text длиннее 4960 символов
"380970000008: Text to speech 'ssml' not valid", //в tts поле ssml длиннее 5000 символов или не начинается и заканчивается тегом speak
"380970000010: Text to speech settings not found by id", //настройки синтеза речи не найдены в проекте по id, указанному в tts.settingsId
"380970000011: Audio is empty" //в массиве audios есть элемент в котором id и tts null
]}
{
"id": 1307,
"action": "GET_CALLS",
"limit": 100, //количество запрашиваемых номеров, до 5000. Можно не указывать - значение по умолчанию 1000.
"offset": 0, //сдвиг относительно начала. Можно не указывать - значение по умолчанию 0.
"callStates": [ //фильтр по callState. Если null или пустой - вернутся все номера обзвона
"NOANSWER",
"BUSY"
]
}
В случае успеха:
[ //массив номеров обзвона с текущим статусом и остальной информацией
{
"phone": "380441234567", //номер телефона
"state": "ANSWER", //статус звонка (callState), не может быть null
"stateDateTime": "2020-09-10 05:47:15" //дата завершения последнего звонка обзвона на этот номер в формате yyyy-MM-dd HH:mm:ss
},
{
"phone": "380931234567",
"state": NEW,
"stateDateTime": "2020-09-10 00:00:00"
}
]
Возможные ошибки:
Task not found | обзвон не найден по id |
Limit range is 1-5000 | limit может быть от 1 до 5000 |
Offset cannot be negative | offset не может быть отрицательным |
{
"id": 1307,
"action": "GET_CALL",
"number": "380971234567"
}
В случае успеха:
{
"taskId": 1307,
"phone": "380971234567",
"state": "ANSWER", //статус номера
"stateDateTime": "2021-10-07 13:18:24.0", //время когда номер попал в текущий статус
"calledCount": 2, //текущее количество дозвонов
"realCalledCount": 5, //общее количество дозвонов
"highPriority": true, //высокий приоритет
"name": "Василий", //имя прикрепленное к номеру
"note": "заказ окон" //заметка прикрепленная к номеру
}
Возможные ошибки:
Task not found | обзвон не найден по id |
Wrong phone number | номер телефона неправильный |
Call not found | номер не найден в обзвоне |
{
"id": 1307,
"action": "REMOVE_ALL_CALLS"
}
В случае успеха:
{"status": "Success"}
Возможные ошибки:
Task not found | обзвон не найден по id |
Numbers not found | в обзвоне нет звонков |
Handler is busy, try again later | Один проект одновременно может удалять или добавлять номера только в одном обзвоне. Данная ошибка говорит о том, что в этот момент в одном из обзвонов проекта в процессе удаление или добавление номеров. Просто повторите попытку позже, когда предыдущая операция завершится |
Удаление звонков по списку статусов:
{
"id": 1307,
"action": "REMOVE_CALLS",
"callStates": [ //массив статусов, номера с этими статусами будут удалены
"NOANSWER",
"ANSWER"
]
}
Удаление номеров по списку номеров:
{
"id": 1307,
"action": "REMOVE_CALLS",
"numbers": [ //массив номеров в международном формате, эти номера будут удалены из обзвона, пробелы/тире/скобки убираются автоматически. Максимум 10 000 номеров
"380970000001",
"380970000002",
"380970000003"
]
}
В случае успеха:
{"status": "Success", "data": ["389833883838383838383838","not a number"]}
Если удалять номера по списку номеров 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 | Один проект одновременно может удалять или добавлять номера только в одном обзвоне. Данная ошибка говорит о том, что в этот момент в одном из обзвонов проекта в процессе удаление или добавление номеров. Просто повторите попытку позже, когда предыдущая операция завершится |
Этот метод позволяет интегрироваться с Вашим ПО и нажатием одной кнопки сразу звонить на номер клиента без необходимости ввода номера вручную на SIP телефоне.
Это используется обычно в CRM системах.
Как это работает: вызываете этот метод — звонит сип клиент как входящий. После ответа сразу идёт звонок на указанный номер. Основная суть — не нужно вводить номер руками.
/phones/directCall
Режим: POST
Content-Type: application/x-www-form-urlencoded
Отправлять форму с двумя параметрами:
String sip — это номер внутренней линии.
String number — gsm номер, присылаемый в международном формате. Например: 380504443322.
String meta — String на 1000 символов. Это любая информация, которая должна отображаться в вэбхуках. Может быть null.
В случае успеха пример ответа:
{"status": "Success","message": "Called"}
Возможные ошибки:
Sip not found | |
Sip not ready | указанная линия оффлайн или занята |
Wrong phone | |
Meta info is too big | meta больше 1000 символов |
Метод используется в случае если необходимо позвонить абоненту с целью информирования его о чём-то.
После того как абонент дослушает аудиозапись — звонок завершиться.
Аудиозапись необходимо предварительно добавить в категорию «API звонки» здесь: https://my.unitalk.cloud/new/index.html#audio. После загрузки Вы увидите её ID
/calls/originateNew
Режим: POST
Content-Type: application/json
Пример JSON запроса:
{
"phone": "380503332211", // номер абонента на который необходимо звонить. Не null.
"outerLine": null, // внешняя линия для звонка абоненту. Если null - то линия будет выбрана автоматически, согласно правилам исходящих сценариев.
"meta": "238", // String на 1000 символов. Это любая информация, которая должна отображаться в вэбхуках. Может быть null.
"ivrId": 211, // id голосового меню, которое будет воспроизведено абоненту ответившему на звонок. Если указаны audios - будет воспроизведено после них. Может быть null - если указан параметр audios. В голосовом меню разрешаются только действия: "Перевод звонка на внутреннюю линию", "Перевод звонка на группу номеров" и разрешена только группа внутренних линий (SIP), "Воспроизведение голосового сообщения".
"audios": [ //массив аудиозаписей и текста для озвучивания из которого будут синтезированы аудио, которые будут воспроизведены абоненту как только он ответит на звонок. В каком порядке аудио находятся в массиве, в таком будут воспроизводиться. Максимум 5 элементов, из них максимум озвучиваний - 2. Озвученные из текста аудиозаписи в списке аудиозаписей проекта не отображаются. Может быть null.
{
"id": 4953, //id заранее загруженного аудио для API звонков. Может быть null, в таком случае tts не должно быть null. Если и id и tts не null, использоваться будет id.
"tts": null //данные для озвучивания текста, могут быть null, если указано id
},
{
"id": null,
"tts": { //данные для озвучивания текста, могут быть null, если указано id
"text": "текст для озвучивания", //текст который будет озвучен, не может превышать 4960 символов. Можем быть null, если указано ssml. Если указаны оба поля text и ssml - использоваться будет ssml
"ssml": "текст для озвучивания", //альтернатива полю text - текст в формате ssml. Не может превышать 5000 символов. Должен начинаться и заканчиваться тегом speak. Может быть null, если указано поле text. Если указаны оба поля text и ssml - использоваться будет ssml
"settingsId": 18 //настройки синтеза речи, которые будут использоваться при озвучивании. Не может быть null
}
}
]
}
В случае успеха:
{"status": "Success"}
Возможные ошибки:
Call already in progress | предыдущий звонок этому абоненту еще не завершился |
Outer line not found | указанная внешняя линия для исходящего звонка не найдена в проекте |
Outer line is tracked | указанная внешняя линия участвует в трекинге. С неё нельзя совершать исходящие |
Meta info is too big | meta больше 1000 символов |
No audio and IVR | не указаны аудиозаписи audios и ivrId, должно быть указано хотя бы что-то одно |
IVR can be used for SIPs only | в голосовом меню присутствуют неразрешенные действия |
Service not paid | Тариф не активен, возможно на счету нет средств, либо в тарифе нет API звонков |
Limit of Simultaneously calls has reached | достигнут предел в 20 одновременных звонков |
Wrong phone | номер телефона абонента неверный |
audios: Too many audios | в массиве audios слишком много элементов |
audios: Too many text to speech | в массиве audios слишком много элементов с озвучиванием текста tts |
audios: Audio is null | в массиве audios есть null элемент |
audios: Audio not found by id | аудиозапись не найдена в проекте по указанному id |
audios: Wrong type of audio | указанная в audios аудиозапись не находится в категории для API звонков |
audios: Text to speech ‘text’ and ‘ssml’ is null | в tts поля text и ssml пустые, хотя бы одно должно быть не null |
audios: Text to speech ‘text’ not valid | в tts поле text длинее 4960 символов |
audios: Text to speech ‘ssml’ not valid | в tts поле ssml длинее 5000 символов или не начинается и заканчивается тегом speak |
audios: Text to speech ‘settingsId’ is null | не указано id настроек синтеза речи в tts |
audios: Text to speech settings not found by id | настройки синтеза речи не найдены в проекте по id, указанному в tts.settingsId |
audios: Audio is empty | в массиве audios есть элемент в котором id и tts null |
audios: Text to speech failed | ошибка при синтезе аудио из текста |
Как это работает: точно также как и обычный с2с, только независимость заключается в том, что Вам не требуется предварительно создавать сайт, добавлять на него кнопку обратного звонка
Метод позволяет создать немедленный с2с звонок.
Этот звонок не будет виден в заявках и CRM системах, но будет в истории звонков и вэбхуках.
Для его работы не нужно предварительно создавать сайт и подключать к нему кнопку обратного звонка
POST /calls/originateC2c
{
"clientNumber": "380935553322",
"meta": "client-5472",
"steps": [
{
"type": "GSM",
"to": "380931111111",
"awaitingTime": 5
}
]
}
clientNumber — номер клиента которому надо звонить
meta— String на 1000 символов. Это любая информация, которая должна отображаться в вэбхуках. Может быть null.
steps — массив шагов переадресаций. Можно указывать несколько.
steps.type — GSM, SIP, GROUP
steps.to — номер оператора
steps.awaitingTime — время вызова от 5 до 300 секунд
в поле steps.to необходимо указывать:
GSM -> номер клиента в международном формате (например 380501112233)
SIP -> внутренний номер линии (например 5455)
GROUP -> id группы (отдела). Id отображается вверху справа на каждом отделе в личном кабинете
Возможные ошибки:
Call to 380935553322 is already in progress | Звонок клиенту уже в процессе |
Steps is empty | Не указаны шагипереадресации steps |
Wrong client number | clientNumber указан не в международном формате |
Meta info is too big | meta больше 1000 символов |
Client number blocked in project settings | clientNumber заблокирован в настройках проекта |
To number incorrect | Номер to не является внутренней линией, либо GSM |
Step type not set | Тип распределения не указан в поле step |
Group id is incorrect | Группа, указаная в to не найдена |
Этот метод позволяет сбросить активный звонок по его id, который вы получаете в вебхуках, либо по номеру внутренней/внешней линии
/calls/hangup
Режим: POST
Content-Type: application/json
Отправлять Json:
{
"number": null,
"id": 1474427802
}
В случае успеха пример ответа:
{"status": "Success","message": "Found: 1"}
Возможные ошибки:
Empty request | Не указан ни id ни number |
/audio/upload
Режим: POST
Content-Type: multipart/form-data
Отправлять multipart с тремя параметрами:
name (String) | Не может быть null. Максимум 200 символов | ||||||||||
type (String) |
|
||||||||||
file (File) |
|
||||||||||
temp (Boolean) | Опциональный параметр. Если true — файл помечается как временный и будет автоматически удалён в 04:00 |
В случае успеха, в message вернётся id загруженного аудиофайла:
{"status": "Success","message": "432"}
Метод синтезирует аудио из текста и добавляет аудиозаписи в проект, с указанным именем и в указанный раздел. За раз можно озвучить до 5 аудио.
/audio/tts
Режим: POST
Content-Type: application/json
Пример JSON запроса:
{
"data": [ //массив данных для синтеза аудио. Максимум 5 элементов
{ //первый элемент для озвучивания
"name": "аудио для обзвона", //название с которым аудио будет добавлено в проект
"type": "AUTODIAL", //раздел аудио в который будет добавлена аудиозапись. Возможные значения: GENERAL (Сценарии), IVR (Голосовые меню), MELODY (Мелодии ожидания на линии и очередей), AUTODIAL (Автообзвоны), API (API звонки)
"tts": { //данные для озвучивания текста
"text": "текст для озвучивания", //текст который будет озвучен, не может превышать 4960 символов. Можем быть null, если указано поле ssml. Если указаны оба поля text и ssml - использоваться будет ssml
"ssml": null, //альтернатива полю text - текст в формате ssml. Не может превышать 5000 символов. Должен начинаться и заканчиваться тегом speak. Может быть null, если указано поле text. Если указаны оба поля text и ssml - использоваться будет ssml
"settingsId": 18 //настройки синтеза речи, которые будут использоваться при озвучивании. Не может быть null
}
},
{ //второй элемент для озвучивания
"name": "аудио для апи звонка",
"type": "API",
"tts": {
"text": null,
"ssml": "текст для озвучивания",
"settingsId": 16
}
}
]
}
В случае успеха:
{
"status": "Success",
"message": "Success",
"data": [ //массив с результатом синтеза, по каждому аудио. Если аудио синтезировано успешно - будет указан id с которым оно сохранилось в проект. В случае ошибки - id будет null, а в поле error будет текст ошибки
{ //успешно синтезированное аудио (присутствует id)
"name": "аудио для обзвона", //название аудио
"id": 4962, //id нового аудио (в случае успеха)
"error": null //текст ошибки (в случае неудачи)
},
{ //синтез неудачен или не выполнен (id нет, есть error)
"name": "аудио для апи звонка",
"id": null,
"error": "Same name already present"
}
]
}
Возможные значения поля error для каждого из элементов озвучивания при Success:
type is null | не указан раздел аудио |
Name is empty | имя аудио не указано или пустое |
Name length more than 200 chars | имя аудио слишком длинное, допускается максимум 200 символов |
Same name already present | аудио с таким именем уже существует в проекте |
tts is null | не указаны данные для озвучивания текста |
Text to speech ‘text’ and ‘ssml’ is null | в tts поля text и ssml пустые, хотя бы одно должно быть не null |
Text to speech ‘text’ not valid | в tts поле text длиннее 4960 символов |
Text to speech ‘ssml’ not valid | в tts поле ssml длиннее 5000 символов или не начинается и заканчивается тегом speak |
Text to speech ‘settingsId’ is null | не указано id настроек синтеза речи в tts |
Text to speech settings not found by id | настройки синтеза речи не найдены в проекте по id, указанному в tts.settingsId |
Text to speech failed | ошибка при синтезе аудио из текста |
Internal error | неизвестная ошибка при синтезе аудио |
Возможные ошибки:
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 озвучиваний за 1 запрос. |
Service not paid | Тариф не активен, возможно на счету нет средств |
POST /lists
BLOCKED_PHONES — список номеров в международном формате, входящие звонки от них блокируются, а запрос click2call отклоняется. Размер — 200 элементов. При добавлении 201го номера — первый (самый старый) удаляется.
GET (получение списка)
{
"list": "BLOCKED_PHONES",
"operation": "GET",
"items": []
}
Ответ:
["380934007171"]
ADD (Добавление нескольких элементов в список)
{
"list": "BLOCKED_PHONES",
"operation": "ADD",
"items": ["380556667788", "380445556677"]
}
Ответ:
{"status": "Success"}
REMOVE (удаление нескольких элементов из списка)
{
"list": "BLOCKED_PHONES",
"operation": "REMOVE",
"items": ["380556667788", "380445556677"]
}
Ответ:
{"status": "Success"}
/users/getStatus
Выдаёт список всех пользователей с указанием их внутренней или мобильной линии и состоянием работы.
[
{
"firstName": "Василий",
"middleName": "Александрович",
"lastName": "Иванов",
"phone": "4035",
"workStatus": "WORK"
}
]
workStatus может быть:
WORK (работает),
PAUS (на паузе),
STOP (работа окончена/еще не начал работать)
у пользователей без расширенного функционала, workStatus всегда WORK
/phones/inner/setStatus
Режим: POST
Передавать параметры
number — номер линии оператора
status — новое состояние (WORK, PAUS, STOP)
Пример: /phones/inner/setStatus?number=9999&status=WORK
В случае успеха ответ:
{"status": "Success", "message": "Success"}
/phones/inner
Режим: POST
Пустой запрос.
В случае успеха ответ:
{
"2239": "offline",
"2238": "offline",
"2006": "offline",
"2237": "offline",
"2005": "offline",
"2004": "offline",
"2003": "online",
"2002": "busy", // занят. Разговор или звонок
"2241": "offline",
"2240": "offline"
}
POST /groups/action
Пример body JSON запроса:
{
"action": "GET"
}
Ответ:
{
"status": "Success",
"data": [
{
"id": 455, // id группы
"name": "Отдел продаж", // имя группы
"phones": [ // массив номеров которые содержит группа
{
"number": "4030", // номер
"firstName": "Александр", // имя пользователя, если он есть
"lastName": "Максимов" // фамилия пользователя, если он есть
}
]
}
]
}
POST /groups/action
Пример body JSON запроса:
{
"action": "REMOVE_NUMBER",
"groupId": 141, // id группы
"number": "2561" // номер, который необходимо удалить
}
Успех:
{"status": "Success"}
Возможные ошибки:
Group not found | указанная группа не найдена |
Cant delete the last number from group | нельзя удалить последний номер из группы |
The group does not contain specified number | группа не содержит указанный номер |
/history/get
Режим: POST
Content-Type: application/json
Отправлять JSON:
{
"dateFrom": "2018-06-25 00:00:00",
"dateTo": "2018-07-09 00:00:00",
"limit": 100,
"offset": 0,
"filter": {
// Все параметры фильтров опциональные. То есть могут быть null, в случае если фильтрация не требуется.
// Ниже пример 2х параметров. Остальные фильтры указаны в таблице ниже, что бы не усложнять этот образец
"direction": "OUT",
"exactPhone": [
"5008"
]
}
}
limit | Максимальное количество записей в ответе. от 1 до 300 |
offset | Сдвиг относительно начала. Пример: если записей много, Вы запрашиваете 50 записей со сдвигом 60, то в результате будут записи с 60-й позиции по 110-ю. |
filter | Набор фильтров. Если какой-то из фильтров не нужен — Вы можете указать его как null или вовсе не присылать. Объект «filter» может быть пуст или отсутствовать. |
filter.direction | Фильтр по направлению звонка. IN, OUT, INNER |
filter.exactPhone | Массив номеров с условием ИЛИ. Ищет звонки по полям «от» и «кому» с полным совпадением. Пример: если указать в нём «5555» и «380955555555», то будут найдены звонки 380444444444 -> 5555 и 5000 -> 380955555555 |
filter.calledTo | Массив номеров кому звонили |
filter.calledFrom | Массив номеров с которых звонили |
filter.lost | Потерянные звонки. true или false |
filter.newLead | Новые клиенты. true или false |
filter.answered | Отвеченные звонки. true или false |
filter.minDuration | Минимальная длительность разговора в секундах. Число. |
filter.voiceMessage | Клиент оставил голосовое сообщение. true или false |
Пример ответа:
{
"count": 8, // количество записей в базе данных по указанным критериям. Конечно же не зависит от параметра limit.
"calls": [
{
"event": "CALL_END",
"call": {
"id": 1091944,
"dbid": 275,
"from": "380505557182",
"to": [
"2000"
],
"direction": "IN",
"secondsFullTime": 19,
"secondsTalk": 9,
"utmSource": "google",
"utmMedium": "search",
"utmCampaign": "web",
"utmTerm": "ковры",
"utmContent": "content",
"outerNumber": "site.ua",
"callback": true,
"googleId": "1182768620.1530916891",
"facebookClientId": "fb.1.1234567890",
"referer": "google.com",
"comment": "комментарий к звонку",
"date": "2018-07-09 16:58:52",
"state": "ANSWER",
"source": "REGULAR",
"link": "https://cstat.nextel.com.ua:8443/tracking/rec/1531144732.920/2018-07-09",
"meta": "some info",
"cause": 16
}
}
]
}
Вы можете использовать систему вебхуков для получения информации о некоторых событиях, отправляемых на, указанный Вами, URL.
Ваше веб-приложение должно принимать JSON методом POST.
Страница настройки вебхуков: https://my.unitalk.cloud/new/index.html#api
Типы событий:
CALL_NEW | пришел звонок, но еще никому не переадресован |
CALL_REDIRECT | звонок перенаправлен на одного или нескольких операторов |
CALL_ANSWER | кто-то ответил на звонок |
CALL_END | звонок завершен. Содержит самый полный набор информации |
{
"event": "CALL_END",
"call": {
"id": 1091944,
"dbid": 275,
"from": "380505557182",
"to": [
"2000"
],
"direction": "IN",
"secondsFullTime": 19,
"secondsTalk": 9,
"utmSource": "google",
"utmMedium": "search",
"utmCampaign": "web",
"utmTerm": "ковры",
"utmContent": "content",
"outerNumber": "site.ua",
"callback": true,
"googleId": "1182768620.1530916891",
"facebookClientId": "fb.1.1234567890",
"referer": "google.com",
"comment": "комментарий к звонку",
"date": "2018-07-09 16:58:52",
"state": "ANSWER",
"source": "REGULAR",
"link": "https://cstat.nextel.com.ua:8443/tracking/rec/1531144732.920/2018-07-09",
"meta": "some info",
"cause": 16
}
}
id | Случайно генерируемый id звонка для связи его с другими событиями звонков | ||||||||||||||||||||||||
dbid | id под которым этот звонок был сохранён в БД и в будущем обладает именно этим id. | ||||||||||||||||||||||||
from | Номер звонящего | ||||||||||||||||||||||||
to | Массив номеров кому был переадресован звонок. При событии CALL_NEW — всегда пуст, если звонок входящий. При событии CALL_REDIRECT — содержит 1 или несколько номеров. При событии CALL_ANSWER — всегда содержит 1 номер. При событии CALL_END — может быть пуст, но может содержать несколько номеров операторов, которым шел звонок, но никто на него не ответил. В случае API звонков может отсутствовать вовсе, если звонок не был перенаправлен ни на кого. |
||||||||||||||||||||||||
direction | Направление звонка. Может быть: IN (входящий), OUT (исходящий) INNER (внутренний) |
||||||||||||||||||||||||
secondsFullTime | Полное время звонка. Известно только в событии CALL_END | ||||||||||||||||||||||||
secondsTalk | Время общения. Известно только в событии CALL_END | ||||||||||||||||||||||||
utmSource utmMedium utmCampaign utmTerm utmContent googleId facebookClientId |
UTM метки, клиентский google id, клиентский facebook id (берется из cookie _fbp). Могут быть null. |
||||||||||||||||||||||||
callback | Указывает является ли этот звонок обратным. Устарело. Используйте source | ||||||||||||||||||||||||
outerNumber | Внешний номер, на который изначально позвонил клиент. Если это был обратный звонок — тут будет название сайта на котором нажали кнопку. Если звонок исходящий — то это линия с которой был звонок клиенту. |
||||||||||||||||||||||||
date | Дата и время когда звонок был принят | ||||||||||||||||||||||||
state |
|
||||||||||||||||||||||||
link | Ссылка на запись звонка. Присутствует только в случае состояния ANSWER | ||||||||||||||||||||||||
source |
|
||||||||||||||||||||||||
meta | Дополнительная информация, которая задаётся при звонках через API | ||||||||||||||||||||||||
cause | Код завершения звонка |
Вы можете использовать систему вебхуков для получения информации о некоторых событиях, отправляемых на, указанный Вами, URL.
Ваше веб-приложение должно принимать JSON методом POST.
Страница настройки вебхуков: https://my.unitalk.cloud/new/index.html#api
Этот тип вебхука предоставляет информацию по каждой операции изменения баланса проекта.
Есть всего 5 типов движения:
MAIN_REFILL | пополнение основного счёта |
BONUS_REFILL | пополнение бонусного счёта |
CALL | списание за платный звонок |
SMS | списание за отправку SMS |
SERVICES | списание за услуги |
{
"date": "2020-04-20 21:45:22",
"type": "MAIN_REFILL",
"sum": 500000,
"mainBalance": 676706,
"bonusBalance": 350000,
"description": "Пополнение баланса на 500.00 UAH через LiqPay"
}
sum | сумма операции. 1 еденица валюты (гривна) = 1000. В примере указано 500 гривен |
mainBalance | основной баланс (сальдо после совершения операции списания или пополнения) |
bonusBalance | бонусный баланс (сальдо после совершения операции списания или пополнения) |
Обработка событий голосовых меню и обзвонов
На странице Обработка событий
Можно добавить обработчик событий, который будет отправлять вебхук.
Обработчик событий можно привязать к событиям:
1) IVR (нажатие любой кнопки в голосовом меню, отсутствие нажатий, неправильное нажатие)
2) К событиям завершения звонка автообзвона и гарантированного дозвона (например завершен звонок со статусом «не отвечено» или «операторы не приняли звонок»).
3) К остальным событиям автообзвона и гарантированного дозвона (например завершение обзвона или отмена обзвона)
Более подробно об обработке событий здесь: инструкция по обработке событий
В зависимости от типа события, к которому привязан вебхук, тело вебхука будет отличаться!
Пример JSON вебхука по событию голосового меню:
{
"ivrName":"голосовое меню 2",
"from":"380971234567",
"outerNumber":"380441234567",
"pressedDigit":2,
"actionType": "MAIN",
"utmCampaign": "sale2021",
"utmSource": "google",
"utmMedium": "email",
"utmTerm": "term",
"utmContent": "content",
"googleId": "11111.11111",
"facebookClientId": "fb.1.1234567890",
"projectName": "myproject"
}
ivrName | название голосового меню | ||||||||
from | номер телефона абонента | ||||||||
outerNumber | внешняя линия на которую позвонил абонент или при click2call название сайта на котором абонент нажал на кнопку обратного звонка | ||||||||
pressedDigit | цифра на которую нажал абонент, может быть null — если сработает «действие когда выбор не сделан» (абонент не нажмет никакой цифры) | ||||||||
actionType |
|
Пример JSON вебхука по событию завершения звонка обзвона:
{
"from": "380971234567",
"operatorNumber": "2040", //может быть null
"callName": "Владимир",
"callNote": "покупал окна",
"calledCount": 1,
"callState": "ANSWER",
"dialName": "обзвон-окна",
"totalCount": 2000,
"doneCount": 537,
"projectName": "myproject"
}
from | номер телефона абонента |
callName | имя из звонка (звонок с именем можно добавить из xls файла или через API) |
callNote | заметка из звонка (звонок с заметкой можно добавить из xls файла или через API) |
calledCount | количество раз сколько мы звонили текущему абоненту |
callState | статус, с которым завершился звонок обзвона. Подробнее о статусах завершения звонков обзвонов в документации по обзвонам |
dialName | название обзвона |
totalCount | количество номеров в обзвоне |
doneCount | количество обработанных номеров в обзвоне |
Для событий обзвона не связанных со звонками отправляется вебхук с пустым телом. При необходимости вы можете вставить нужные вам параметры прямо в ссылку:
{ }
UniTalk может принимать вебхуки с определенной структурой и выполнять по ним действия.
Доступные на данный момент действия:
Добавление номера телефона в обзвон
Удаление номера телефона из обзвона
Для выполнения действий вам необходимо сгенерировать url для вебхука, заполнить в url необходимые параметры и отправить на url POST запрос.
Сгенерировать url для вебхука можно на странице API, в разделе «Входящие вебхуки».
Сперва надо создать токен для входящих вебхуков. После этого появится кнопка «Сгенерировать ссылку».
В блоке для генерации ссылки можно выбрать нужное вам действие, выбрать обзвон в котором будет выполнено это действие и выбрать дополнительные опции.
Пример сгенерированной ссылки:
https://cstat.nextel.com.ua:8443/tracking/webhook/event?token=mYbYrjxqx5vMfzyzWQwa&action=AUTODIAL_ADD&id=5&name=¬e=&phones=
Параметры, которые заполняются при генерации автоматически:
token | токен для входящих вебхуков |
action | тип действия вебхука |
id | id обзвона |
Параметры, которые необходимо заполнить:
phones | номер телефона или список номеров телефона через запятую, которые будут добавлены в обзвон |
name | имя, которое будет указано в добавленном звонке обзвона. Максимум 100 символов. Если номеров несколько — у всех будет указано это имя. Заполнять не обязательно |
note | заметка, которая будет указана в добавленном звонке обзвона. Максимум 500 символов. Если номеров несколько — у всех будет указана эта заметка. Заполнять не обязательно |
Заполненная ссылка будет выглядеть примерно так:
https://cstat.nextel.com.ua:8443/tracking/webhook/event?token=mYbYrjxqx5vMfzyzWQwa&action=AUTODIAL_ADD&id=5&name=vasya¬e=okna&phones=380971234567
Если вы отправите по этой ссылке запрос — в обзвон (выбранный при генерации ссылки) будет добавлен номер телефона 380971234567, с именем vasya и заметкой okna.
В случае успеха:
{"status": "Success"}
В случае неудачи:
Internal error | ошибка сервера |
Token not found | переданный токен не найден в Nextel |
Action not found | отсутствует параметр action в ссылке |
Id is null | отсутствует параметр id в ссылке |
Autodial not found | не найден обзвон по id, возможно он был удален |
Empty phones | параметр phones не указан или пустой |
Phones not found | параметр phones не пустой, но в нем не найден хотя бы один номер телефона |
Phones not added | не получилось добавить номера в обзвон. Возможно номера уже были добавлены в обзвон |
Пример сгенерированной ссылки:
https://cstat.nextel.com.ua:8443/tracking/webhook/event?token=mYbYrjxqx5vMfzyzWQwa&action=AUTODIAL_REMOVE&id=3&phones=
Параметры, которые заполняются при генерации автоматически:
token | токен для входящих вебхуков |
action | тип действия вебхука |
id | id обзвона |
Параметры, которые необходимо заполнить:
phones | номер телефона или список номеров телефона через запятую, которые будут удалены из обзвона |
Заполненная ссылка будет выглядеть примерно так:
https://cstat.nextel.com.ua:8443/tracking/webhook/event?token=mYbYrjxqx5vMfzyzWQwa&action=AUTODIAL_REMOVE&id=3&phones=380971234567,380670001000
Если вы отправите по этой ссылке запрос — из обзвона (выбранного при генерации ссылки) будут удалены номера 380971234567 и 380670001000
В случае успеха:
{"status": "Success"}
В случае неудачи:
Internal error | ошибка сервера |
Token not found | переданный токен не найден в Nextel |
Action not found | отсутствует параметр action в ссылке |
Id is null | отсутствует параметр id в ссылке |
Autodial not found | не найден обзвон по id, возможно он был удален |
Empty phones | параметр phones не указан или пустой |
Phones not found | параметр phones не пустой, но в нем не найден хотя бы один номер телефона |
Calls not found | не получилось удалить ни один номер. Возможно в обзвоне не было ни одного из указанных номеров |
В настройках входящих сценариев можно указать тип перенаправления звонка по ответу от внешней системы «Внешняя липучка».
В перенаправлении Вы указываете URL адрес к Вашему веб-приложению.
На этот адрес, в соответствующий момент, будет отправлен POST запрос с Json:
{
"event": "ROUTE",
"call": {
"from": "380505557182" // номер звонящего абонента
}
}
from | это номер звонящего |
В ответ Ваше приложение должно ответить следующим Json:
{
"operatorNumber": "2048",
"callerName": "Александр",
"ivrId": 487
}
operatorNumber | Номер телефона ответственного оператора на кого нужно перевести звонок. Можно указать SIP или GSM. Может быть null. |
callerName | Имя клиента, которое необходимо отобразить на sip телефоне. Может быть null. |
ivrId | id голосового меню. Может быть null. |
Предварительно проверять свободен ли в данный момент оператор не нужно — если он занят — то перенаправление звонка на него будет пропущено и звонок пойдёт дальше.