Вебхуки

Обновлено 13 мая 2024

Graph

Вебхук — это способ, с помощью которого можно обращаться к подсистемам смартапа, реализованным на любых языках программирования и размещенным на сторонних серверах. Подсистемы производят вычисления для определенных задач и возвращают смартапу переменные, необходимые для работы сценария.

При использовании вебхука ассистент перед переходом к выполнению блоков экрана передаст все переменные на ваш сервер и будет ждать ответа.

Получив ответ, асисстент обновит значения переменных и перейдет к выполнению блоков.

Таким образом использование вебхуков позволяет дополнять и изменять переменные в процессе работы смартапа.

Используйте вебхуки, если вашему смартапу необходимо часто вычислять или сохранять данные и строить диалог с пользователем с учетом них. В этом случае вы сможете делать сложные вычисления и интеграции на собственном сервере, используя при этом любой язык программирования.

Вы также можете использовать блок HTTP-запрос, если для работы смартапа нужны небольшие вычисления или сохранение небольших объемов данных.

Включение вебхуков

Адрес вебхука может быть публичным или тестовым:

• вебхуки, развернутые на публичных адресах, работают с опубликованными смартапами;
• вебхуки, развернутые на тестовых адресах, помогают проводить диагностику и отладку в процессе разработки смартапа.

Сообщения, которыми ассистент обменивается со сторонним вебхуком, соответствуют протоколу вебхуков Graph.

Сервер для вебхука можно разрабатывать локально, а затем загружать код на публичный сервер. Например, с помощью ngrok .

Чтобы включить сторонние вебхуки:

1. В левой навигационной панели проекта нажмите Настройки. Откроется окно Настройки сценария SmartApp.
2. На вкладке Базовые настройки в блоке Настройки вебхука укажите в зависимости от настраиваемого вебхука адрес в поле Публичный или Тестовый.
3. Нажмите кнопку Сохранить.

Отправка вебхуков

Чтобы отправлять вебхуки:

1. Выберите экран, с которого необходимо отправлять вебхуки.

2. В названии экрана укажите имя события, которое будет передаваться на сторонний сервер.

   Например event1.

3. Нажмите на кнопку вебхука в правом верхнем углу экрана.

Смартап будет отправлять переменные и выбранное событие на сервер, а затем копировать переменные из ответа сервера. Только после этого смартап будет выполнять блоки на экране.

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