Вебхуки
Что такое вебхуки в Aimylogic
Вебхук — это «сквозная» логика вашего бота, которая производит вычисления на определенных экранах и возвращает боту нужные переменные, с которыми он дальше работает в сценарии.
С помощью вебхуков вы можете реализовывать логику для вашего бота на вашем собственном сервере на любом языке программирования.
С чего начать
У нас есть урок по созданию сценария с использованием вебхука. Мы рекомендуем вам его пройти после прочтения текущей статьи, чтобы потренироваться и закрепить знания.
Чтобы выполнить урок, вам не нужны навыки программирования. Главное — придерживаться пошаговой инструкции в уроке.
Вы также можете посмотреть видео вместо того, чтобы читать урок:
Как работает вебхук в Aimylogic
Если вы используете вебхук в боте, то при переходе на новый экран сценария бот автоматически отправит все текущие переменные на ваш сервер и будет ждать ответа. Когда ответ придет, бот скопирует отправленные переменные, которые сгенерировал сервер, а потом начнет выполнять блоки на экране.
Таким образом вы можете дополнять и изменять переменные в вашем боте прямо в процессе работы. Вы сможете реализовать даже самую сложную логику для вычислений.
Например:
В этом сценарии вебхук будет вызван с запуском бота прямо на первом экране. На сервер вебхука будут переданы все текущие переменные, а в ответ получены новые. В частности здесь сервер вернет объект, в котором есть переменная $lastSeen
.
Если переменная $lastSeen
не пустая, то бот перейдет на второй экран, на котором тоже будет вызван вебх ук и получена переменная $name
.
Если же в $lastSeen
ничего нет, то бот перейдет на третий экран, где вебхук не вызывается.
События вебхука
На каждом экране, где вы хотите вызывать ваш вебхук, нужно указать событие. Событие — это любая строка текста, которая будет передана вебхуку вместе с переменными. Таким образом сервер поймет, с какого экрана пришел запрос и какие данные нужно вернуть.
В примере выше на первом экране бот отправит вебхук с событием start
, на втором — с событием seen
. Событие отображается в правом верхнем углу каждого экрана.
Вы можете указывать одинаковые события для разных экранов. В качестве события можно использовать любой текст.
Чтобы указать событие, просто напишите его название в заголовке экрана:
Как включить вебхук
В настройках вашего бота есть пункт Настройки вебхука.
Здесь вам нужно указать публичный URL вашего сервера, который умеет принимать POST-запросы в формате вебхуков Aimylogic.
Вы также можете указать URL для тестов. Тогда при тестировании сценария в тестовом виджете бот будет вызывать ваш тестовый сервер. Так вы можете разрабатывать сервер для вебхука локально на своей машине и только потом загружать код на публичный сервер — например, используя утилиту ngrok.
После того как вы прописали URL вашего вебхука, вы можете включать и выключать события на экранах в сценарии вашего бота.
Для этого укажите название события в заголовке экрана:
Вы можете выбрать любой цвет заголовка, а затем кликнуть на значок вебхука , чтобы он загорелся:
Если событие на экране включено, то бот будет отправлять переменные и выбранное событие на сервер, а затем копировать переменные из ответа сервера. Только после этого бот будет выполнять блоки на экране.
Переменные, полученные от вашего сервера, можно использовать точно так же, как и все другие — например, подставлять в текстовый ответ, использовать в условиях или в HTTP-запросах.
Протокол вебхуков Aimylogic
На каждом экране, где включено событие для вебхука, бот посылает POST-запрос, а в теле запроса передает объект JSON, в котором соде ржатся все текущие переменные бота, в том числе системные, а также поле action
— текст события, которое вы прописали на этом экране:
{ "action": "event1", "queryText": "пока", "userId": "1234567890", "channelId": "0000000000000000", "channelType": "telegram", "rawRequest": {"message": {...}}, "variable1": 50, "variable2": "значение"}
Ваш сервер должен вернуть в ответ JSON с нужными вашему боту переменными, которые он ожидает получить на этом экране:
{ "lastSeen": 60, "name": "Василий", "data": { "age": 30, "website": "http://example.com" }}
В этом примере сервер вебхука вернул переменные $lastSeen
, $name
и $data
. Теперь бот может их использовать в своем сценарии начиная с того экрана, на котором он получил эти переменные.