API references - UniTalk

Про API
Сopied

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

Цей ключ необхідно вказувати при кожному запиті в header: “Authorization:*Ваш ключ*”

Будь-який метод описаного API може повернути помилку:

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

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

Також можна відправляти ключ у форматі “Authorization:Bearer *Ваш ключ*”

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

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

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

Загальні відомості
Сopied

Усі дії з обдзвонами виконуються лише одним методом:
/autodial/action
У тілі запиту завжди має бути JSON із обов’язковим полем дії, яке Ви хочете виконати.
Мінімальний JSON виглядає так:

{
  "action": "GET_WITH_DATA"
}

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

Нижче наведено словники ключових полів, необхідних для роботи з обдзвонами:
state:

NEW	Номери не додані
IN_PROGRESS	В процесі обдзвону на даний момент
WAITING	В очікуванні початку обдзвону
PAUSED	На паузі
CANCELED	Скасовано, але ще не встиг завершитися (частина номерів обдзвону знаходяться у статусі DIALING)
FINISHED	Завершено

callState:

Статус	Назва статусу	Доступний для автоматичного повторного продзвонювання (поле repeatCallStates)	Доступний для методу REFRESH	Свідчить про можливі проблеми в налаштуваннях обдзвону або телефонії
NEW	Не оброблено	–	–	–
DIALING	У процесі обдзвону	–	–	–
ANSWER	Була відповідь абонентом та оператором	–	+	–
ANSW_RJCT	Абонент відповів та не було дзвінка операторам	+	+	–
NOANSWER	Немає відповіді	+	+	–
BUSY	Зайнято або скинуто	+	+	–
FAIL	Збій з’єднання	+	+	–
BLOCKED	Заблокований	–	+	–
TALKING	Автовідповідач: абонент розмовляє	+	+	–
UNREACHABLE	Автовідповідач: абонент недоступний	+	+	–
NOT_EXIST	Автовідповідач: номер не існує	+	+	–
CLIENT_CALLED	Абонент зателефонував сам або був вихідний	–	+	–
CANCEL	Скасовано	–	+	–
ANSW_NF_OP	Абонент відповів але небуло вільних операторів	+	+	+
ANSW_OP_NA	Абонент відповів та оператори не прийняли дзвінок	+	+	+
BUSYOUT	Недостатньо ліній	+	+	+
AUDIO_ERR	Помилка аудіо	–	+	+
WRONG_DIR	Неправильний напрямок	–	+	+
AUTOCANCEL	Скасовано автоматично	–	+	+

algorithm:

FIXED_A	Автообдзвон: за кількістю потоків
FIXED_G	Гарантований дозвон: за кількістю потоків
FREE_G	Гарантований дозвон: за вільними операторами
SMART_G	Гарантований дозвон: розумний підбір

triggerActionEvent:

AUTODIAL_ANSWER	Дзвінок завершено – абонент та оператор відповіли
AUTODIAL_ANSW_RJCT	Дзвінок завершено – абонент відповів і не було дзвінка до операторів
AUTODIAL_ANSW_NF_OP	Дзвінок завершено – абонент відповів і не було вільних операторів
AUTODIAL_ANSW_OP_NA	Дзвінок завершено – абонент відповів та оператори не прийняли дзвінок
AUTODIAL_NOANSWER	Дзвінок завершено – немає відповіді
AUTODIAL_BUSY	Дзвінок завершено – зайнято або скинуто
AUTODIAL_CALL_FAIL	Дзвінок завершено – збій з’єднання
AUTODIAL_TALKING	Дзвінок завершено – абонент розмовляє
AUTODIAL_UNREACHABLE	Дзвінок завершено – абонент недоступний
AUTODIAL_NOT_EXIST	Дзвінок завершено – номер не існує
AUTODIAL_BUSYOUT	Дзвінок завершено – недостатньо ліній
AUTODIAL_WRONG_DIR	Дзвінок завершено – неправильний напрямок
AUTODIAL_AUDIO_ERR	Дзвінок завершено – помилка аудіо
AUTODIAL_NUMBER_BLOCKED	Номер заблокований налаштуваннями проекту
AUTODIAL_REPEAT_ATTEMPTS_ENDED	Дзвінок завершено неуспішно і закінчилися спроби повторного продзвону
AUTODIAL_CLIENT_CALLED	Абонент зателефонував сам або був вихідний
AUTODIAL_USER_PAUSED	Користувач поставлено на паузу обдзвоном. Доступно лише для гарантованого дозвону
AUTODIAL_STATUS_CHANGED	Статус обдзвону змінено
AUTODIAL_CANCEL	Обдзвон скасовано
AUTODIAL_AUTOCANCEL	Обдзвон скасовано автоматично
AUTODIAL_FINISH	Обдзвон завершено

