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 – [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}';
}
?>
Рекомендуємо для налаштування webhook номера додатково використовувати API-метод експорту даних про співробітників проєкту.
Цей API метод дасть змогу отримати всі доступні напрямки співробітників для подальшої переадресації дзвінка.