Вебхук для ИИ-агента: запрос во внешнюю систему

Клиент спрашивает, остался ли нужный размер на складе. Остатки лежат в своей учётной программе, для которой готовой кнопки подключения в Савви нет и не будет: система собрана под конкретный бизнес и больше нигде не встречается. Проверить остаток на месте, прямо в переписке, получится, если агент сам умеет постучаться в эту программу и получить ответ.

Что такое вебхук в действии агента и когда он нужен

Вебхук — тип шага в действии агента, который отправляет HTTP-запрос на указанный вами адрес: с методом GET или POST, заголовками и телом запроса, если метод их подразумевает.

Ходит запрос в обе стороны: агент передаёт наружу то, что узнал у клиента, и получает назад данные или подтверждение, которое тут же пересказывает человеку. Нужен такой шаг там, где у Савви нет отдельной кнопки подключения к сервису: собственная учётная система, внутренний склад, самописный личный кабинет, любая программа, о существовании которой платформа знать не обязана. Готовые интеграции вроде CRM или таблиц закрывают частые случаи, а вебхук закрывает то, что осталось, тем же самым способом.

Как настроить действие «Вебхук»

Настройка состоит из общей части действия и отдельной формы самого шага.

Разница между вторым пунктом и остальными и есть главная мысль всей настройки: одни значения плывут вместе с диалогом, другие стоят на месте.

Переменные действия и константы действия: где проходит граница

Переменные действия — это то, что агент собирает у клиента заново в каждом разговоре: номер заказа, город доставки, артикул товара, который спросили на складе. Каждый диалог наполняет их своими значениями.

Константы действия устроены иначе: значение задаётся один раз в настройке и остаётся неизменным для любого диалога любого клиента. Типичный пример — токен доступа к вашему сервису или логин для авторизации: он не должен зависеть от того, кто сейчас пишет в чат, и не должен каждый раз запрашиваться у человека, который к нему вообще отношения не имеет.

Переменные подставляются и в URL

Обычный случай — параметр после знака вопроса: адрес вида https://ваш-сервис.ru/sklad?артикул=ART-4521, где значение артикула агент подставляет из переменной, собранной в диалоге.

Есть и второй вариант, менее очевидный: переменную вставляют прямо в тело URL, там, где значение не выглядит как параметр запроса. Платформа заменяет обозначение переменной на реальное значение перед отправкой, поэтому адрес вида https://ваш-сервис.ru/sklad/{artikul}/ostatok уходит наружу уже с настоящим артикулом вместо обозначения. Тот же механизм работает и в остальных действиях: переменные подставляются в аргументы других шагов, в текст фоллоу-апов и в условия отбора диалогов для рассылок.

Что происходит при ошибке или таймауте ответа

Если внешний сервис не ответил кодом из ожидаемого диапазона, статус приравнивается к ошибке. По умолчанию платформа ждёт код 200, но фильтр по кодам можно убрать вовсе, и тогда агент увидит любой статус, какой бы сервис ни вернул.

На случай ошибки заранее задаётся текст в поле «Сообщение об ошибке» действия: именно его получит агент вместо ответа сервиса, и это заменяет собой любую догадку модели о том, что могло произойти. Отдельными флагами включаются уведомление менеджеру и полная остановка диалога, если ошибка критична для дальнейшего разговора. Если внешняя система из-за собственной автоматизации отвечает не сразу, перед вызовом можно поставить задержку, вместо того чтобы агент повторял запрос раньше времени.

Здесь же работает более общая страховка: флаг «Реагировать на срабатывания и ошибки» в контроле поведения не даёт агенту подтвердить клиенту то, чего он на самом деле не сделал, например записи на услугу без реального вызова функции записи. Для вебхука это правило особенно уместно: ошибка сервиса не должна превращаться в вежливое «всё готово».

Лимит в десять вызовов общий для платформы и относится к любой функции без исключений. Сценарий, где агент дёргает один и тот же вебхук на каждую уточняющую реплику клиента, упирается в этот потолок быстрее, чем кажется на старте: разумнее один вызов на один точный вопрос, а не серию проверок вдогонку.

Как проверить, что вебхук реально сработал

Журнал диалогов и продвинутый режим в разделе «Чаты» показывают вызов между строк переписки: название функции, переданные аргументы и статус выполнения. Там же видно, что именно вернул внешний сервис, текстом или структурированным ответом, и совпадает ли это с тем, что агент затем сказал клиенту.

Экспорт диалога сохраняет ту же картину отдельным файлом: полезно, когда вебхук ведёт себя странно сразу в нескольких разговорах и нужно сравнить аргументы между вызовами. Частая находка на этом шаге — параметр, переданный пустым или не тем типом: сама функция вызвалась исправно, а до неё просто не дошло значение из диалога.

Отличие от персонального канала (API) здесь принципиальное: там ваша система сама присылает сообщение агенту, это входящее направление. Вебхук в действии устроен обратным движением: инициатива остаётся у агента, и посреди разговора он сам обращается наружу за конкретным ответом. Общий разбор того, из каких полей состоит любое действие агента и как он выбирает, какую функцию вызвать, есть в статье про действия ИИ-агента: вебхук устроен по тем же правилам, просто в роли шага выступает HTTP-запрос. А если нужен готовый пример со своей учётной системой, у которой уже есть опыт похожего подключения, посмотрите статью про интеграцию с 1С: там расписана авторизация и передача аргументов на конкретном случае. Полный список настроек шага, включая коды статусов и правила ответа при нескольких шагах в одном действии, — в руководстве Савви.

Разложите свою систему на вопросы, которые чаще всего требуют доступа к ней

Разложите обращения клиентов, которые сейчас обрабатывает человек, на конкретные вопросы к вашей системе: остаток на складе, статус заявки, действующий тариф. Каждый такой вопрос — кандидат на отдельный вебхук с одной переменной и одним понятным ответом.

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

Частые вопросы