Для работы Вам понадобится ключ (токен) доступа к API.
Ключ позволяет идентифицировать Ваш проект и получать к нему доступ с максимальными привилегиями без необходимости предварительной авторизации каждый раз.
На странице личного кабинета «API» необходимо создать ключ:
Этот ключ необходимо указывать при каждом запросе в header: «Authorization:*Ваш ключ*»
Любой метод из описанного API может вернуть ошибку:
{"status": "Error", "message": "Internal error"}
О таких ошибках сообщайте, пожалуйста, в техническую поддержку.
Все пути всех методов, описанных в этой документации, имеют пути относительно https://cstat.nextel.com.ua:8443/tracking/api
Все запросы к методам API выполняются в режиме POST.
Примеры результатов использования методов API в данной статье показаны с использованием Postman. В Postman режим, необходимый заголовок авторизации и адрес метода указываются следующим образом:
Также можно отправлять ключ в формате «Authorization: Bearer *Ваш ключ*»
В случае если ключ или заголовок авторизации будет отсутствовать или указан неверно, результат выполнения метода будет следующим:
{"status": "Error", "message": "Authorization invalid"}
Все действия с обзвонами выполняются только одним методом:
/autodial/action
В теле запроса всегда должен быть JSON с обязательным полем действия, которое Вы хотите выполнить.
Минимальный JSON выглядит так:
{
"action": "GET_WITH_DATA"
}
Поскольку данный метод имеет множество вариаций использования и разнообразных параметров, рекомендуется настроить несколько обзвонов в личном кабинете и выполнить запрос из предыдущего примера, прежде чем изучать данную инструкцию.
Ниже приведены словари ключевых полей, необходимых для работы с обзвонами:
state:
NEW | Номера не добавлены |
IN_PROGRESS | В процессе обзвона в текущий момент |
WAITING | В ожидании начала обзвона |
PAUSED | На паузе |
CANCELED | Отменен, но еще не успел завершиться (часть номеров обзвона находятся в в статусе DIALING) |
FINISHED | Завершен |
callState:
Статус | Название статуса | Доступен для автоматического повторного прозвона (поле repeatCallStates) | Доступен для метода REFRESH | Свидетельствует о возможных проблемах в настройках обзвона или телефонии |
---|---|---|---|---|
NEW | Не обработано | — | — | — |
DIALING | В процессе обзвона | — | — | — |
ANSWER | Отвечено абонентом и оператором | — | + | — |
ANSW_RJCT | Отвечено абонентом и не было звонка операторам | + | + | — |
NOANSWER | Не отвечено | + | + | — |
BUSY | Занято или сброс | + | + | — |
FAIL | Сбой соединения | + | + | — |
BLOCKED | Заблокирован | — | + | — |
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_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 | Обзвон завершен |
Поле action определяет какое действие будет выполнено с обзвоном и перечень необходимых параметров. Ниже приведен перечень возможных значений поля.
action:
GET_WITH_DATA | Получение списка всех обзвонов с полными данными (в том числе данными для создания и редактирования обзвонов) |
ADD | Добавление нового обзвона |
UPDATE | Обновление обзвона |
REMOVE | Удаление обзвона |
REFRESH | Прозвонить повторно номера с указанными статусами |
CANCEL | Отмена обзвона. Недоступен для обзвонов в состояниях FINISHED и CANCELED |
PAUSE | Пауза. В случае успеха состояние обзвона изменится на PAUSED. Недоступен для обзвонов в состояниях FINISHED и CANCELED |
UNPAUSE | Снятие с паузы. Недоступен для обзвонов в состояниях FINISHED и CANCELED |
ADD_CALLS | Добавление номеров. Успешное добавление номеров в завершенный обзвон (FINISHED) изменит состояние на WAITING или IN_PROGRESS |
GET_CALLS | Получение номеров обзвона с текущим статусом и остальными данными |
GET_CALL | Получение номера обзвона с текущим статусом и остальными данными |
REMOVE_CALLS | Удаление номеров из обзвона на основании их статуса или указанного перечня |
REMOVE_ALL_CALLS | Удаление всех номеров из обзвона |
Каждое действие может вернуть определённую ошибку. Ошибки выглядят как:
{
"status": "Error",
"message": "*Текст ошибки*",
"rus": "*Внутреннее обозначение текста ошибки*",
"data": "*Дополнительная информация*"
}
Далее в этой инструкции будет рассматриваться только поле message.
Например, если в запросе не указано действие, ответ будет содержать message — Action is null.
{
"action": "GET_WITH_DATA"
}
Ответ в случае успеха:
Да, мы знаем что в JSON не может быть комментариев, но уверены что так понять будет проще 🙂
{
"audios": { // Список аудио, доступных для использования в автообзвонах (FIXED_A)
"1234": "Sample song name", // "ID": "Название"
...
},
"moh": { // Список мелодий ожидания на линии, доступных для использования в гарантированных дозвонах (FIXED_G / FREE_G / SMART_G)
"2345": "Elevator audio", // "ID": "Название"
...
},
"groups": { // Список отделов телефонии доступных, для использования в гарантированных дозвонах (FIXED_G / FREE_G / SMART_G)
"3456": "Sales department", // "ID": "Название"
...
},
"scenarios": { // Список входящих сценариев, доступных для использования в автообзвонах (FIXED_A)
"4567": "Main with IVR", // "ID": "Название"
...
},
"outScenarios": { // Список исходящих сценариев
"5678": "From a fixed number", // "ID": "Название"
...
},
"ttsSettings": { // Список профилей настроек синтеза речи
"12": "Pretty woman voice", // "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": "В процессе обзвона",
...
},
"tasks": [ // Массив всех обзвонов
{
"id": 12345, // ID обзвона
"name": "Обзвон окна", // Название обзвона
"algorithm": "FREE_G", // Алгоритм обзвона
"type": "GUARANTEED_DIAL", // Тип обзвона. Определяется на основании используемого алгоритма - "AUTODIAL" для FIXED_A, "GUARANTEED_DIAL" для FIXED_G / FREE_G / SMART_G
"state": "FINISHED", // Текущее состояние обзвона
"statistics": { // Статистика номеров обзвона
"totalCount": 10, // Всего номеров
"doneCount": 6, // Обработано номеров
"repeatCount": 2 // Повторных звонков
"callsDoneCount": // Количество завершенных звонков
"statesCount": { // Статистика номеров по статусам
"NEW": 3, // "ID": Количество
...
}
},
"finishedDate": "2020-04-21", // Дата завершения обзвона. null если состояние обзвона не FINISHED
"threadCount": 1, // Количество параллельных звонков. Доступно для FIXED_A и FIXED_G
"delay": 2, // Пауза между концом воспроизведения аудиозаписи и запуском сценария в секундах. Доступно для FIXED_A
"smartSpeed": 0, // Регулятор скорости обзвона. Доступно для SMART_G. Допустимые значения от -10 до 10 пропорционально влияют на скорость обзвона
"coldBaseStartCallsMultiplier": null, // Если не null, изменяет количество одновременных звонков в зависимости от процента дозвона с указанным коэффициентом. Доступны значения от 0.1 до 1.5. Доступно для FREE_G и SMART_G
"callDelay": 0, // Пауза между звонками в секундах. Доступно для FIXED_A и FIXED_G и учитывается только при количестве потоков - 1
"callDelayOnlyAnswered": true, // Пауза между звонками будет срабатывать только после звонков отвеченных оператором. Доступно для FIXED_A и FIXED_G
"audioId": null, // ID аудио воспроизводимого при ответе клиентом на звонок. Может быть null. Доступно для FIXED_A
"moh": 53, // ID аудио, которое клиент будет слышать ожидая соединение с оператором. Может быть null. Доступно для FIXED_G, FREE_G и SMART_G
"startDate": "2020-03-15", // Дата начала периода проведения обзвона (включительно)
"endDate": "2020-05-15", // Дата окончания периода проведения обзвона (включительно)
"timeFrom": [ // Время начала обзвона по дням недели в формате "HH:mm". Может быть null
"09:00", // Понедельник
"11:00", // Вторник
"11:00", // Среда
"11:00", // Четверг
"11:00", // Пятница
null, // Суббота, null - обзвон в этот день не работает
"14:00" // Воскресенье
],
"timeTo": [ // Время окончания обзвона по дням недели
"19:00",
"19:00",
"19:00",
"19:00",
"19:00",
null,
"17:00"
],
"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, // Количество повторных прозвонов. Доступны значения от 0 до 10. Значения 0 и null отключают повторный прозвон
"repeatCallIntervalMinutes": 30, // Минимальный интервал повторных прозвонов в минутах. Доступны значения от 5 до 1500
"repeatCallHighPriority": false, // Значение true указывает на необходимость внесения повторных прозвонов в приоритетную очередь
"repeatCallStates": [ // Список статусов звонков, которые будут повторно прозваниваться. Может быть пустым или null, если repeatCallAttempts равно 0 или null
"NOANSWER",
...
],
"callerIdPrefix": null, // Префикс, который будет отображаться в SIP клиенте перед номером телефона. Может быть null
"crmMode": "DONT_SEND", // Определяет какие звонки будут отправлены в CRM. Доступны значения "DONT_SEND" (Никакие), "SEND_ANSWERED" (Отвеченные абонентом), "SEND_SUCCESS" (Отвеченные абонентом и оператором) и "ALL_CALLS" (Все)
"clientCalledMode": "NEVER", // Указывает на необходимость игнорировать номера абонентов, от которых поступали звонки. Доступны значения "NEVER" (Никогда), "ANSWERED_CALLS" (Только если звонок отвечен) и "ALL_CALLS" (Всегда)
"displayName": false, // Показывать имя закрепленное за номером в SIP клиенте
"displayNote": false, // Показывать примечание к номеру в SIP клиенте
"markAsBusySeconds": 60, // Количество секунд на которое SIP линия отмечается занятой после успешного звонка. Доступны значения от 0 до 3600. Доступно для FREE_G и SMART_G
"markAsBusyMinSecondsTalk": 15, // Минимальная длительность звонка для срабатывания настройки markAsBusySeconds в секундах. Доступны значения от 0 до 3600. Доступно для FREE_G и SMART_G
"reservedSipsBusyOnlyForAutodials": true, // Указывает на доступность внутренних линий для звонков, поступающих по входящим сценариям. Доступно для FREE_G и SMART_G
"triggerActions": { // Список событий и обработчиков за ними закрепленными. К одному событию можно прикрепить максимум 5 обработчиков
"AUTODIAL_NOANSWER": [ // Событие
2, // ID обработчика событий
...
],
...
},
"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 // Свидетельствует о возможных проблемах в настройках обзвона или телефонии
},
...
]
}
Данные для создания и обновления различных типов обзвонов отличаются незначительно, по этому они будут показаны на примере одного запроса:
Запрос:
{
"action": "ADD", // Или "UPDATE"
"task": {
"id": 0, // 0 для "ADD" или ID существующего обзвона для "UPDATE"
"name": "Обзвон", // Должно быть уникальным
"algorithm": "FIXED_A", // FIXED_A / FIXED_G / FREE_G / SMART_G
"numbers":[ // Массив номеров для обзвона в международном формате, все символы, кроме цифр, удаляются. Игнорируется если action - "UPDATE", для добавления номеров в существующий обзвон используйте действие "ADD_CALLS"
"+38(097)11-11 111",
...
],
"highPriority": true, // Указывает на необходимость добавления номеров с высоким приоритетом. Такие номера обзваниваются в первую очередь. Игнорируется если action - "UPDATE"
"threadCount": 1, // Доступно для FIXED_A и FIXED_G
"audioId": 2599, // Доступно для FIXED_A
"moh": 255, // Доступно для FIXED_G, FREE_G и SMART_G
"scenarioId": 70, // Доступно для FIXED_A
"groupId": 300, // Доступно для FIXED_G, FREE_G и SMART_G
"coldBaseStartCallsMultiplier": null, // Доступно для FREE_G и SMART_G
"smartSpeed": 5, // Доступно для SMART_G
"outScenarioId": 567,
"ttsSettingsId": 18,
"useTaskAudioIfAudioError": true,
"delay": 2, // Доступно для FIXED_A
"callDelay": 30, // Доступно для FIXED_A и FIXED_G
"callDelayOnlyAnswered": true, // Доступно для FIXED_A и FIXED_G
"pauseOperatorNoAnswerLimit": 5, // Доступно для FREE_G и SMART_G
"markAsBusySeconds":60, // Доступно для FREE_G и SMART_G
"markAsBusyMinSecondsTalk":15, // Доступно для FREE_G и SMART_G
"reservedSipsBusyOnlyForAutodials":true, // Доступно для FREE_G и SMART_G
"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": {
"AUTODIAL_NOANSWER": [
2,
3
],
"AUTODIAL_ANSWER": [
2
]
},
"callerIdPrefix": "pref",
"crmMode": "DONT_SEND",
"clientCalledMode": "NEVER",
"repeatCallAttempts": 3,
"repeatCallIntervalMinutes": 10,
"repeatCallHighPriority": false,
"repeatCallStates": ["NOANSWER"],
"displayName": true,
"displayNote": false
}
}
В случае успеха:
{"status": "Success", "data": 12345}
При выполнении действия ADD в поле data передается id созданного обзвона.
Возможные ошибки:
task is null | Поле task не указано в запросе |
Please confirm phone number | Неподтвержденные проекты не могут создавать обзвоны |
algorithm is null | Поле algorithm не указано в запросе |
Billing not allow | На данном тарифе обзвон недоступен, либо тариф не оплачен |
Task not found | Обзвон не найден по id при UPDATE |
Algorithm not allowed | Изменение типа обзвона доступно только между FIXED_G, FREE_G или SMART_G |
groupId is null | Тип обзвона FIXED_G, FREE_G или SMART_G, но поле groupId не указано в запросе |
Group not found | Тип обзвона FIXED_G, FREE_G или SMART_G, но группа операторов с указанным id не найдена |
Wrong group type | Тип обзвона FIXED_G, FREE_G или SMART_G, но указанная группа не является группой внутренних линий |
Moh not found | Тип обзвона FIXED_G, FREE_G или SMART_G, но аудио мелодии ожидания не найдено по указанному id |
Wrong audio type: moh | Тип обзвона FIXED_G, FREE_G или SMART_G, но по указанному id найдено аудио другой категории |
In scenario not found | Тип обзвона FIXED_A, но входящий сценарий по указанному id не найдено |
Audio not found | Тип обзвона FIXED_A, но аудио по указанному id не найдено |
Wrong audio type: audio | Тип обзвона FIXED_A, но по указанному id найдено аудио другой категории |
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 | В массиве 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 указан обработчика событий, который несовместим с этим triggerActionEvent |
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",
...
]
}
В случае успеха:
{"status": "Success"}
Возможные ошибки:
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 | Не найдено ни одного номера с указанными статусами |
{
"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, // Указывает на необходимость повторно обработать номера, которые уже присутствуют в обзвоне. Если обзвон в процессе прозвона времени, такие номера будут обработаны первыми
"highPriority": true, // Указывает на необходимость обрабатывать добавляемые номера в первую очередь
"numbers": [ // Массив номеров в международном формате. Все символы, кроме цифр, будут удалены. Дубликаты не сохраняются. Обязательное поле, если numbersWithData не указано
"380970000001",
...
],
"numbersWithData": [ // Массив номеров в международном формате c именем, примечанием и аудиозаписями. Все символы, кроме цифр, будут удалены. Дубликаты не сохраняются. Обязательное поле, если numbers не указано
{
"phone": "380670000002",
"name": "Иван", // Имя. Учитываются первые 100 символов. Может быть null
"note": "окна", // Примечание. Учитываются первые 500 символов. Может быть null
"audios": [ // Массив аудиозаписей и текста синтеза аудио, которые будут проиграны при звонке на указанный номер вместо основного аудио обзвона. Порядок расположения аудио в массиве соответствует порядку воспроизведения. Для автообзвона максимум элементов - 5 (из которых 2 синтеза аудио), для гарантированного дозвона - 1. Процесс озвучивания происходит перед стартом звонка. Синтезированные аудио хранятся до 7 дней по завершению обзвона, не более 3 месяцев с момента создания и в списке аудиозаписей проекта не отображаются. Может быть null
{
"id": 4953, // id аудиозаписи из раздела "Автообзвоны" для автообзвона или раздела "Мелодии ожидания" для гарантированного дозвона. Может быть null если указано tts. Если указаны id и tts, использоваться будет id
"tts": { // Данные для синтеза аудио. Может быть null, если указано id
"text": "текст для озвучивания", // Текст который будет озвучен. Максимум 4960 символов. Может быть null, если указано ssml
"ssml": "текст для озвучивания ", // Текст который будет озвучен в формате ssml, альтернатива text. Максимум 5000 символов. Должен начинаться и заканчиваться тегом speak. Может быть null, если указано text
"settingsId": 18 // id профиля настройки синтеза аудио, который будет использоваться при озвучивании. Может быть null, если профиль указан в настройках обзвона
}
},
...
]
},
...
]
}
В случае успеха:
{"status": "Success"}
Возможные ошибки:
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 |
В массиве numbers присутствуют номера с некорректным аудио. В поле data будет указан массив элементов numbers с соответствующей ошибкой аудио
|
{
"id": 1307,
"action": "GET_CALLS",
"limit": 100, // Максимальное количество номеров, которые будут возвращены в ответе. Максимальное значение - 5000, значение по умолчанию - 1000
"offset": 0, // Сдвиг возвращаемых записей относительно начала списка. Значение по умолчанию - 0
"callStates": [ // Фильтр по callState. Может быть null или пустой
"NOANSWER",
...
]
}
В случае успеха:
[ // Массив номеров обзвона с дополнительной информацией
{
"id": 110232, // id звонка обзвона
"taskId": 18700, // id обзвона //!
"phone": "380441234567", // Номер телефона
"state": "ANSWER", // Статус звонка
"stateDateTime": "2020-09-10 05:47:15" // Дата завершения последнего звонка обзвона по этому номеру
"calledCount": 0, // Количество звонков на этот номер с последнего запуска обзвона
"realCalledCount": 0, // Количество звонков на этот номер в обзвоне
"highPriority": false, // Указывает находиться ли номер в приоритетной очереди
"name": null, // Имя закрепленное за номером в обзвоне
"note": "9049", // Заметка закрепленная за номером в обзвоне
"audios": null // Аудио закрепленные за номером в обзвоне
},
...
]
Возможные ошибки:
Task not found | Обзвон не найден по указанному id |
Limit range is 1-5000 | Значение limit не в диапазоне от 1 до 5000 |
Offset cannot be negative | Значение offset должно быть положительным |
{
"id": 1307,
"action": "GET_CALL",
"number": "380971234567"
}
В случае успеха:
{
"id": 110232, // id звонка обзвона
"taskId": 18700, // id обзвона
"phone": "380441234567", // Номер телефона
"state": "ANSWER", // Статус звонка
"stateDateTime": "2020-09-10 05:47:15" // Дата завершения последнего звонка обзвона по этому номеру
"calledCount": 0, // Количество звонков на этот номер с последнего запуска обзвона
"realCalledCount": 0, // Количество звонков на этот номер в обзвоне
"highPriority": false, // Указывает находиться ли номер в приоритетной очереди
"name": null, // Имя закрепленное за номером в обзвоне
"note": "9049", // Заметка закрепленная за номером в обзвоне
"audios": null // Аудио закрепленные за номером в обзвоне
}
Возможные ошибки:
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": [ // Массив статусов номера в которых будут удалены. В запросе должно присутствовать одно из полей callStates и numbers
"NOANSWER",
...
],
"numbers": [ // Массив номеров в международном формате которые будут удалены из обзвона. Все символы, кроме цифр, будут удалены. Максимум 10 000 номеров. В запросе должно присутствовать одно из полей callStates и 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 | Один проект одновременно может удалять или добавлять номера только в одном обзвоне. Данная ошибка говорит о том, что в этот момент в одном из обзвонов проекта происходит процесс удаления или добавления номеров. Повторите попытку позже, когда предыдущая операция завершится |
Этот метод позволяет интегрироваться с Вашим ПО и нажатием одной кнопки сразу звонить на номер клиента без необходимости ввода номера вручную на 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 или voiceSecretaryId. В голосовом меню разрешаются только действия: "Перевод звонка на внутреннюю линию", "Перевод звонка на группу номеров" и разрешена только группа внутренних линий (SIP), "Воспроизведение голосового сообщения".
"voiceSecretaryId": 321, // id голосового секретаря, который будет вызван при ответе абонента на звонок. Если указаны audios - будет воспроизведено после них. Может быть null - если указан параметр audios иди ivrId. В голосовом секретаре не разрешаются действия "Перевод звонка на GSM номер", "Активация сценария", "Активация голосового меню" и "Перевод звонка на отдел" с операторами на GSM.
"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 и voiceSecretaryId, должно быть указано хотя бы что-то одно |
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"}
POST /users/list
Возвращает список пользователей.
[
{
"email": "example@gmail.com",
"firstName": "Александр",
"lastName": "Александрович",
"middleName": "Александров",
"phone": "380501234567",
"role": "ADMIN",
"id": 12579,
"workStatus": "WORK"
},
{
"email": "example@unitalk.cloud",
"firstName": "Владимир",
"lastName": "Владимирович",
"middleName": "null",
"phone": "380935551133",
"role": "OWNER",
"id": 5701,
"workStatus": "WORK"
}
]
/users/getStatus
Выдаёт список всех пользователей с указанием их внутренней или мобильной линии и состоянием работы.
[
{
"firstName": "Василий",
"middleName": "Александрович",
"lastName": "Иванов",
"phone": "4035",
"workStatus": "WORK"
}
]
workStatus может быть:
WORK (работает),
PAUS (на паузе),
STOP (работа окончена/еще не начал работать)
у пользователей без расширенного функционала, workStatus всегда WORK
/phones/inner/setStatus
Режим: POST
Передавать параметры
number — номер линии оператора
status — новое состояние (WORK, PAUS, STOP)
Пример: /phones/inner/setStatus?number=9999&status=WORK
В случае успеха ответ:
{"status": "Success", "message": "Success"}
/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": 246,
"offset": 0,
"filter": {
// Все параметры фильтров опциональные. То есть могут быть null, в случае если фильтрация не требуется.
// Ниже пример 2х параметров. Остальные фильтры указаны в таблице ниже, что бы не усложнять этот образец
"direction": "OUT",
"exactPhone": [
"5008"
]
}
}
limit | Максимальное количество запрашиваемых записей. От 1 до 1000 |
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
}
}
]
}
Вы можете использовать систему вебхуков для получения информации о событиях телефонии. Кроме того, UniTalk поддерживает входящие вебхуки.
Вебхук «Движение по балансу» предоставляет информацию по каждой операции изменения баланса проекта и не может быть конфигурирован, поскольку события данной категории обрабатываются системой автоматически. Для работы с этим вебхуком Ваше веб-приложение должно принимать JSON методом POST по указанному на странице личного кабинета «API» URL.
Есть всего 5 типов операций:
MAIN_REFILL | Пополнение основного счёта |
BONUS_REFILL | Пополнение бонусного счёта |
CALL | Списание за платный звонок |
SMS | Списание за отправку SMS |
SERVICES | Списание за услуги |
Пример отправляемого JSON:
{
"date": "2022-11-12 19:12:50", // Время проведения операции
"type": "MAIN_REFILL", // Тип операции
"sum": 500000, // Сумма операции. 1000 соответствует единице валюты проекта
"sumV2": 500000000, // Сумма операции. 1000,000 соответствует единице валюты проекта
"mainBalance": 15500000, // Основной баланс по завершению операции. 1000 соответствует единице валюты проекта
"mainBalanceV2": 15500000000, // Основной баланс по завершению операции. 1000,000 соответствует единице валюты проекта
"bonusBalance": 350000, // Бонусный баланс по завершению операции. 1000 соответствует единице валюты проекта
"description": "Пополнение баланса на 500.00 UAH через LiqPay" // Описание операции
}
Отправка вебхука может быть выбрана в качестве типа действия при создании или редактировании действий на странице личного кабинета «Обработка событий». При конфигурации действия данного типа можно указать:
1) URL на который будет отправлен вебхук;
2) HTTP метод, который будет использован;
3) Заголовки HTTP;
4) URL параметры;
5) Тип тела запроса (Для POST, PUT, PATCH);
6) Содержимое тела запроса (Для типов «Указанный JSON» и «Форма (urlencoded)»).
События, за которыми можно закрепить действия, существуют 4 типов:
Типы событий
События в обзвонах номеров | Настраиваются для каждого отдельного обзвона номеров при создании или редактировании через API или в соответствующем разделе личного кабинета, например, “Обзвон завершен”. |
События в голосовых меню | Настраиваются для каждого отдельного голосового меню при создании или редактировании на странице личного кабинета «Голосовое меню», например, нажатие клиентом клавиши “1” |
События звонков | Настраиваются на странице личного кабинета «API», например “Завершение звонка”. Обратите внимание, действие закрепляется за событием звонка вне зависимости от внешней линии, которая при этом задействована |
Событие очереди с голосовым сопровождением | Доступно при создании или редактировании входящего сценария на странице личного кабинета «Входящие сценарии», при выборе перенаправления на “Очередь с сопровождением” и активации опции “Специальное действие” |
Более подробно с процессом обработки событий можно ознакомиться в инструкции по обработке событий.
Отправка вебхука с типом тела «Стандартный JSON» подразумевает формирование тела запроса на основании типа события, по которому был отправлен вебхук:
Стандартный JSON для событий звонков:
{
"event": "CALL_END", // Событие, по которому был отправлен вебхук
"call": { // Массив данных о звонке
"id": 1091944, // Случайно генерируемый id звонка для связи его с другими событиями звонков
"dbid": 275, // id под которым этот звонок был сохранён в базу данных. Впоследствии звонок обладает именно эти id
"from": "380505557182", // Номер с которого был совершен звонок
"to": [ // Массив номеров, на которые был переадресован звонок
"2000"
],
"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://cstat.nextel.com.ua:8443/tracking/rec/1531144732.920/2018-07-09", // Ссылка на запись звонка. Присутствует только в случае поле state - "ANSWER"
"meta": "some info", // Дополнительная информация, которая может быть задана при инициации звонка через API
"cause": 16 // Код завершения звонка
}
}
Массив «to»
При событии CALL_NEW входящего звонка | Всегда пуст |
При событии CALL_REDIRECT | Содержит один или более номеров |
При событии CALL_ANSWER | Содержит один номер |
При событии CALL_END | Может быть пуст или содержать номера операторов, которым поступил звонок |
Для API звонков | Может отсутствовать, если звонок не был ни на кого перенаправлен |
Поле «state»
ANSWER | Звонок был принят |
BUSY | Линия была занята |
FAIL | Сбой |
NOANSWER | Звонок не был принят |
CHANUNAVAIL | Вызываемый номер был недоступен |
NOMONEY | Недостаточно средств для совершения звонка |
BUSYOUT | Во время совершения звонка все внешние линии были заняты |
WRONGDIR | Неверное направление звонка |
BLOCKED | Звонок был заблокирован согласно настройкам проекта |
DIALING | Идет вызов |
UNREACHABLE | Абонент недоступен или находится вне зоны действия сети |
NOT_EXIST | Вызываемый номер не существует |
Поле «source»
REGULAR | Обычный прямой звонок |
TRACKING | Звонок коллтрекинга |
CLICK2CALL | Обратный звонок с кнопки |
LEAD_CATCHER | Обратный звонок с попапа |
FORM | Обратный звонок с формы |
CALLBACK | Звонок по признаку callback на внешнем номере |
AUTO_CB | Автоматический обратный звонок на пропущенный вызов |
AUTODIAL | Звонок из обзвона номеров |
API_CALL | Звонок инициированный через API |
C2C_API | с2с звонок инициированный через API |
Стандартный JSON для событий голосовых меню:
{
"ivrName":"Распределение по отделам", // Название голосового меню
"from":"380971234567", // Номер телефона абонента
"outerNumber":"380441234567", // Внешняя линия, которая была использована для совершения или получения звонка. Содержит название сайта в случае обратного звонка
"pressedDigit":2, // Цифра на которую нажал абонент. Может быть null
"actionType": "MAIN", // Тип действия. "MAIN" - основное действие, "NO_CHOICE" - действие отсутствия выбора, "WRONG_DIGIT" - действие неправильного выбора
"projectName": "myproject", // Название проекта
"utmCampaign": "sale2021", // Метка аналитики. Может быть null
"utmSource": "google", // Метка аналитики. Может быть null
"utmMedium": "email", // Метка аналитики. Может быть null
"utmTerm": "term", // Метка аналитики. Может быть null
"utmContent": "content", // Метка аналитики. Может быть null
"googleId": "11111.11111", // Метка аналитики. Может быть null
"facebookClientId": "fb.1.1234567890" // Метка аналитики. Может быть null
}
Стандартный JSON для событий завершения звонков обзвонов номеров:
{
"from": "380971234567", // Номер телефона абонента
"operatorNumber": "2040", // Внутренняя линия оператора. Может быть null
"callName": "Владимир", // Имя закрепленное за номером обзвона
"callNote": "покупал окна", // Заметка к номеру обзвона
"calledCount": 1, // Количество звонков на данный номер в обзвоне
"callState": "ANSWER", // Статус завершения звонка. Детальнее в разделе "Обзвон номеров" - "Общие сведенья"
"dialName": "обзвон-окна", // Название обзвона
"totalCount": 2000, // Количество номеров в обзвоне
"doneCount": 537, // Количество обработанных номеров обзвона
"projectName": "myproject" // Название проекта
}
Стандартный JSON для событий обзвона, не связанных со звонками
{}
Стандартный JSON для события очереди с голосовым сопровождением
{
"from":"380971234567", // Номер телефона абонента
"projectName":"my-project", // Название проекта
"utmCampaign": "sale2021", // Метка аналитики. Может быть null
"utmSource": "google", // Метка аналитики. Может быть null
"utmMedium": "email", // Метка аналитики. Может быть null
"utmTerm": "term", // Метка аналитики. Может быть null
"utmContent": "content", // Метка аналитики. Может быть null
"googleId": "11111.11111", // Метка аналитики. Может быть null
"facebookClientId": "fb.1.1234567890", // Метка аналитики. Может быть null
"gclid": "gclid..." // Метка аналитики. Может быть null
"cdid": "cdid...", // Метка аналитики. Может быть null
"referer": "https://unitalk.cloud", // Метка аналитики. Может быть null
"ip": "111.111.111.111" // !
}
UniTalk может принимать вебхуки с определенной структурой и выполнять по ним действия.
Доступные на данный момент действия:
1) «AUTODIAL_ADD» — Добавление номера телефона в обзвон номеров;
2) «AUTODIAL_REMOVE» — Удаление номера телефона из обзвона номеров.
Для использования входящих вебхуков на странице личного кабинета «API« необходимо:
1) Сгенерировать токен:
2) Нажать кнопку «Сгенерировать ссылку«:
3) Выбрать действие, обзвон к которому оно применится, указать дополнительные опции и нажать кнопку «Сгенерировать«:
4) Заполнить параметры ссылки и отправить на неё POST запрос.
Параметры, которые заполняются при генерации автоматически:
token | Токен для входящих вебхуков |
action | Тип действия вебхука |
id | id обзвона номеров |
Пример сгенерированной ссылки:
https://cstat.nextel.com.ua:8443/tracking/webhook/event?token=LrqN7GRb1Y1Qx5wRoZHY&action=AUTODIAL_ADD&id=20461&name=¬e=&phones=
Параметры, которые необходимо заполнить:
phones | Номер телефона или список номеров телефона через запятую которые необходимо добавить в обзвон |
name | Имя, которое будет закреплено за добавляемыми номерами. Максимум 100 символов. Не обязательное поле |
note | Заметка, которая будет закреплена за добавляемыми номерами. Максимум 500 символов. Не обязательное поле |
Пример заполненной ссылки:
https://cstat.nextel.com.ua:8443/tracking/webhook/event?token=LrqN7GRb1Y1Qx5wRoZHY&action=AUTODIAL_ADD&id=20461&name=vasya¬e=okna&phones=380971234567
При отправке POST запроса по этой ссылке, в обзвон с id «20461» будет добавлен номер телефона «380971234567», с именем «vasya» и заметкой «okna».
В случае успеха:
{"status": "Success"}
Возможные ошибки:
Token not found | Переданный токен не найден в UniTalk |
Action not found | Отсутствует параметр action в ссылке |
Id is null | Отсутствует параметр id в ссылке |
Autodial not found | Не найден обзвон по id |
Empty phones | Параметр phones не указан или пустой |
Phones not found | Параметр phones не пустой, но в нем не найден хотя бы один корректный номер телефона |
Phones not added | Не получилось добавить номера в обзвон. Возможно номера уже были добавлены в обзвон |
Пример сгенерированной ссылки:
https://cstat.nextel.com.ua:8443/tracking/webhook/event?token=LrqN7GRb1Y1Qx5wRoZHY&action=AUTODIAL_REMOVE&id=20461&phones=
Параметры, которые необходимо заполнить:
phones | Номер телефона или список номеров телефона через запятую которые необходимо добавить в обзвон |
Пример заполненной ссылки:
https://cstat.nextel.com.ua:8443/tracking/webhook/event?token=LrqN7GRb1Y1Qx5wRoZHY&action=AUTODIAL_REMOVE&id=20461&phones=380971234567,380670001000
При отправке POST запроса по этой ссылке, из обзвона с id «20461» будут удалены номера «380971234567» и «380670001000».
В случае успеха:
{"status": "Success"}
Возможные ошибки:
Token not found | Переданный токен не найден в UniTalk |
Action not found | Отсутствует параметр action в ссылке |
Id is null | Отсутствует параметр id в ссылке |
Autodial not found | Не найден обзвон по id |
Empty phones | Параметр phones не указан или пустой |
Phones not found | Параметр phones не пустой, но в нем не найден хотя бы один корректный номер телефона |
Calls not found | Не получилось удалить ни один номер. Возможно в обзвоне не было ни одного из указанных номеров |
Вебхук «Перевод звонка на ответственного оператора» позволяет получить информацию о звонке для последующего выбора ответственного оператора Вашей системой. Для работы с этим вебхуком Ваше веб-приложение должно принимать JSON методом POST по указанному при создании или редактировании входящего сценария на странице личного кабинета «Входящие сценарии», при выборе перенаправления на «На ответственного менеджера» и активации опции «Запрос в Ваш API» URL.
При выполнении данного перенаправления, на указанный URL будет отправлен запрос с следующим содержимым:
{
"event": "ROUTE",
"call": {
"from": "380505557182" // Номер звонящего абонента
}
}
В ответ Ваше приложение должно отправить JSON следующей структуры:
{
"operatorNumber": "2048", // Номер телефона ответственного оператора. Можно указать SIP или GSM. Может быть null
"callerName": "Александр", // Имя абонента, которое будет отображено в SIP клиенте
"ivrId": 487 // id голосового меню, которое необходимо воспроизвести абоненту. Может быть null
}
Предварительно проверять свободен ли в данный момент оператор не нужно: если он занят, перенаправление звонка на него будет пропущено.
Вебхук «Управление очередью с голосовым сопровождением» позволяет получить информацию о звонке для последующей приоритезации обработки клиентов Вашей системой. Для работы с этим вебхуком Ваше веб-приложение должно принимать JSON методом POST по указанному при создании или редактировании входящего сценария на странице личного кабинета «Входящие сценарии», при выборе перенаправления на «Очередь с сопровождением» и активации опции «Вебхук для управления» URL.
При выполнении данного перенаправления, на указанный URL отправлен будет запрос с следующим содержимым:
{
"outerNumber": "380440000001", // Внешняя линия, на которую поступил звонок
"from": "380501234567", // Номер абонента
"utmSource": null, // Метка аналитики. Может быть null
"utmMedium": null, // Метка аналитики. Может быть null
"utmCampaign": null, // Метка аналитики. Может быть null
"utmTerm": null, // Метка аналитики. Может быть null
"utmContent": null, // Метка аналитики. Может быть null
"googleId": null, // Метка аналитики. Может быть null
"facebookClientId": null, // Метка аналитики. Может быть null
"gclid": null, // Метка аналитики. Может быть null
"cdid": null, // Метка аналитики. Может быть null
"referer": null // Метка аналитики. Может быть null
}
Очередь с приоритетом состоит из 10 очередей, которые обрабатываются в порядке уменьшения номера. По умолчанию, UniTalk определяет все звонки в очередь с номером 5.
Ваше приложение может изменить номер очереди, отправив в ответ JSON следующей структуры:
{
"setPriority": 7 // Номер очереди от 1 до 10
}
POST /widget/sendNotification
Отправляет уведомление указанным пользователям.
Пример body JSON запроса:
Как минимум одно из полей объекта data
должно быть заполнено.
{
"userIds": [
5701, 5800, 4560
],
"data": {
"contactName": "Александр",
"contactLink": "https://example.com",
"entityName": "Продажа автомобиля",
"entityLink": "https://example.com",
"responsible": "Владимир"
}
}
Ответ:
{
"status":"Success",
"data": {
"notificationId": 1985837794
}
}
No users was specified for notifications send | Не было указано ни одного пользователя для отправки уведомления |
Data fields is all null | Не указано значение ни одного поля объекта data |
User with id 4560 not found | Пользователь с указанным id не был найден |
No users with connected chrome extension was found | Указанные пользователи не подключили хром плагин |
POST /widget/hideNotification
Скрывает уведомления указанным пользователям.
Пример body JSON запроса
{
"userIds": [
5701, 5800, 4560
],
"notificationId": 1551593033
}
{
"status": "Success"
}
No users was specified for notifications hide | Не было указано ни одного пользователя для скрытия уведомления |
NotificationId not specified | notificationId не указан |
The specified users are not found or chrome extension not connected | Указанные пользователи не найдены или у них не подключен хром плагин |