> For the complete documentation index, see [llms.txt](https://docs.suvvy.ai/ru/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.suvvy.ai/ru/deistviya/veb-khuki.md). # Веб-хуки Веб-хуки — это простой способ, с помощью которого одно приложение может уведомлять другое о каком-то событии в реальном времени. ## Описание работы {% hint style="warning" %} Ваш вебхук будет получать запросы **с разных IP-адресов.** {% endhint %} Предположим, вы создаете агента, который автоматически обрабатывает заказы пользователей, скажем, на сайте интернет-магазина. В этого агента встроена возможность использовать веб-хуки для того, чтобы другие системы узнавали о ключевых событиях. Вот как это работает: 1. **Создание веб-хука**: Вы создаете веб-хук для какого-то важного события, например, завершения обработки заказа. В процессе создания вы указываете URL-адрес, на который нужно отправить уведомление, когда произойдет определенное событие. 2. **Происходит событие**: В диалоге с Савви пользователь делает заказ, и Савви успешно его обрабатывает. После завершения всех вычислений и операций, Савви понимает, что пришло время уведомить другие системы об этом. 3. **Отправка веб-хука**: Сразу после успешного завершения обработки заказа, Савви отправляет HTTP-запрос на указанный URL, содержащий информацию о заказе — его статус, номер, детали и т.д. Этот запрос как раз и называется веб-хуком. 4. **Обработка на стороне получателя**: Другая система — например, сервис доставки или CRM — получает этот запрос (веб-хук) и использует его для выполнения дальнейших действий. Допустим, CRM получает уведомление и обновляет данные клиента о его новом заказе, или сервис доставки начинает подготовку к отправке посылки. Таким образом, использование веб-хуков в Савви позволяет легко и автоматически интегрировать его с другими приложениями и сервисами, устраняя необходимость в постоянных проверках статуса и давая возможность сразу же реагировать на произошедшие события. Это делает взаимодействие между системами более быстрым, точным и удобным. Теперь пройдемся подробнее по техническим особенностям каждого из этапов. ## Создание веб-хука {% stepper %} {% step %} ### Перейдите во вкладку Действия и нажмите на кнопку "Добавить"
{% endstep %} {% step %} ### Выберите тип шага Вебхук Тип шага "Вебхук" находится в разделе API-вызовы. О других типах шагов, таких как "Чтение ссылок", "Вызов агента", "Переключение агента"» и прочих мы расскажем в следующих разделах, в данном случае нас интересует веб-хук.
{% endstep %} {% step %} ### Настройте вебхук При выборе откроется форма шага 1:
**Название действия** - просто название для отображения в списке. **Название шага** - название самого шага.
**Переменные действий** - это переменные, которые необходимо заполнять агентом, и которые далее можно будет выбирать при добавлении шагов /вызове конкретных запросов. > Например, вы используете вызов по API для получения данных по заказу используя телефон клиента и дату рождения. Вы можете задать тут сразу эти переменные и агент поймёт, что их нужно собирать у клиента перед вызовом API. При добавлении шагов эти переменные будут заполняться конкретными значениями и их можно подставлять в нужные места.
**Константы действия** - это конкретные постоянные значения, которые можно задать фиксированно и которые можно вызывать во всех последующих шагах. > Например, вам понадобилось обратиться по API к какому-то сервису. При этом, при вызове этого сервиса используется какое-то конкретный ваш токен, который необходимо передавать на нескольких шагах. Используя константы, можно задать этот токен один раз и потом выбирать его, без необходимости прописывать его каждый раз на каждом шаге отдельно. > {% endstep %} {% step %} ### Настройка раздела "Условия срабатывания"
**Название функции** - это название функции, которое будет видеть бот. Данное название указывается на английском без пробелов. Название должно отображать общий смысл действия. {% hint style="success" %} После заполнения названия действия можно нажать на кнопку 🔃 справа от поля. Тогда название сгенерируется **автоматически.** {% endhint %} **Описание функции** - более подробное описание смысла действия. По данному описанию Савви будет понимать, когда ее нужно вызывать. **Сообщение об ошибке, передаваемое боту** - сообщение, которое будет получать Савви от действия, в случае, если на стороне веб-хука вернется ошибка. Может быть пустым, в этом случае Савви получит текст ошибки от URL-адреса, на который отправляется веб-хук. {% endstep %} {% step %} ### Настройка раздела "Дополнительные настройки"
**Действия при вызове** — в этом разделе мы отмечаем флаги тех настроек, которые нам требуются, а именно: **Добавить задержку перед вызовом** — полезно при работе с CRM, если на стороне интеграции выполняется какая-то автоматизация Остановить диалог при вызове — при вызове функции действия, агент прерывается Не отвечать при вызове — агент не напишет ответ клиенту, вызовется только функция\ **Присвоить тег при вызове** — при вызове функции диалогу присвоится тег, который Вы пропишете
**Действия при ошибке** — настройки, которые сработают в случае ошибки действия **Уведомлять при ошибке** — Если в процессе выполнения действия возникнет ошибка, то пользователь получит уведомление **Останавливать диалог при ошибке** — если действие выполнится с ошибкой, то диалог с агентом остановится. **Сообщение об ошибке, передаваемое** агенту— если действие выполнится с ошибкой, то в самой функции вернётся тот текст, который пропишет пользователь, например An error occured
**Результат, возвращаемый** агенту— здесь мы можем выбрать то, что вернётся агенту в результате выполнения функции, есть четыре варианта:
Настраиваемый результат позволяет вернуть настроенные переменные. Для этого, нужно нажать на колёсико справа от окна, в котором прописываем кастомизированный результат:
{% endstep %} {% endstepper %} ## Настройки веб-хука ### Название, URL и метод **Название** - название для отображения в списке шагов. **URL** - сюда указывается адрес на стороне куда будет передаваться запрос. Это может быть как **IP-адрес**, так и доменное имя, например, `https://192.168.34.12` или `https://test.ru` *(тут будет какой-то ваш нужный адрес).* **Метод запроса** - метод отправляемого запроса (GET, POST и т.д.). Этот метод должна предоставлять конечная сторона. Подробнее о разных методах, можно посмотреть [здесь](https://developer.mozilla.org/ru/docs/Web/HTTP/Methods). ### **Параметры, которые будут передаваться в URL** **Параметры, которые будут передаваться в URL** - это те параметры, которые обычно в адресе передаются после знака ?. > Например: > > > > Где, phone и date - это параметры В форме шага данный пример будет выглядеть так:
Но в данном случае, мы передали фиксированные значения. А как сделать, когда эти величины являются изменяемыми и у каждого клиента / диалога они будут свои? Для этого используются **переменные**. #### Использование переменных (аргументы действия) Переменные мы указывали на предыдущем шаге, когда добавили их в форме действия, теперь нам осталось их просто выбрать через кнопку **+**. Для выше описанного примера, когда нам нужно указать изменяемые параметры, мы делаем так:
При этом, несмотря на то, что мы рекомендуем делать подробное описание, боту даже не обязательно описывать дополнительные инструкции о том, какие параметры ему нужно запросить у клиента, он и так это поймет. Поэтому названия переменных лучше выбирать понятные. {% hint style="info" %} В URL-адресе так же можно указывать переменные, когда они в явном виде не являются параметрами, например, так: Где phone будет автоматом заменяться на телефон присаланный клиентом. {% endhint %} ### Заголовки запроса В заголовках запроса часто передается информация об авторизации. Это скорее статические параметры, но иногда могут передаваться и динамические параметры, какие-либо ключ шифрования, которые получены на предыдущем шаге.
### Отправка запросом с данными (POST, PUT, DELETE, PATCH) В случае с отправкой POST, PUT, DELETE и PATCH запросов появляется поле, в котором указывается тело запроса. У нас реализовано два типа тела - это текст и JSON. Для того, чтобы при отправке не возникало ошибок, требуется соблюдать определенные правила синтаксиса. Элементы JSON должны быть в кавычках. Переменные так же выбираются нажатием на **+**. На примере выше рассмотренного примера, тело запроса будет выглядеть так:
{% hint style="info" %} Не забывайте про кавычки при использовании **JSON**, даже при использовании переменных. {% endhint %} ### Статус коды Можно указать статус коды, на которые агент будет реагировать. По умолчанию ставится код 200, т.е. код успешного возврата. В случае не успеха, агент получит текст, написанный в поле "Сообщение об ошибке" из настроек действия. Можно убрать отбор на статус коды - и тогда он будет видеть все статусы и все ошибки, которые ему возвращаются и выдавать их клиенту. ### Правила ответа агенту
Поскольку, как мы говорили ранее, мы можем передавать последовательность шагов, в том числе в виде веб-хуков за один раз, то есть настройка, которая определяет, а что мы передадим агенту в ответ: * **Все** - передадим все ответы с каждого шага * **Только первый** - только ответ от первого шага * **Только последний** - только ответ с последнего шага По умолчанию, ставится ответ с последнего шага, что кажется логичным. Хотя, конечно, бывают сценарии в которых мы можем передать информацию с первого шага и дальше выполнить ряд служебных действий, ответ от которых мы не передаем клиенту, например, когда мы просто оповещаем сторонние системы о каком-то триггере. ### Пропуск шага Эти настройки актуальны в ситуациях, когда в действии **настроено несколько шагов**, при этом инструкции в самом агенте достаточно объёмные, поэтому выносить шаг в отдельное действие некорректно. В ситуации когда шагов более, чем 2-3, может возникнуть проблема с тем, что, например, CRM очень долго создает лида, в то время, как бот обрабатывает быстрее. Поэтому выставлять задержку длиной в то время, которое создаётся лид — плохой вариант, так как задержка может оказаться впоследствии длиннее, а также менедже отдела продаж должен среагировать быстрее, чтобы клиент не ждал так долго.
* **Прервать выполнение действия при успешном выполнении шага** — если шаг с таким флагом завершился без ошибки - завершаем действие как успешное. * **Пропускать шаг при ошибке** — если шаг с таким флагом завершился с ошибкой - переходим к следующему. Если для дальнейших шагов нужна переменная которую должен был заполнить этот шаг - сразу ошибка в шаге. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.suvvy.ai/ru/deistviya/veb-khuki.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.