Триггер «Webhook»
Триггер «Входящий webhook» запускает сценарий по запросу из вашей системы: CRM, сайта, склада или службы доставки. Бот стартует не от сообщения клиента, а от события снаружи — и пишет клиенту первым. Работает во всех каналах ботов.
Как устроен запрос
| Что | Значение |
|---|---|
| Адрес | POST https://api.apx.chat/api/chatbot-builder/public/webhook/<ID сценария> — точный адрес показан в карточке триггера. |
| Секрет | Заголовок x-webhook-secret. Секрет создаёт кнопка «Сгенерировать секрет» в карточке триггера — она доступна владельцу и администраторам. |
| Тело | JSON с идентификатором собеседника в поле external_id. Имя поля можно поменять в настройке «Поле идентификатора подписчика». |
Сценарий должен быть опубликован. Собеседник должен уже писать в канал сценария: бот продолжает существующий диалог, а не начинает новый. Сценарий запускается в открытом диалоге клиента на этом канале, а если открытого нет — в последнем. Диалоги, снятые из подписчиков или в которых клиент заблокировал бота, пропускаются.
Идентификатор собеседника по каналам
| Канал | Что передать |
|---|---|
| Telegram, VK, MAX | id пользователя в мессенджере |
| Сайт | uuid клиента в APX |
| Avito | id чата Avito (например, u2i-…) или числовой id покупателя |
Поле может быть вложенным — например, client.id.
Ответ
Ответ всегда с кодом 200, итог — в поле data: {"ok": true, "reason": "started"}, если сценарий запущен. Если нет, ok равно false, а reason объясняет причину:
invalid_secret— неверный секрет;scenario_not_publishedилиno_webhook_trigger— сценарий не опубликован или в нём нет этого триггера;no_external_id,invalid_external_id,subscriber_not_found,chat_not_found— в теле нет идентификатора, у него неверный формат для канала, такого собеседника нет или у него нет диалога в этом канале;bot_blocked— клиент заблокировал бота;removed_from_subscribers— диалог клиента снят из подписчиков;session_already_active— у клиента уже идёт сценарий, второй не запускается.
Данные из запроса
В переменные сценария попадают только поля, для которых задано сопоставление «поле запроса → переменная». В карточке триггера его нет: сопоставление умеет задать AI-помощник конструктора, и оно уже есть в шаблоне «Статус заказа по webhook». Без сопоставления сценарий запускается, но остальные поля запроса не сохраняются.
Как настроить
Добавьте триггер
В стартовой ноде нажмите «Добавить триггер» и выберите «Входящий webhook».
Сгенерируйте секрет
Нажмите «Сгенерировать секрет» (владелец или администратор) и сохраните его: он понадобится вашей системе.
Опубликуйте сценарий
Запросы к черновику не запускают бота.Настройте вашу систему
Пусть она отправляет POST на адрес из карточки триггера с заголовком
x-webhook-secretи JSON с идентификатором собеседника.
Когда применять / Пример
- Статус заказа. Склад меняет статус — бот присылает клиенту «Заказ отправлен» с трек-номером.
- Событие в CRM. Сделка перешла на этап «Счёт выставлен» — бот напоминает клиенту об оплате.
Шаблон «Статус заказа по webhook» для MAX принимает order_id, status и tracking, складывает их в переменные и через Условие отправляет клиенту нужное сообщение.