Дії
С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.
Наприклад, якщо у запиті не вказано дію, відповідь міститиме message – Action is null.

Отримання даних
С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": "Обзвон завершен", // "Подія": "Назва"
        ...
    },

Створення та редагування
С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	Перевищено максимальну кількість обдзвонів у проекті

Видалення
Сopied

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

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

{"status": "Success"}

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

Task not found

Обдзвон не знайдено за вказаним id

Handler is busy, try again later

Один проект може одночасно видаляти або додавати номери тільки в одному обдзвоні. Ця помилка говорить про те, що в цей момент в одному з обдзвонів проекту відбувається процес видалення чи додавання номерів. Повторіть спробу пізніше, коли попередня операція завершиться

Оновлення
С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	Не знайдено жодного номера із зазначеними статусами

Відміна
Сopied

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

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

{"status": "Success"}

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

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

Зняття з паузи
Сopied

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

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

{"status": "Success"}

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

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

Пауза
Сopied

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

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

{"status": "Success"}

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

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

Додання номерів
Сopied

{
  "id": 1307,
  "action": "ADD_CALLS",
  "refreshDuplicates": true,  // Вказує на необхідність повторно опрацювати номери, які вже є в обдзвоні. Якщо обдзвон у процесі продзвону, такі номери будуть оброблені першими
  "highPriority": true,  // Вказує на необхідність обробляти номери, що додаються, в першу чергу
  "numbers": [ // Масив номерів у міжнародному форматі. Усі символи, окрім цифр, будуть видалені. Дублікати не зберігаються. Обов'язкове поле, якщо numbersWithData не вказано
    "380970000001",
    ...
  ],
  "numbersWithData": [ // Масив номерів у міжнародному форматі з ім'ям, приміткою та аудіозаписами. Усі символи, окрім цифр, будуть видалені. Дублікати не зберігаються. Обов'язкове поле, якщо номери не вказані
    {
      "phone": "380670000002",
      "name": "Иван", // Ім'я. Враховуються перші 100 символів. Може бути null
      "note": "окна", // Примітка. Враховуються перші 500 символів. Може бути null
      "link": "https://...", // Дані для Web Dialer. Враховуються перші 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 є елементи зі значенням nullAudio 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 символів або не починається та закінчується тегом speakText to speech settings not found by idУ масиві audios присутні елементи з tts у якому за вказаним settingsId не знайдено профіль налаштувань синтезу аудіоAudio is emptyУ масиві audios присутні елементи у яких обидва tts та id мають значення null

Отримання дзвінків
С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", // Нотатка закріплена за номером в обдзвоні
    "link": "https://...", // Дані для Web Dialer закріплені за номером в обдзвоні
    "audios": null // Аудіо закріплені за номером в обдзвоні
  },
  ...
]

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

Task not found	Обдзвон не знайдено за вказаним id
Limit range is 1-5000	Значення limit не в діапазоні від 1 до 5000
Offset cannot be negative	Значення offset повинно бути позитивним

Отримання дзвінка
С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", // Нотатка закріплена за номером в обдзвоні
    "link": "https://...", // Дані для Web Dialer закріплені за номером в обдзвоні
    "audios": null // Аудіо закріплені за номером в обдзвоні
}

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

