Усі колекції
API та Webhooks
Webhook номер
Webhook номер
Katerina Tverdochleb avatar
Автор: Katerina Tverdochleb
Оновлено протягом останнього тижня

Webhook номер переадресації — унікальний інструмент, який дозволяє АТС Ringostat отримувати у відповідь на http(s)-запит номер телефона або id схеми переадресації, на який буде йти переадресація дзвінка.

Ця функція дозволяє отримувати напрямок переадресації із зовнішнього ресурсу залежно від параметрів вхідного дзвінка. Параметри дзвінка можуть надходити відповідно до налаштувань hook-a в HTTP заголовках, JSON форматі або за допомогою JSON-RPC протоколу. Відповідь має містити напрямок (номер у міжнародному форматі/sip) у тілі відповіді HTTP або у конкретному ідентифікаторі JSON формату.

WebHooks - спрощений варіант rest-подій та rest-команд, що не вимагає написання програми. Але, навіть не дивлячись на це, робота з REST – непросте завдання, яке вимагає солідної кваліфікації від розробника.

Налаштування вебхук номера

Використовувати Webhook номер для переадресації дзвінків ви зможете після його створення та налаштування.

У меню навігації виберіть Віртуальна АТС -> Webhook номер і створіть webhook з довільним ім'ям:

Щоб потрапити в меню налаштування webhook номера виберіть "Редагувати"

Загальний опис налаштувань полів

  1. Назва – назва webhook запиту

  2. URL – адреса обробника, на яку буде надіслано запит. Стандартні порти: 80 для HTTP та 443 для HTTPS.

    Для встановлення Webhook на URL із зазначеним портом можна передавати URL у вигляді: http://11.111.111.11:80

  3. Метод відправки даних:

    • GET – запит із передачею параметрів в адресному рядку (URL-адреса запиту);

    • POST – запит із передачею параметрів у тілі (body) запиту;

    • PUT – запит для зміни екземпляра із зазначеним ID;

    • DELETE – запит із передачею параметрів для видалення екземпляра із зазначеним ID

  4. Тип відправки даних – це формат даних, у якому будуть відправлені параметри запиту.

    • http – відправка параметрів в адресному рядку (URL-адреса запиту);

    • json – відправка параметрів у форматі об'єкта (набір пар ключ/значення) у запиті;

    • json-rpc – протокол віддаленого виклику процедур, що використовує JSON для кодування повідомлень;

5. Тип прийому даних – формат даних, у якому буде прийнято параметри запиту.

  • http – прийом параметрів в адресному рядку (URL-адреса запиту);

  • json – прийом параметрів у форматі об'єкта (набір пар ключ/значення) у запиті;

  • json-rpc – протокол віддаленого виклику процедур, що використовує JSON для кодування повідомлень.

6. Поле номера переадресації (для json) – ім'я параметра, в якому буде вказано напрямок переадресації:

  • якщо у відповідь на запит буде вказана переадресація на номер телефона, ім'я, що рекомендується, – dst_phone або dst_callee

  • якщо у відповідь на запит буде вказана переадресація на ID схеми переадресації, тоді потрібно повернути параметр schema

7. Json-rpc метод – назва методу (функції), який слід викликати;

8. Таймаут у секундах – таймаут відправки додзвону на напрямок переадресації, що повернули у відповідь на запит

Варіанти налаштувань переадресації дзвінка

Переадресувати дзвінок за допомогою Webhook можна:

  • на номер телефону/sip акаунт

  • на схему переадресації у проекті

Переадресація на номер телефона / SIP акаунти / декілька номерів

Приклад налаштування:

  • URL: адреса обробника

  • Метод відправки даних: GET

  • Тип відправки даних: http чи json, не має значення

  • Тип прийому даних: завжди json

  • Поле для переадресації дзвінка (для json): рекомендуємо використовувати один із варіантів імен: dst_phone або dst_callee для повернення параметрів

  • У відповідь на http-запит повинен повернутися цей параметр у форматі json і містити напрямок (номер у міжнародному форматі або SIP URI потрібного sip акаунту).

  • Номер переадресації у міжнародному форматі виглядає так: 380ХХХХХХХХХ (12 цифр) – Україна;

    7ХХХХХХХХХХ (11 цифр) – Казахстан.

Приклад повернення SIP URI – sip/[email protected]

Також можлива переадресація одночасно на кілька номерів телефонів. Для цього необхідно перерахувати номери через кому.

Приклад: 380441111111,380441111112,380441111113

Приклад повної відповіді із сервера у форматі json:

{ dst_phone: '380441111111,380441111112,380441111113'}

