Вебхук — это HTTP-запрос, с помощью которого чат-бот в определенных ситуациях передает данные в сторонний сервис по заданному адресу. Чат-бот ожидает ответа на вебхук и может дальше использовать его в сценарии.
С помощью вебхуков вы можете на отдельном сервере реализовать логику на любом языке программирования.
Адрес вебхука может быть публичным или тестовым:
- вебхуки, развернутые на публичных адресах, работают с опубликованными чат-ботами;
- вебхуки, развернутые на тестовых адресах, помогают проводить диагностику и отладку в процессе разработки чат-бота.
Сообщения, которыми чат-бот обменивается со сторонним вебхуком, соответствуют протоколу вебхуков Graph.
Сервер для вебхука можно разрабатывать локально, а затем загружать код на публичный сервер. Например, с помощью 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. Она позволяет создавать серверы на любом языке программирования.