Про API
Сopied

Для работы Вам понадобится ключ (токен) доступа к API.
Ключ позволяет идентифицировать Ваш проект и получать к нему доступ с максимальными привилегиями без необходимости предварительной авторизации каждый раз.
На странице личного кабинета «API» необходимо создать ключ:

api_key_gen_ru

Этот ключ необходимо указывать при каждом запросе в header: «Authorization:*Ваш ключ*»

Любой метод из описанного API может вернуть ошибку:

{"status": "Error", "message": "Internal error"}

О таких ошибках сообщайте, пожалуйста, в техническую поддержку.
Все пути всех методов, описанных в этой документации, имеют пути относительно https://cstat.nextel.com.ua:8443/tracking/api
Все запросы к методам API выполняются в режиме POST.
Примеры результатов использования методов API в данной статье показаны с использованием Postman. В Postman режим, необходимый заголовок авторизации и адрес метода указываются следующим образом:

api_postman_sample_multilang

Также можно отправлять ключ в формате «Authorization: Bearer *Ваш ключ*»

В случае если ключ или заголовок авторизации будет отсутствовать или указан неверно, результат выполнения метода будет следующим:

{"status": "Error", "message": "Authorization invalid"}

Обзвон номеров
Сopied

Общие сведения
Сopied

Все действия с обзвонами выполняются только одним методом:
/autodial/action
В теле запроса всегда должен быть JSON с обязательным полем действия, которое Вы хотите выполнить.
Минимальный JSON выглядит так:

{
  "action": "GET_WITH_DATA"
}

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

image-1

Ниже приведены словари ключевых полей, необходимых для работы с обзвонами:
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 Обзвон завершен

Действия
Сopied

Поле 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.
Например, если в запросе не указано действие, ответ будет содержать messageAction is null.

GET_WITH_DATA
Сopied

{ 
  "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 // Свидетельствует о возможных проблемах в настройках обзвона или телефонии
        },
        ...
    ]
}

ADD и UPDATE
Сopied

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


{
  "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 Превышено максимальное количество обзвонов в проекте

REMOVE
Сopied

{
  "id": 1307,
  "action": "REMOVE"
}

В случае успеха:

{"status": "Success"}

Возможные ошибки:

Task not found Обзвон не найден по указанному id
Handler is busy, try again later Один проект одновременно может удалять или добавлять номера только в одном обзвоне. Данная ошибка говорит о том, что в этот момент в одном из обзвонов проекта происходит процесс удаления или добавления номеров. Повторите попытку позже, когда предыдущая операция завершится

REFRESH
Сopied

{
  "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 Не найдено ни одного номера с указанными статусами

CANCEL
Сopied

{
  "id": 1307,
  "action": "CANCEL"
}

В случае успеха:

{"status": "Success"}

Возможные ошибки:

Task not found Обзвон не найден по указанному id
Task is finished Невозможно отменить обзвон со статусом FINISHED
Task is canceled Невозможно отменить обзвон со статусом CANCELED

UNPAUSE
Сopied

{
  "id": 1307,
  "action": "UNPAUSE"
}

В случае успеха:

{"status": "Success"}

Возможные ошибки:

Task not found Обзвон не найден по указанному id
Task is finished Невозможно снять с паузы обзвон со статусом FINISHED
Task is canceled Невозможно снять с паузы обзвон со статусом CANCELED

PAUSE
Сopied

{
  "id": 1307,
  "action": "PAUSE"
}

В случае успеха:

{"status": "Success"}

Возможные ошибки:

Task not found Обзвон не найден по указанному id
Task is finished Невозможно поставить на паузу обзвон со статусом FINISHED
Task is canceled Невозможно поставить на паузу обзвон со статусом CANCELED

ADD_CALLS
Сopied

{
  "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 с соответствующей ошибкой аудио

data Значение
Too many audios В массиве audios слишком много элементов
Too many text to speech В массиве audios слишком много элементов с синтезом аудио (tts)
Audio is null В массиве audios присутствуют элементы со значением null
Audio not found by id В массиве audios присутствуют элементы с id по которым не найдена аудиозапись
Wrong type of audio В массиве audios присутствуют элементы с id который указывает аудиозапись недопустимого раздела
Text to speech ‘text’ and ‘ssml’ is null В массиве audios присутствуют элементы с tts в котором оба text и ssml пустые
Text to speech ‘text’ not valid В массиве audios присутствуют элементы с tts в котором text превышает 4960 символов
Text to speech ‘ssml’ not valid В массиве audios присутствуют элементы с tts в котором ssml превышает 5000 символов или не начинается и заканчивается тегом speak
Text to speech settings not found by id В массиве audios присутствуют элементы с tts в котором по указанному settingsId не найден профиль настроек синтеза аудио
Audio is empty В массиве audios присутствуют элементы в которых оба tts и id имеют значение null

GET_CALLS
Сopied

{
  "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 должно быть положительным

GET_CALL
Сopied

{ 
  "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 Номер не найден в обзвоне

REMOVE_ALL_CALLS
Сopied

{
  "id": 1307, 
  "action": "REMOVE_ALL_CALLS"
}

В случае успеха:

{"status": "Success"}

Возможные ошибки:

Task not found Обзвон не найден по указанному id
Numbers not found В указанном обзвоне отсутствуют номера
Handler is busy, try again later Один проект одновременно может удалять или добавлять номера только в одном обзвоне. Данная ошибка говорит о том, что в этот момент в одном из обзвонов проекта происходит процесс удаления или добавления номеров. Повторите попытку позже, когда предыдущая операция завершится

REMOVE_CALLS
Сopied

{
   "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 Один проект одновременно может удалять или добавлять номера только в одном обзвоне. Данная ошибка говорит о том, что в этот момент в одном из обзвонов проекта происходит процесс удаления или добавления номеров. Повторите попытку позже, когда предыдущая операция завершится

Управление звонками
Сopied

Прямой вызов SIP -> GSM
Сopied

Этот метод позволяет интегрироваться с Вашим ПО и нажатием одной кнопки сразу звонить на номер клиента без необходимости ввода номера вручную на 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 символов

image-3

Создание нового звонка
Сopied

Метод используется в случае если необходимо позвонить абоненту с целью информирования его о чём-то.
После того как абонент дослушает аудиозапись — звонок завершиться.
Аудиозапись необходимо предварительно добавить в категорию «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 не указаны параметры audiosivrId и 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 ошибка при синтезе аудио из текста

image-4

Независимый click to call звонок
Сopied

Как это работает: точно также как и обычный с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.typeGSM, SIP, GROUP
steps.to — номер оператора
steps.awaitingTime — время вызова от 5 до 300 секунд

в поле steps.to необходимо указывать:
GSM -> номер клиента в международном формате (например 380501112233)
SIP -> внутренний номер линии (например 5455)
GROUP -> id группы (отдела). Id отображается вверху справа на каждом отделе в личном кабинете

image-5

Возможные ошибки:

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 не найдена

 

 

Сброс звонка
Сopied

Этот метод позволяет сбросить активный звонок по его id, который вы получаете в вебхуках, либо по номеру внутренней/внешней линии

/calls/hangup
Режим: POST
Content-Type: application/json
Отправлять Json:

{
  "number": null,
  "id": 1474427802
}

В случае успеха пример ответа:

{"status": "Success","message": "Found: 1"}

Возможные ошибки:

Empty request Не указан ни id ни number

postman_ygvbvwlw64

Аудио
Сopied

Добавление аудио файлов в проект
Сopied

/audio/upload
Режим: POST
Content-Type: multipart/form-data
Отправлять multipart с тремя параметрами:

name (String) Не может быть null. Максимум 200 символов
type (String)
GENERAL Сценарии
IVR Голосовые меню
MELODY Мелодии ожидания на линии и очередей
AUTODIAL Автообзвоны
API API звонки
file (File)
Максимальный размер: 15мб.
Допускается аудио или видео файл любого формата.
Его аудио дорожка будет переконвертирована и нормализирована под 0дб.
В случае если длительность файла превышает эти параметры — будет автоматически обрезано:
IVR 90 секунд
AUTODIAL, MELODY, API 300 секунд
GENERAL 30 секунд
temp (Boolean) Опциональный параметр. Если true — файл помечается как временный и будет автоматически удалён в 04:00

В случае успеха, в message вернётся id загруженного аудиофайла:

{"status": "Success","message": "432"}

image-6

Синтез аудио из текста
Сopied

Метод синтезирует аудио из текста и добавляет аудиозаписи в проект, с указанным именем и в указанный раздел. За раз можно озвучить до 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 Тариф не активен, возможно на счету нет средств

image-7

Списки
Сopied

BLOCKED_PHONES
Сopied

POST /lists

BLOCKED_PHONES — список номеров в международном формате, входящие звонки от них блокируются, а запрос click2call отклоняется. Размер — 200 элементов. При добавлении 201го номера — первый (самый старый) удаляется.

image-8

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"}

Пользователи
Сopied

Список
Сopied

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"
    }
]

list

Данные о пользователях
Сopied

/users/getStatus
Выдаёт список всех пользователей с указанием их внутренней или мобильной линии и состоянием работы.

[
    {
        "firstName": "Василий",
        "middleName": "Александрович",
        "lastName": "Иванов",
        "phone": "4035",
        "workStatus": "WORK"
    }
]

workStatus  может быть:
WORK (работает),
PAUS (на паузе),
STOP (работа окончена/еще не начал работать)

у пользователей без расширенного функционала, workStatus всегда WORK

image-9

Изменение состояния работы
Сopied

/phones/inner/setStatus
Режим: POST
Передавать параметры
number — номер линии оператора
status — новое состояние (WORK, PAUS, STOP)
Пример: /phones/inner/setStatus?number=9999&status=WORK

В случае успеха ответ:

{"status": "Success", "message": "Success"}

image-10

Внутренние линии
Сopied

Список внутренних линий
Сopied

/phones/inner
Режим: POST
Пустой запрос.
В случае успеха ответ:

{  
  "2239": "offline",  
  "2238": "offline",  
  "2006": "offline",  
  "2237": "offline",  
  "2005": "offline",  
  "2004": "offline",  
  "2003": "online",  
  "2002": "busy", // занят. Разговор или звонок  
  "2241": "offline",  
  "2240": "offline"  
}

image-11

Отделы
Сopied

Получение групп
Сopied

POST /groups/action
Пример body JSON запроса:

{
  "action": "GET"
}

Ответ:

{ 
  "status": "Success", 
  "data": [ 
    { 
      "id": 455, // id группы 
      "name": "Отдел продаж", // имя группы 
      "phones": [ // массив номеров которые содержит группа      
        { 
          "number": "4030",  // номер   
          "firstName": "Александр", // имя пользователя, если он есть 
          "lastName": "Максимов"  // фамилия пользователя, если он есть 
        } 
      ] 
    } 
  ] 
}

image-12

Удаление номера из группы
Сopied

POST /groups/action
Пример body JSON запроса:

{ 
  "action": "REMOVE_NUMBER", 
  "groupId": 141, // id группы
  "number": "2561" // номер, который необходимо удалить
}

Успех:

{"status": "Success"}

Возможные ошибки:

Group not found указанная группа не найдена
Cant delete the last number from group нельзя удалить последний номер из группы
The group does not contain specified number группа не содержит указанный номер

image-13

История звонков
Сopied

Получение истории
Сopied

/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 
      } 
    } 
  ] 
}

image-14

Вебхуки
Сopied

Вы можете использовать систему вебхуков для получения информации о событиях телефонии. Кроме того, UniTalk поддерживает входящие вебхуки.

Движение по балансу
Сopied

Вебхук «Движение по балансу» предоставляет информацию по каждой операции изменения баланса проекта и не может быть конфигурирован, поскольку события данной категории обрабатываются системой автоматически. Для работы с этим вебхуком Ваше веб-приложение должно принимать JSON методом POST по указанному на странице личного кабинета «API» URL.
api_balance_webhook_url_ru
Есть всего 5 типов операций:

MAIN_REFILL Пополнение основного счёта
BONUS_REFILL Пополнение бонусного счёта
CALL Списание за платный звонок
SMS Списание за отправку SMS
SERVICES Списание за услуги

Пример отправляемого JSON:

{
  "date": "2022-11-12 19:12:50", // Время проведения операции
  "type": "MAIN_REFILL", // Тип операции
  "sum": 500000, // Сумма операции. 1000 соответствует единице валюты проекта
  "sumV2": 500000000, // Сумма операции. 1000,000 соответствует единице валюты проекта
  "mainBalance": 15500000, // Основной баланс по завершению операции. 1000 соответствует единице валюты проекта
  "mainBalanceV2": 15500000000, // Основной баланс по завершению операции. 1000,000 соответствует единице валюты проекта
  "bonusBalance": 350000, // Бонусный баланс по завершению операции. 1000 соответствует единице валюты проекта
  "description": "Пополнение баланса на 500.00 UAH через LiqPay" // Описание операции
}

Обработка событий
Сopied

Отправка вебхука может быть выбрана в качестве типа действия при создании или редактировании действий на странице личного кабинета «Обработка событий». При конфигурации действия данного типа можно указать:
1) URL на который будет отправлен вебхук;
2) HTTP метод, который будет использован;
3) Заголовки HTTP;
4) URL параметры;
5) Тип тела запроса (Для POST, PUT, PATCH);
6) Содержимое тела запроса (Для типов «Указанный JSON» и «Форма (urlencoded)»).
События, за которыми можно закрепить действия, существуют 4 типов:
Типы событий

События в обзвонах номеров Настраиваются для каждого отдельного обзвона номеров при создании или редактировании через API или в соответствующем разделе личного кабинета, например, “Обзвон завершен”.
События в голосовых меню Настраиваются для каждого отдельного голосового меню при создании или редактировании на странице личного кабинета «Голосовое меню», например, нажатие клиентом клавиши “1
События звонков Настраиваются на странице личного кабинета «API», например “Завершение звонка”. Обратите внимание, действие закрепляется за событием звонка вне зависимости от внешней линии, которая при этом задействована
Событие очереди с голосовым сопровождением Доступно при создании или редактировании входящего сценария на странице личного кабинета «Входящие сценарии», при выборе перенаправления на “Очередь с сопровождением” и активации опции “Специальное действие

Более подробно с процессом обработки событий можно ознакомиться в инструкции по обработке событий.
Отправка вебхука с типом тела «Стандартный JSON» подразумевает формирование тела запроса на основании типа события, по которому был отправлен вебхук:
Стандартный JSON для событий звонков:

{
  "event": "CALL_END", // Событие, по которому был отправлен вебхук
  "call": { // Массив данных о звонке
    "id": 1091944, // Случайно генерируемый id звонка для связи его с другими событиями звонков
    "dbid": 275, // id под которым этот звонок был сохранён в базу данных. Впоследствии звонок обладает именно эти id
    "from": "380505557182", // Номер с которого был совершен звонок
    "to": [ // Массив номеров, на которые был переадресован звонок
      "2000"
    ],
    "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" // !
}

Входящие вебхуки
Сopied

UniTalk может принимать вебхуки с определенной структурой и выполнять по ним действия.
Доступные на данный момент действия:
1) «AUTODIAL_ADD» — Добавление номера телефона в обзвон номеров;
2) «AUTODIAL_REMOVE» — Удаление номера телефона из обзвона номеров.
Для использования входящих вебхуков на странице личного кабинета «API« необходимо:
1) Сгенерировать токен:

api_inbound_webhook_token_ru
2) Нажать кнопку «Сгенерировать ссылку«:

api_link_gen_ru
3) Выбрать действие, обзвон к которому оно применится, указать дополнительные опции и нажать кнопку «Сгенерировать«:

api_link_gen_2_ru
4) Заполнить параметры ссылки и отправить на неё POST запрос.
Параметры, которые заполняются при генерации автоматически:

token Токен для входящих вебхуков
action Тип действия вебхука
id id обзвона номеров

AUTODIAL_ADD
Сopied

Пример сгенерированной ссылки:
https://cstat.nextel.com.ua:8443/tracking/webhook/event?token=LrqN7GRb1Y1Qx5wRoZHY&action=AUTODIAL_ADD&id=20461&name=&note=&phones=
Параметры, которые необходимо заполнить:

phones Номер телефона или список номеров телефона через запятую которые необходимо добавить в обзвон
name Имя, которое будет закреплено за добавляемыми номерами. Максимум 100 символов. Не обязательное поле
note Заметка, которая будет закреплена за добавляемыми номерами. Максимум 500 символов. Не обязательное поле

Пример заполненной ссылки:
https://cstat.nextel.com.ua:8443/tracking/webhook/event?token=LrqN7GRb1Y1Qx5wRoZHY&action=AUTODIAL_ADD&id=20461&name=vasya&note=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 Не получилось добавить номера в обзвон. Возможно номера уже были добавлены в обзвон