Task not found	Обдзвон не знайдено за вказаним id
Wrong phone number	Номер телефону некоректний
Call not found	Номер не знайдений в обдзвоні

Видалення усіх номерів
Сopied

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

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

{"status": "Success"}

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

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

Видалення номерів
С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 символів

Створення нового дзвінка
С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 чи voiceSecretaryIds. У голосовому секретарі заборонені дії: "Перенаправлення дзвінка на номер 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 та IVR	не вказано аудіозаписи audios, ivrId і voiceSecretaryId, має бути зазначено хоча б щось одне
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 і ttsnull
audios: Text to speech failed	помилка синтезу аудіо з тексту

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

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

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

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

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

Скидання дзвінка
Сopied

Цей метод дозволяє скинути активний дзвінок за його id, який ви отримуєте у вебхуках або за номером внутрішньої/зовнішньої лінії

/calls/hangup
Режим: POST
Content-Type: application/json
Приклад JSON запиту:

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

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

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

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

Empty request

Не вказано ані id, ані number

Аудіо
Сopied

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

/audio/upload
Режим: POST
Content-Type: multipart/form-data
Надсилати multipart з трьома параметрами:

name (String)	Не може бути null. Максимум 200 символів
type (String)	GENERALСценаріїIVRГолосові менюMELODYМелодії очікування на лінії та чергиAUTODIALАвтодзвінкиAPIAPI дзвінки
file (File)	Максимальний розмір: 15мб. Дозволяється аудіо або відео файл будь-якого формату. Його аудіо доріжка буде переконвертована та нормалізована під 0дб.У разі якщо тривалість файлу перевищує ці параметри – буде автоматично обрізано:IVR90 секундAUTODIAL, MELODY, API300 секундGENERAL30 секунд
temp (Boolean)	Опціональний параметр. Якщо true — файл позначається як тимчасовий і буде автоматично вилучено о 04:00.

У разі успіху, в message повернеться id завантаженого аудіофайлу:

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

Синтез аудіо з тексту
С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	Тариф не активний, можливо, на рахунку немає коштів

Списки
Сopied

BLOCKED_PHONES
Сopied

POST /lists

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

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

Дані про користувачів
Сopied

/users/getStatus
Видає список усіх користувачів із зазначенням їхньої внутрішньої або мобільної лінії та станом роботи.

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

workStatusможе бути:
WORK(працює),
PAUS(на паузі),
STOP(робота закінчена/ще не почав працювати)

у користувачів без розширеного функціоналу, workStatus завжди WORK

Зміна стану роботи
Сopied

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

У разі успіху відповідь:

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

Внутрішні лінії
С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"
}

Відділи
Сopied

Отримання груп
Сopied

POST /groups/action
Приклад body JSON запиту:

{
   "action": "GET"
}

Відповідь:

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

Видалення номера з групи
Сopied

POST /groups/action
Приклад body JSON запиту:

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

Успіх:

{"status": "Success"}

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

Group not found	Вказана група не знайдена
Cant delete the last number from group	не можна видалити останній номер із групи
Група не містить певного номера	група не містить зазначеного номера

Історія дзвінків
С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
      }
    }
  ]
}

Вебхуки
Сopied

Ви можете використовувати систему вебхуків для отримання інформації про події телефонії. Крім того, UniTalk підтримує вхідні вебхуки.

Рух за балансом
Сopied

Вебхук “Рух за балансом” надає інформацію щодо кожної операції зміни балансу проекту і не може бути конфігурований, оскільки події даної категорії обробляються системою автоматично. Для роботи з цим вебхуком Ваш веб-додаток має приймати JSON методом POST за вказаною на сторінці особистого кабінету “API” URL.

