Все коллекции
API и Webhooks
Webhook номер
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 – 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 номер приходит ДО звонка

Первый целевой звонок

Данный параметр не может быть захвачен, поскольку 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}';
}
?>

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