Направлення дзвінка на схему переадресації у проекті

Приклад налаштування:

  • URL: адреса обробника

  • Метод відправки даних: GET

  • Тип відправки даних: http чи json, не має значення

  • Тип прийому даних: завжди json

  • Поле для переадресації дзвінка (для json): для повернення ID схеми переадресації використовується спеціальний параметр schema

  • У відповідь на http-запит повинен повернутися цей параметр у форматі json і ID схеми переадресації.

    Щоб дізнатися, який ID присвоєний потрібній схемі переадресації, в меню навігації перейдіть до розділу Віртуальна АТС -> Переадресація та у потрібної схеми натисніть кнопку Редагувати схему:

Додавання параметрів Webhook

Ви можете додати до webhook номера список параметрів, які потрібно обробити та, в залежності від вхідних даних, повернути у відповідь напрямок переадресації дзвінка. Таке налаштування буде корисним, якщо вам, наприклад, необхідно налаштувати переадресацію на різних менеджерів/відділи.

Наприклад, залежно від вибраного параметра зі списку нижче.

Або навіть кастомного параметра, перехопленого на сайті за допомогою відстежуваних сутностей (наприклад місто, сторінка сайту і т.д.)

Щоб додати параметри — у відповідній таблиці виберіть значення та вкажіть імена параметрів, які будуть передані.

Параметри передачі

Ви можете додати до webhook номеру список параметрів, які потрібно обробити та в залежності від вхідних даних повернути у відповідь напрямок переадресації дзвінка.

Ім'я параметра

Опис параметра

Номер абонента

Номер клієнта, який зателефонував або замовив зворотній дзвінок

Куди дзвонили

Номер із пулу підміни, на який зателефонували

Дата

Дата та час дзвінка

Цінність

Цей параметр не може бути захоплений, оскільки Webhook номер

приходить до дзвінка

Тривалість

Цей параметр завжди повертає "0", оскільки Webhook номер приходить ДО дзвінка

Тип

Тип дзвінка: in

Очікування

Цей параметр не може бути перехоплений, оскільки Webhook номер приходить ДО дзвінка

Тривалість розмови

Цей параметр завжди повертає "0", оскільки Webhook номер приходить ДО дзвінка

З ким з'єднано

Цей параметр не може бути перехоплений, оскільки Webhook номер приходить ДО дзвінка

Який за рахунком дзвінок

Повертає суму, який за рахунком дзвінок із цього номера

Цільовий

Цей параметр не може бути перехоплений, оскільки Webhook номер приходить ДО дзвінка

Повторний

Цей параметр не може бути перехоплений, оскільки Webhook номер приходить ДО дзвінка

Джерело

Джерело переходу відвідувача

UTM-мітка – utm_source

Канал

Канал трафіку переходу відвідувача

UTM-мітка – utm_medium

Кампанія

Рекламна кампанія переходу

UTM-мітка – utm_campaign

Контент

Вміст оголошення в кампанії

UTM-мітка – utm_content

Ключове слово

Ключове слово переходу на сайт

Запис

Унікальний ID дзвінка в Ringostat

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

Цей параметр не може бути перехоплений, оскільки Webhook номер приходить ДО дзвінка

UUID відвідувача

Google Analytics Client ID відвідувача

IP відвідувача

IP-адреса відвідувача

Крок переадресації

Етап розподілу виклику, повертає назву методу та таймаут у секундах (приклад:webhookNumber:120)

Посилання на аудіозапис

Цей параметр не може бути перехоплений, оскільки Webhook номер приходить ДО дзвінка

Унікальний (перший) дзвінок

Вказує, чи є дзвінок 1м з цього номера клієнта

Унікальний цільовий дзвінок

Цей параметр не може бути перехоплений, оскільки Webhook номер приходить ДО дзвінка

Last Page

Сторінка, з якої здійснено дзвінок

Лендінг

Сторінка входу на сайт

Тип підміни

Тип підміни: Динамічна/Статична/Callback

Ім'я пула

Назва динамічного та статичного пулу підміни, звідки був виданий номер

Схема переадресації

Назва схеми переадресації, куди було переведено дзвінок

ID дзвінка

Унікальний ідентифікатор дзвінка

User-Agent

Цей параметр не може бути перехоплений, оскільки Webhook номер приходить ДО дзвінка

Google Analytics resource UUID

Ідентифікатор відстеження Google Analytics

ID менеджера

Цей параметр не може бути перехоплений, оскільки Webhook номер приходить ДО дзвінка

Додатковий номер

Додатковий номер, який клієнт ввів у меню IVR

Відповідальні менеджери

