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

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

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

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

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

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

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

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

Назва – назва webhook запиту
URL – адреса обробника, на яку буде надіслано запит. Стандартні порти: 80 для HTTP та 443 для HTTPS.
Для встановлення Webhook на URL із зазначеним портом можна передавати URL у вигляді: http://11.111.111.11:80
Метод відправки даних:
- GET – запит із передачею параметрів в адресному рядку (URL-адреса запиту);
- POST – запит із передачею параметрів у тілі (body) запиту;
- PUT – запит для зміни екземпляра із зазначеним ID;
- DELETE – запит із передачею параметрів для видалення екземпляра із зазначеним ID
Тип відправки даних – це формат даних, у якому будуть відправлені параметри запиту.
- 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 – supportringostat_example

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

Приклад з номерами: 380441111111,380441111112,380441111113

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

{ "dst_phone": "380441111111,380441111112,380441111113"}

Приклад з SIP акаунтами: sip_test1,sip_test2,sip_test3
Приклад повної відповіді із сервера у форматі json:
{"dst_callee":"sip_test1,sip_test2,sip_test3"}

Приклад з SIP акаунтами та номерами: 380441111111,sip_test1,380441111113

Приклад повної відповіді із сервера у форматі json:{"dst_callee":"380441111111,sip_test1,380441111113"}

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

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

URL: адреса обробника
Метод відправки даних: GET
Тип відправки даних: http чи json, не має значення
Тип прийому даних: завжди json
Поле для переадресації дзвінка (для json): для повернення ID схеми переадресації використовується спеціальний параметр schema
У відповідь на http-запит повинен повернутися цей параметр у форматі json і ID схеми переадресації.
Щоб дізнатися, який ID присвоєний потрібній схемі переадресації, в меню навігації перейдіть до розділу Віртуальна АТС -> Переадресація та у потрібної схеми натисніть кнопку Редагувати схему:

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

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

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

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

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

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

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

У цьому файлі описані всі параметри, які можна передавати

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

{
"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}';
}
?>

Рекомендуємо для налаштування webhook номера додатково використовувати API-метод експорту даних про співробітників проєкту.

Цей API метод дасть змогу отримати всі доступні напрямки співробітників для подальшої переадресації дзвінка.

Схожі статті

Webhooks. Створення webhook-запиту

Налаштування інтеграції KeepinCRM

Інтеграція з KeyCRM

API Ringostat. Експорт даних про співробітників проєкту

Інтеграція із LBS Cloud