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