Цей параметр не може бути перехоплений, оскільки Webhook номер приходить ДО дзвінка

custom

Кастомний параметр, перехоплений на сайті

Roistat Visit ID

Номер візиту Roistat

ID проекта

Унікальний ідентифікатор проекта у Ringostat

Співробітник

ПІБ співробітника, який обробив дзвінок

Цей параметр не може бути перехоплений, оскільки Webhook номер приходить ДО дзвінка

Відділ

Назва відділу, де знаходиться співробітник, який обробив дзвінок.

Цей параметр не може бути перехоплений, оскільки Webhook номер приходить ДО дзвінка

Цільовий

Параметр набуває значення 0 або 1 в залежності від того, чи був дзвінок цільовим.

Повторний

Параметр набуває значення 0 або 1 в залежності від того, чи був дзвінок повторним

Код співробітника

ID співробітника, який обробив дзвінок.

Цей параметр не може бути перехоплений, оскільки Webhook номер приходить ДО дзвінка

Вихідний номер

Номер, який відобразився клієнту під час вихідного дзвінка від менеджера

User agent

Усі дані про пристрій користувача, а також про браузер переходу

Номер у форматі E.164

Номер формату E.164.

Номери E.164 можуть мати максимум 15 цифр і зазвичай записуються з префіксом «+».

Приклад відправки параметрів:

{
"caller":"380441112233",
"callee":"380442223344",
"date":"2018-08-13 11:11:11",
"type":"in",
"callnum":"1",
"source":"ringostat",
"medium":"support",
"campaign":"webhook_number",
"term":"test",
"content":"simple_webhook_number_test",
"record":"3333333333.3333333",
"useruuid":"1479099944.1534841744",
"userip":"10.10.10.10",
"callroute":"webhookNumber:90",
"uniquefirst":"1",
"lastpage":"ringostat.com/?utm_source=ringostat&utm_medium=support&utm_campaign=hook_number&utm_term=test",
"landing":"ringostat.com/?utm_source=ringostat&utm_medium=support&utm_campaign=hook_number&utm_term=test",
"replacetype":"dynamic",
"gaid":"UA-11111111-1",
"fullnum":"+380441112233",
"ivrnum":"3",
"callid":"3333333333.3333333",
"custom":"http://ringostat.com/?utm_source=ringostat&utm_med...
"roistat":"17541"
"employee_fio":"Иван Иванов"
"department":"Отдел продаж"
"proper_flag":"1"
"repeated_flag":"0"
"staffid":"1111"
"outbound_number":"380671234567"
"useragent":“Mozilla/5.0 (Linux; Android 8.0.0; LND-L29 Build/HONORLND-L29; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/96.0.4664.45 Mobile Safari/537.36”,
"project_id": “0000”,
"add_num_id":“102"
"E164":"+380561234567",
"agent_id":"1111"
"recording_wav":"https://app.ringostat.com/recordings/ua8_-11111111111.1111111.wav?token=462908f128343fc23862397ddd638953"
}

Це набір параметрів, які отримає ваш обробник

Налаштування переадресації на webhook

Більш детально ознайомитись із створенням, налаштуванням та функціоналом схем переадресації ви можете у статті бази знань.

Після створення Webhook номера його потрібно включити в схему переадресації.

Перейдіть до розділу "Віртуальна АТС" -> "Переадресація" -> "Створити нову схему переадресації":

Далі:

  • вкажіть зрозуміле ім'я схеми переадресації

  • виберіть напрямок – Webhook номер переадресації

  • виберіть створений webhook запит

  • вкажіть додаткові параметри схеми переадресації (робочий час/фоновий звук та сповіщення)

Приклад обробника webhook номера

Повертати ID схеми можна навіть без вказівки імені у параметрі + зробити перевірку і, у разі, якщо за вхідними даними не вдається повернути номер, у параметрі schema повернути ID схеми переадресації.

Увага! Приклад умовний та наданий для розуміння принципу роботи та реалізації!

Приклад обробника PHP, який перевіряє параметр "Тип підміни".

Якщо значення дорівнює "Динамічний" – у відповідь буде надіслано номер телефону

(ім'я параметра вказується у Полі номера для переадресації);

Якщо значення відрізняється – у відповідь буде надіслано ID схеми переадресації

(ім'я параметра не обов'язково вказувати в Полі номера для переадресації)

<?php
$insertion_type = !empty($_GET['insertionType']) ? $_GET['insertionType']: '';
if($insertion_type === 'dynamic') {
echo '{"dst_phone":380443334455}';
}
else {
echo '{"schema":26076}';
}
?>

Ви отримали відповідь на своє запитання?