Вебхук — это способ, с помощью которого можно обращаться к подсистемам смартапа, реализованным на любых языках программирования и размещенным на сторонних серверах. Подсистемы производят вычисления для определенных задач и возвращают смартапу переменные, необходимые для работы сценария.
При использовании вебхука ассистент перед переходом к выполнению блоков экрана передаст все переменные на ваш сервер и будет ждать ответа.
Получив ответ, асисстент обновит значения переменных и перейдет к выполнению блоков.
Таким образом использование вебхуков позволяет дополнять и изменять переменные в процессе работы смартапа.
Используйте вебхуки, если вашему смартапу необходимо часто вычислять или сохранять данные и строить диалог с пользователем с учетом них. В этом случае вы сможете делать сложные вычисления и интеграции на собственном сервере, используя при этом любой язык программирования.
Вы также можете использовать блок 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 . Она позволяет создавать серверы на любом языке программирования.