К основному содержимому
Webhook номер
Katerina Tverdochleb avatar
Автор: Katerina Tverdochleb
Обновлено больше недели назад

Webhook номер переадресации — уникальный инструмент, который позволяет АТС Ringostat получать в ответ на http(s)-запрос номер телефона или sip-логин, на который будет дальнейшая переадресация звонка.

Данная функция позволяет получать направление переадресации с внешнего ресурса в зависимости от параметров входящего звонка. Параметры звонка могут приходить в соответствии с настройками 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): рекомендуем использовать 1 из вариантов имён: dst_phone или dst_callee для возврата параметров

  • В ответ на http-запрос, должен вернуться этот параметр в формате json и содержать направление (номер в международном формате или SIP URI нужного sip аккаунта).

  • Номер переадресации в международном формате выглядит так:

  • 380ХХХХХХХХХ (12 цифр) – Украина;

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

Пример возврата SIP URI – supportringostat_example

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


Пример c номерами: 380441111111,380441111112,380441111113

Пример полного ответа с сервера в формате json:

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

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

Пример c 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 метод позволит получить все доступные направления сотрудников для дальнейшей переадресации звонка.

Нашли ответ на свой вопрос?