Всього є 5 типів операцій:

MAIN_REFILL	Поповнення основного рахунку
BONUS_REFILL	Поповнення бонусного рахунку
CALL	Списання за платний дзвінок
SMS	Списання за відправку SMS
SERVICES	Списання за послуги

Приклад JSON, що відправляється:

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

Обробка подій
Сopied

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

Події в обдзвонах номерів	Налаштовуються для кожного окремого обдзвону номерів під час створення або редагування через API або у відповідному розділі особистого кабінету, наприклад, “Обдзвон завершено”.
Події у голосових меню	Налаштовуються для кожного окремого голосового меню під час створення чи редагування на сторінці особистого кабінету “Голосове меню”, наприклад, натискання клієнтом клавіші “1”
Події дзвінків	Налаштовуються на сторінці особистого кабінету “API”, наприклад “Завершення дзвінка”. Зверніть увагу, дія закріплюється за подією дзвінка незалежно від зовнішньої лінії, яка задіяна при цьому
Подія черги з голосовим супроводом	Доступно при створенні або редагуванні вхідного сценарію на сторінці особистого кабінету “Вхідні сценарії”, при виборі перенаправлення на “Черга з супроводом” та активації опції “Спеціальна дія“

Докладніше з процесом обробки подій можна ознайомитись в інструкції з обробки подій.
Відправлення вебхука з типом тіла “Стандартний JSON” передбачає формування тіла запиту на підставі типу події, за якою було надіслано вебхук:
Стандартний JSON для подій дзвінків:

{
  "event": "CALL_END", // Подія, за якою було відправлено вебхук
  "call": { // Масив даних про дзвінок
    "id": 1091944, // Випадково генерований id дзвінка для зв'язку його з іншими подіями дзвінків
    "dbid": 275, // id під яким цей дзвінок було збережено до бази даних. Згодом дзвінок має саме цей id
    "from": "380505557182", // Номер з якого було здійснено дзвінок
    "to": [ // Масив номерів, на які було переадресовано дзвінок
      "2000"
    ],
    "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) Згенерувати токен:

2) Натиснути кнопку “Сгенерувати посилання“:

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

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=&link=&phones=
Параметри, які потрібно заповнити:

phones	Номер телефону або список номерів телефону через кому які необхідно додати до обдзвону
name	Ім’я, яке буде закріплене за номерами, що додаються. Максимум – 100 символів. Необов’язкове поле
note	Нотатка, яка буде закріплена за номерами, що додаються. Максимум – 500 символів. Необов’язкове поле
link	Дані для Web Dialer, які будуть закріплені за номерами, що додаються. Максимум – 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.

При виконанні цього перенаправлення, на вказаний URL буде надіслано запит з таким вмістом:

{  
  "event": "ROUTE",  
  "call": {  
    "from": "380505557182" // Номер абонента, що телефонує  
  }  
}

У відповідь Ваш додаток має надіслати JSON наступної структури:

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

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

Керування чергою із голосовим супроводом
Сopied

Вебхук “Керування чергою із голосовим супроводом” дозволяє отримати інформацію про дзвінок для подальшої пріоритезації обробки клієнтів Вашою системою. Для роботи з цим вебхуком Ваш веб-додаток повинен приймати JSON методом POST за вказаним під час створення або редагування вхідного сценарію на сторінці особистого кабінету «Вхідні сценарії», при виборі перенаправлення на «Чергу з супроводом» та активації опції «Вебхук для керування» URL .

При виконанні цього перенаправлення, на вказаний URL буде надіслано запит з таким вмістом:

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

Черга з пріоритетом складається із 10 черг, які обробляються у порядку зменшення номера. За замовчуванням UniTalk визначає всі дзвінки в чергу з номером 5.
Ваша програма може змінити черговий номер, надіславши відповідь у наступні структури JSON:

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

Повідомлення
Сopied

Надсилання повідомлень у Chrome віджет
Сopied

POST /widget/sendNotification

Надсилає повідомлення вказаним користувачам.

Приклад body JSON запиту:

Як мінімум одне з полів об’єкта data має бути заповнено.

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

Відповідь:

{
    "status":"Success",
    "data": {
        "notificationId": 1985837794
    }
}

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

No users was specified for notifications send	Не було вказано жодного користувача для надсилання повідомлення
Data fields is all null	Не вказано значення жодного поля об’єкта `data`
User with 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
}

