Веб-хуки
Last updated
Was this helpful?
Last updated
Was this helpful?
Веб-хуки — это простой способ, с помощью которого одно приложение может уведомлять другое о каком-то событии в реальном времени.
Ваш вебхук будет получать запросы с разных IP-адресов.
Предположим, вы создаете бота, который автоматически обрабатывает заказы пользователей, скажем, на сайте интернет-магазина. В этот бот встроена возможность использовать веб-хуки для того, чтобы другие системы узнавали о ключевых событиях. Вот как это работает:
Создание веб-хука: Вы создаете веб-хук для какого-то важного события, например, завершения обработки заказа. В процессе создания вы указываете URL-адрес, на который нужно отправить уведомление, когда произойдет определенное событие.
Происходит событие: В диалоге с Савви пользователь делает заказ, и Савви успешно его обрабатывает. После завершения всех вычислений и операций, Савви понимает, что пришло время уведомить другие системы об этом.
Отправка веб-хука: Сразу после успешного завершения обработки заказа, Савви отправляет HTTP-запрос на указанный URL, содержащий информацию о заказе — его статус, номер, детали и т.д. Этот запрос как раз и называется веб-хуком.
Обработка на стороне получателя: Другая система — например, сервис доставки или CRM — получает этот запрос (веб-хук) и использует его для выполнения дальнейших действий. Допустим, CRM получает уведомление и обновляет данные клиента о его новом заказе, или сервис доставки начинает подготовку к отправке посылки.
Таким образом, использование веб-хуков в Савви позволяет легко и автоматически интегрировать его с другими приложениями и сервисами, устраняя необходимость в постоянных проверках статуса и давая возможность сразу же реагировать на произошедшие события. Это делает взаимодействие между системами более быстрым, точным и удобным.
Теперь пройдемся подробнее по техническим особенностям каждого из этапов.
Создание веб-хуков происходит через раздел Действия внутри настроек бота
Название действия - просто название для отображения в списке.
Название функции - это название функции, которое будет видеть LLM-модель. Данное название указывается на английском без пробелов. Название должно отображать общий смысл действия.
Описание функции - более подробное описание смысла действия. По данному описанию Савви будет понимать, когда ее нужно вызывать.
Сообщение об ошибке - сообщение, которое будет получать Савви от действия, в случае, если на стороне веб-хука вернется ошибка. Может быть пустым, в этом случае Савви получит текст ошибки от URL-адреса, на который отправляется веб-хук.
Аргументы действий - это переменные, которые необходимо заполнять ботом, и которые далее можно будет выбирать при добавлении шагов / вызове конкретных запросов.
Например, вы используете вызов по API для получения данных по заказу используя телефон клиента и дату рождения. Вы можете задать тут сразу эти переменные и бот поймет, что их нужно собирать у клиента перед вызовом API. При добавлении шагов эти переменные будут заполняться конкретными значениями и их можно подставлять в нужные места.
Константы действия - это конкретные постоянные значения, которые можно задать фиксированно и которые можно вызывать во всех последующих шагах.
Например, вам понадобилось обратиться по API к какому-то сервису. При этом, при вызове этого сервиса используется какое-то конкретный ваш токен, который необходимо передавать на нескольких шагах. Используя константы, можно задать этот токен один раз и потом выбирать его, без необходимости прописывать его каждый раз на каждом шаге отдельно.
Название - название для отображения в списке шагов.
URL - сюда указывается адрес на стороне куда будет передаваться запрос. Это может быть как IP-адрес, так и доменное имя, например, https://192.168.34.12 или https://test.ru (тут будет какой-то ваш нужный адрес).
Метод запроса - методы отправляемого запроса. Этот метод должна предоставлять конечная сторона. Подробнее о методах, можно посмотреть здесь.
Параметры, которые будут передаваться в URL - это те параметры, которые обычно в адресе передаются после знака ?.
Например:
https://192.168.34.12/CRM?phone=79112345678&date=09012024
Где, phone и date - это параметры
В форме шага данный пример будет выглядеть так:
Но в данном случае, мы передали фиксированные значения. А как сделать, когда эти величины являются изменяемыми и у каждого клиента / диалога они будут свои? Для этого используются переменные.
Переменные мы указывали на предыдущем шаге, когда добавили их в форме действия, теперь нам осталось их просто выбрать через кнопку +. Для выше описанного примера, когда нам нужно указать изменяемые параметры, мы делаем так:
При этом, несмотря на то, что мы рекомендуем делать подробное описание, боту даже не обязательно описывать дополнительные инструкции о том, какие параметры ему нужно запросить у клиента, он и так это поймет. Поэтому названия переменных лучше выбирать понятные.
В URL-адресе так же можно указывать переменные, когда они в явном виде не являются параметрами, например, так:
Где phone будет автоматом заменяться на телефон присаланный клиентом.
В заголовках запроса часто передается информация об авторизации.
Это скорее статические параметры, но иногда могут передаваться и динамические параметры, какие-либо ключ шифрования, которые получены на предыдущем шаге.
В случае с отправкой POST, PUT, DELETE и PATCH запросов появляется поле, в котором указывается тело запроса.
У нас реализовано два типа тела - это текст и JSON.
Для того, чтобы при отправке не возникало ошибок, требуется соблюдать определенные правила синтаксиса. Элементы JSON должны быть в кавычках. Переменные так же выбираются нажатием на +. На примере выше рассмотренного примера, тело запроса будет выглядеть так:
Не забывайте про кавычки при использовании JSON, даже для выделения переменных.
Можно указать статус коды, на которые бот будет реагировать. По умолчанию ставится код 200, т.е. код успешного возврата. В случае не успеха, бот получит текст, написанный в поле "Сообщение об ошибке" из настроек действия.
Можно убрать отбор на статус коды - и тогда он будет видеть все статусы и все ошибки, которые ему возвращаются и выдавать их клиенту.
Поскольку, как мы говорили ранее, мы можем передавать последовательность шагов, в том числе в виде веб-хуков за один раз, то есть настройка, которая определяет, а что мы передадим боту в ответ:
Все - передадим все ответы с каждого шага
Только первый - только ответ от первого шага
Только последний - только ответ с последнего шага
По умолчанию, ставится ответ с последнего шага, что кажется логичным. Хотя, конечно, бывают сценарии в которых мы можем передать информацию с первого шага и дальше выполнить ряд служебных действий, ответ от которых мы не передаем клиенту, например, когда мы просто оповещаем сторонние системы о каком-то триггере.
Есть еще одна настройка позволяющая регулировать текст возвращаемого ответа боту в случае ошибки.
Например, если мы не хотим передавать текст вернувшейся ошибки, т.к. там могут быть технические детали не нужные клиенту, мы можем унифицировать текст возвращаемый боту, который он будет выдавать клиенту через данное поле:
