Про API
Сopied

Для роботи Вам знадобиться ключ (токен) доступу до API.
Ключ дозволяє ідентифікувати Ваш проект та отримувати до нього доступ із максимальними привілеями без необхідності попередньої авторизації щоразу.
На сторінці особистого кабінету “API” необхідно створити ключ:

api_key_gen_uk

Цей ключ необхідно вказувати при кожному запиті в 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": [ // Масив номерів у міжнародному форматі з ім'ям, приміткою та аудіозаписами. Усі символи, окрім цифр, будуть видалені. Дублікати не зберігаються. Обов'язкове поле, якщо номери не вказані
    {
      "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": [ // Масив номерів у міжнародному форматі, які будуть видалені з обдзвону. Усі символи, окрім цифр, будуть видалені. Максимум 10000 номерів. У запиті має бути одне з полів 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. У голосовому меню дозволені лише дії: "Переклад дзвінка на внутрішню лінію", "Переклад дзвінка на групу номерів" та дозволена лише група внутрішніх ліній (SIP), "Відтворення голосового повідомлення".
  "audios": [ //масив аудіозаписів та тексту для озвучування з якого будуть синтезовані аудіо, які будуть відтворені абоненту як тільки він відповість на дзвінок. В якому порядку аудіо знаходяться в масиві, в такому відтворюватимуться. Максимум 5 елементів, з них максимум озвучень – 2. Озвучені з тексту аудіозапису у списку аудіозаписів проекту не відображаються. Можливо null.
    {
      "id": 4953, //id заздалегідь завантаженого аудіо для API дзвінків. Можливо null, у разі tts повинно бути null. Якщо id і tts не null, буде використовуватися id.
      "tts": null //дані для озвучування тексту можуть бути null, якщо вказано id
    },
    {
      "id": null,
      "tts": { //дані для озвучування тексту можуть бути null, якщо вказано id
        "text": "текст для озвучування", // текст, який буде озвучений, не може перевищувати 4960 символів. Може бути null, якщо вказано ssml. Якщо вказано обидва поля text та ssml - використовуватиметься ssml
        "ssml": "текст для озвучування" // Альтернатива полю text - текст у форматі ssml. Не може перевищувати 5000 символів. Повинний починатися та закінчуватися тегом speak. Можливо null, якщо вказано поле Text. Якщо вказано обидва поля text та ssml - використовуватиметься ssml
        "settingsId": 18 //налаштування синтезу мови, які будуть використовуватися під час озвучування. Не може бути null
      }
    }
  ]
}

У разі успіху:

{"status": "Success"}

Можливі помилки:

Call already in progress попередній дзвінок цього абонента ще не завершився
Outer line not found вказана зовнішня лінія для вихідного дзвінка не знайдена у проекті
Outer line is tracked зазначена зовнішня лінія бере участь у трекінгу. З неї не можна робити вихідні
Meta info is too big metaбільше 1000 символів
No audio та IVR не вказано аудіозаписи audiosі ivrId, має бути зазначено хоча б щось одне
IVR може бути використаний для SIPs тільки у голосовому меню присутні невирішені дії
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 для ‘text’ and ‘ssml’ is null в ttsполя text< /span>і ssmlпусті, хоча б одне має бути не null
audios: Text до тексту ‘text’ not valid в tts поле text< /span>довше 4960 символів
audios: Text для ‘ssml’ не valid в ttsполе ssml< /span> довше 5000 символів або не починається і закінчується тегом speak
audios: Text to speech ‘settingsId’ is null не вказано id налаштувань синтезу мови у tts
audios: Text для швидких налаштувань не знайдено id налаштування синтезу мови не знайдено в проекті ID, вказаному в tts.settingsId
audios: Audio is empty у масиві audiosє елемент у якому id< /strong>і ttsnull
audios: Text to speech failed помилка синтезу аудіо з тексту

image-4

Незалежний click to call дзвінок
Сopied

Як це працює: так само як і звичайний с2с, тільки незалежність полягає в тому, що Вам не потрібно попередньо створювати сайт, додавати на нього кнопку зворотного дзвінка
Метод дозволяє створити негайний с2с дзвінок.
Цей дзвінок не буде видно у заявках та CRM системах, але буде в історії дзвінків та вебхуках.
Для його роботи не потрібно попередньо створювати сайт та підключати до нього кнопку зворотного дзвінка
POST /calls/originateC2c

{
  "clientNumber": "380935553322",
  "steps": [
    {
      "type": "GSM",
      "to": "380931111111",
      "awaitingTime": 5
    }
  ]
}

clientNumber — номер клієнта, якому треба дзвонити
steps — масив кроків переадресацій. Можна вказувати декілька.
steps.typeGSM, SIP, GROUP
steps.to — номер оператора
steps.awaitingTime — час виклику від 5 до 300 секунд

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

image-5

Аудіо
С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 до звуку ‘text’ and ‘ssml’ is null в ttsполя text< /span>і ssmlпусті, хоча б одне має бути не null
Text до тексту ‘text’ not valid в tts поле text< /span> довше 4960 символів
Text для ‘ssml’ не valid в ttsполе ssml< /span> довше 5000 символів або не починається і закінчується тегом speak
Text to speech ‘settingsId’ is null не вказано id налаштувань синтезу мови у tts
Text для прослуховування не знайдено id налаштування синтезу мови не знайдено в проекті ID, вказаному в tts.settingsId
Text to speech failed помилка синтезу аудіо з тексту
Internal error невідома помилка при синтезі аудіо

Можливі помилки:

Завжди один 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",
  "операція": "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 не можна видалити останній номер із групи
Група не містить певного номера група не містить зазначеного номера

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_ua
Всього є 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_ua
2) Натиснути кнопку “Сгенерувати посилання“:

api_link_gen_ua
3) Обрати дію, обдзвон до якого вона застосовується, вказати додаткові опції та натиснути кнопку “Сгенерувати“:

api_link_gen_2_ua
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_-ua
При виконанні цього перенаправлення, на вказаний 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_ua
При виконанні цього перенаправлення, на вказаний 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 id4560 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 Зазначені користувачі не знайдені або у них не підключений хром плагін