Відповідь:

{
   "status": "Success"
}

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

No users was specified for notifications hide	Не було вказано жодного користувача для приховування повідомлення
NotificationId not specified	`notificationId` не вказано
The specified users are not found or chrome extension not connected	Зазначені користувачі не знайдені або у них не підключений хром плагін

Про API Сopied

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

Загальні відомості Сopied

Дії Сopied

Отримання даних Сopied

Створення та редагування Сopied

Видалення Сopied

Оновлення Сopied

Відміна Сopied

Зняття з паузи Сopied

Пауза Сopied

Додання номерів Сopied

Отримання дзвінків Сopied

Отримання дзвінка Сopied

Видалення усіх номерів Сopied

Видалення номерів Сopied

Ініціація дзвінків Сopied

Прямий виклик SIP -> GSM Сopied

Створення нового дзвінка Сopied

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

Скидання дзвінка Сopied

Аудіо Сopied

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

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

Списки Сopied

BLOCKED_PHONES Сopied

Користувачі Сopied

Список Сopied

Дані про користувачів Сopied

Зміна стану роботи Сopied

Внутрішні лінії Сopied

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

Відділи Сopied

Отримання груп Сopied

Видалення номера з групи Сopied

Історія дзвінків Сopied

Здобуття історії Сopied

Вебхуки Сopied

Рух за балансом Сopied

Обробка подій Сopied

Вхідні вебхуки Сopied

AUTODIAL_ADD Сopied

AUTODIAL_REMOVE Сopied

Переклад дзвінка на відповідального оператора Сopied

Керування чергою із голосовим супроводом Сopied

Повідомлення Сopied

Надсилання повідомлень у Chrome віджет Сopied

Прихованні повідомлення у віджеті Chrome Сopied

Про API
Сopied

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

Загальні відомості
Сopied

Дії
Сopied

Отримання даних
Сopied

Створення та редагування
Сopied

Видалення
Сopied

Оновлення
Сopied

Відміна
Сopied

Зняття з паузи
Сopied

Пауза
Сopied

Додання номерів
Сopied

Отримання дзвінків
Сopied

Отримання дзвінка
Сopied

Видалення усіх номерів
Сopied

Видалення номерів
Сopied

Ініціація дзвінків
Сopied

Прямий виклик SIP -> GSM
Сopied

Створення нового дзвінка
Сopied

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

Скидання дзвінка
Сopied

Аудіо
Сopied

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

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

Списки
Сopied

BLOCKED_PHONES
Сopied

Користувачі
Сopied

Список
Сopied

Дані про користувачів
Сopied

Зміна стану роботи
Сopied

Внутрішні лінії
Сopied

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

Відділи
Сopied

Отримання груп
Сopied

Видалення номера з групи
Сopied

Історія дзвінків
Сopied

Здобуття історії
Сopied

Вебхуки
Сopied

Рух за балансом
Сopied

Обробка подій
Сopied

Вхідні вебхуки
Сopied

AUTODIAL_ADD
Сopied

AUTODIAL_REMOVE
Сopied

Переклад дзвінка на відповідального оператора
Сopied

Керування чергою із голосовим супроводом
Сopied

Повідомлення
Сopied

Надсилання повідомлень у Chrome віджет
Сopied

Прихованні повідомлення у віджеті Chrome
Сopied