AUTODIAL_REMOVE
Сopied

Пример сгенерированной ссылки:
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 Не получилось удалить ни один номер. Возможно в обзвоне не было ни одного из указанных номеров

Перевод звонка на ответственного оператора
Сopied

Вебхук «Перевод звонка на ответственного оператора» позволяет получить информацию о звонке для последующего выбора ответственного оператора Вашей системой. Для работы с этим вебхуком Ваше веб-приложение должно принимать JSON методом POST по указанному при создании или редактировании входящего сценария на странице личного кабинета «Входящие сценарии», при выборе перенаправления на «На ответственного менеджера» и активации опции «Запрос в Ваш API» URL.
api_operator_webhook_url_ru
При выполнении данного перенаправления, на указанный URL будет отправлен запрос с следующим содержимым:

{  
  "event": "ROUTE",  
  "call": {  
    "from": "380505557182" // Номер звонящего абонента  
  }  
}

В ответ Ваше приложение должно отправить JSON следующей структуры:

{  
  "operatorNumber": "2048", // Номер телефона ответственного оператора. Можно указать SIP или GSM. Может быть null
  "callerName": "Александр",  // Имя абонента, которое будет отображено в SIP клиенте
  "ivrId": 487 // id голосового меню, которое необходимо воспроизвести абоненту. Может быть null
}

Предварительно проверять свободен ли в данный момент оператор не нужно: если он занят, перенаправление звонка на него будет пропущено.

Управление очередью с голосовым сопровождением
Сopied

Вебхук «Управление очередью с голосовым сопровождением» позволяет получить информацию о звонке для последующей приоритезации обработки клиентов Вашей системой. Для работы с этим вебхуком Ваше веб-приложение должно принимать JSON методом POST по указанному при создании или редактировании входящего сценария на странице личного кабинета «Входящие сценарии», при выборе перенаправления на «Очередь с сопровождением» и активации опции «Вебхук для управления» URL.

api_queue_webhook_url_ru
При выполнении данного перенаправления, на указанный URL отправлен будет запрос с следующим содержимым:

{
  "outerNumber": "380440000001", // Внешняя линия, на которую поступил звонок
  "from": "380501234567", // Номер абонента
  "utmSource": null, // Метка аналитики. Может быть null
  "utmMedium": null, // Метка аналитики. Может быть null
  "utmCampaign": null, // Метка аналитики. Может быть null
  "utmTerm": null, // Метка аналитики. Может быть null
  "utmContent": null, // Метка аналитики. Может быть null
  "googleId": null, // Метка аналитики. Может быть null
  "facebookClientId": null, // Метка аналитики. Может быть null
  "gclid": null, // Метка аналитики. Может быть null
  "cdid": null, // Метка аналитики. Может быть null
  "referer": null // Метка аналитики. Может быть null
}

Очередь с приоритетом состоит из 10 очередей, которые обрабатываются в порядке уменьшения номера. По умолчанию, UniTalk определяет все звонки в очередь с номером 5.
Ваше приложение может изменить номер очереди, отправив в ответ JSON следующей структуры:

{
  "setPriority": 7 // Номер очереди от 1 до 10
}

Уведомления
Сopied

Отправка уведомлений в Chrome виджет
Сopied

POST  /widget/sendNotification

Отправляет уведомление указанным пользователям.

Пример body JSON запроса:

Как минимум одно из полей объекта data должно быть заполнено.

{
    "userIds": [ 
        5701, 5800, 4560
    ],
    "data": {
        "contactName": "Александр",
        "contactLink": "https://example.com",
        "entityName": "Продажа автомобиля",
        "entityLink": "https://example.com",
        "responsible": "Владимир"
    }
}

sendexample

 

Ответ:

{
    "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 Указанные пользователи не подключили хром плагин

Скрытие уведомлений в Chrome виджете
Сopied

POST  /widget/hideNotification

Скрывает уведомления указанным пользователям.

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

{     
    "userIds": [
        5701, 5800, 4560
    ],
    "notificationId": 1551593033
}
hide
Ответ:
{
   "status""Success"
}
Возможные ошибки:
No users was specified for notifications hide Не было указано ни одного пользователя для скрытия уведомления
NotificationId not specified notificationId не указан
The specified users are not found or chrome extension not connected Указанные пользователи не найдены или у них не подключен хром плагин