Вебхук — это HTTP-запрос, с помощью которого голосовой робот в определенных ситуациях передает данные в сторонний сервис по заданному адресу. Робот ожидает ответа на вебхук и может дальше использовать его в сценарии.
С помощью вебхуков вы можете на отдельном сервере реализовать логику на любом языке программирования.
Адрес вебхука может быть публичным или тестовым:
- вебхуки, развернутые на публичных адресах, работают с опубликованными голосовыми роботами;
- вебхуки, развернутые на тестовых адресах, помогают проводить диагностику и отладку в процессе разработки голосового робота.
Сообщения, которыми голосовой робот обменивается со сторонним вебхуком, соответствуют протоколу вебхуков Graph для SaluteBot Voice.
Сервер для вебхука можно разрабатывать локально, а затем загружать код на публичный сервер. Например, с помощью ngrok.
Чтобы включить сторонние вебхуки:
В левой навигационной панели проекта нажмите Настройки.
Откроется окно Настройки голосового робота.
Выберите вкладку Базовые настройки.
В блоке Настройки вебхука выберите какой вебхук необходимо указать: публичный или тестовый.
В списке Вариант ввода выберите Пользовательский Webhook.
Укажите адрес вебхука в поле Публичный webhook или Тестовый webhook, в зависимости от настраиваемого вебхука.
Нажмите кнопку Сохранить.
Вебхук — это способ, с помощью которого можно обращаться к подсистемам голосового робота, реализованным на любых языках программирования и размещенным на сторонних серверах. Подсистемы производят вычисления для определенных задач и возвращают роботу переменные, необходимые для работы сценария.
При использовании вебхука голосовой робот перед переходом на выполнением блоков экрана передаст все переменные на ваш сервер и будет ждать ответа.
Получив ответ, асисстент обновит значения переменных и перейдет к выполнению блоков.
Таким образом использование вебхуков позволяет дополнять и изменять переменные в процессе работы голосового робота.
Используйте вебхуки, если вашему голосовому роботу необходимо часто вычислять или сохранять данные и строить диалог с пользователем с учетом них. В этом случае вы сможете делать сложные вычисления и интеграции на собственном сервере, используя при этом любой язык программирования.
Вы также можете использовать блок HTTP-запрос, если для работы робота нужны небольшие вычисления или сохранение небольших объемов данных.
Отправка вебхуков
Чтобы использовать вебхуки в сценарии, в параметрах голосового робота укажите сервер, на который они будут передаваться.
Чтобы отправлять вебхуки:
Выберите экран, с которого необходимо отправлять вебхуки.
В названии экрана укажите имя события, которое будет передаваться на сторонний сервер.
Например
event1.Нажмите на кнопку вебхука в правом верхнем углу экрана.
Голосовой робот будет отправлять переменные и выбранное событие на сервер, а затем копировать переменные из ответа сервера. Только после этого голосовой робот будет выполнять блоки на экране.
Переменные, полученные от вашего сервера, можно использовать точно так же, как и любые другие – например подставлять в текстовый ответ, использовать в условиях или в HTTP-запросах.
События вебхука
На каждом экране, где надо вызывать вебхук, требуется указать событие.
Событие – это любая строка текста, которая будет передана вебхуку вместе с переменными. Событие показывает серверу, с какого экрана пришел запрос, и какие данные надо вернуть.
События задаются в названии экрана и могут быть представлены в виде произвольного текста.
Разные экраны могут иметь одинаковые события.
Протокол вебхуков Graph
На каждом экране, где включено событие для вебхука, голосовой робот посылает POST-запрос, в теле которого передает JSON-объект. Этот объект содержит все текущие переменные робота (в том числе системные), а также поле action – текст события, заданное в названии экрана.
Пример:
{
"action": "event1",
"queryText": "пока",
"userId": "1234567890",
"rawRequest": {"message": {...}},
"variable1": 50,
"variable2": "значение"
}
Голосовой робот ожидает от сервера JSON-объект с переменными, которые робот использует в блоках экрана.
Пример:
{
"lastSeen": 60,
"name": "Василий",
"data": {
"age": 30,
"website": "http://example.com"
}
}
В этом примере сервер вебхука вернул переменные lastSeen, name и data. Теперь голосовой робот может их использовать в своем сценарии, начиная с того экрана, на котором он получил эти переменные.
Отличие вебхука от блока HTTP-запрос
Можно использовать блок HTTP-запрос всякий раз, когда голосовому роботу надо получить данные от вашего сервера.
При этом вебхук обладает следующими преимуществами, если необходимо делать запросы более чем с одного экрана:
- Сценарий не перегружается блоками HTTP-запрос, что делает его более понятным.
- Вебхук всегда отправляет все текущие переменные на один адрес, заданный в настройках голосового робота.
- Протокол вебхука стандартизирован, и робот самостоятельно скопирует все переменные из ответа.
- Вебхук можно включать или выключать на разных экранах.
- Вебхук можно разрабатывать и отлаживать на непубличном тестовом адресе.
Где бесплатно развернуть вебхук
Чтобы запустить вебхук необходим хостинг.
При этом во время разработки вы можете использовать такие утилиты, как ngrok, чтобы на время получить публичный адрес, который позволит серверу на вашем локальном компьютере получать запросы от вашего голосового робота.
Для бесплатного публичного размещения сервера для обработки вебхуков можно рассмотреть платформу heroku.com. Она позволяет создавать серверы на любом языке программирования.