Что такое вебхуки в Aimylogic

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

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

С чего начать

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

Как работает вебхук в Aimylogic

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

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

Например:



В этом сценарии вебхук будет вызван на первом экране (как только бот запустится). На сервер вебхука будут переданы все текущие переменные и в ответ будут получены новые переменные (в данном случае сервер возвращает объект, в котором есть переменная 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. Теперь бот может их использовать в своем сценарии начиная с того экрана, на котором он получил эти переменные.

Чем вебхук отличается от блока HTTP запрос?

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

Не нужно перегружать сценарий блоками "HTTP-запрос", поэтому сценарий становится гораздо более компактным и понятным;
Вебхук всегда отправляет все текущие переменные на один и тот же URL, который вы прописываете только один раз в настройках бота;
Не нужно парсить ответ от сервера каждый раз, потому что протокол вебхука стандартизирован, и бот сам скопирует все переменные из ответа;
Вебхук можно включать/выключать на разных экранах и при этом не переделывать весь сценарий, чтобы отвязать переходы на блок HTTP-запрос;
Можно прописать тестовый URL вебхука, чтобы разрабатывать его локально на своем компьютере в момент разработки сценария, и при этом не влиять на работу бота, который уже общается с вашими клиентами.

Когда нужно использовать вебхук

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

Когда не нужно использовать вебхук

Если в вашем сценарии есть только одно место, где вам нужно вычислить/сохранить какие-то данные на вашем сервере, то проще будет использовать блок HTTP-запроса на нужном экране.

Как разработать вебхук

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

Node JS
Python

Запустить на Heroku

Где можно развернуть вебхук бесплатно

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

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

Heroku

Одним из возможных вариантов для бесплатного размещения сервера вебхука является платформа heroku.com - она позволяет создавать серверы на любом языке программирования.

Все шаблоны вебхуков, которые мы приводим выше, можно развернуть на Heroku просто кликнув на ссылку "Запустить на Heroku".

Webtask

Если вы создаете вебхук с использованием Node JS, и при этом ваш код не очень сложный и не очень ресурсоемкий, то вам может подойти еще один бесплатный вариант для запуска приложений на Node JS - webtask.io
Была ли эта статья полезна?
отменить
Спасибо!