AI Webhooks API: подключите агентов к любой системе

Что такое Webhooks API и кому он нужен

Webhooks API — это канал в MyChatBot, который вы подключаете самостоятельно. Если ваша платформа умеет отправлять и принимать HTTP-запросы, ваш AI-агент может общаться с её пользователями: платформа передаёт каждое сообщение пользователя, а ответ агента возвращается на URL, которым управляете вы.

Встроенные каналы, например WhatsApp, Telegram или Website Widget, подключаются прямо в приложении. Webhooks API закрывает всё остальное — системы, которые MyChatBot не поддерживает нативно.

Он хорошо подходит для:

• собственных чат-приложений и чата внутри мобильного приложения;
• существующей системы поддержки клиентов, которую вы хотите сохранить;
• IoT-устройств с обменом сообщениями;
• любой сторонней платформы без нативного канала MyChatBot.

В вашем продукте пользователям отвечает ассистент, которого вы подключили к этому каналу, — с его инструкциями, знаниями и подключёнными инструментами. Ваши разработчики отвечают за передачу данных, а разговор ведёт MyChatBot.

Как сообщение проходит через MyChatBot

Каждая интеграция держится на трёх значениях: API token, который вы генерируете, Unique page_id, который вы выбираете, и Reply webhook URL — HTTPS-эндпоинт на вашей стороне. Когда всё заполнено, каждое сообщение проходит пять шагов:

1. Пользователь пишет на вашей платформе, а ваш бэкенд отправляет сообщение POST-запросом в формате JSON на входящий webhook URL, указанный на странице Channels. Обязательных полей четыре: client_id, page_id, platform и text.
2. MyChatBot проверяет, что канал включён для этого page_id.
3. Сообщение добавляется в историю разговора пользователя по client_id. Если вы отправили ссылку на аудио, запись сначала расшифровывается в текст.
4. Агент читает разговор и пишет ответ.
5. Ответ приходит на ваш Reply webhook URL как form-encoded запрос с полями text, images, file и audio. Длинный ответ может прийти несколькими частями, поэтому добавляйте их по порядку.

Для каждого пользователя оставляйте client_id неизменным: именно так разговор продолжается, а не начинается заново. Также можно передать необязательные поля client_name и client_avatar и массив attachments со ссылками на файлы или изображения.

Ключевые возможности

Голос в обе стороны

Добавьте ссылку audio во входящее сообщение, и MyChatBot автоматически расшифрует запись, так что агент воспримет её как обычное сообщение. Включите Voice reply settings и выберите голос — тогда ответы будут содержать ссылку на аудио рядом с текстом.

Настройки канала

• Reply Delay (s) добавляет паузу перед ответом: так ответы выглядят естественнее, а серию быстрых сообщений проще обработать вместе.
• Ignore Reactions пропускает реакции, которые иначе запускали бы нежелательные ответы.
• Quick comment reply задаёт необязательный короткий публичный ответ в ветке комментариев, а полный ответ уходит в личные сообщения.

Понятные коды ответа

Входящий webhook возвращает стандартные HTTP-коды: 200 — сообщение принято, 400 — некорректный запрос или не хватает обязательного поля, 401 — API token не совпадает, 500 — при обработке произошла ошибка, и запрос стоит повторить.

Все настройки ассистента

Разговор через Webhooks API ведёт ассистент, которого вы настраиваете на странице Agent configuration, поэтому его инструкции, Knowledge Base и подключённые интеграции работают и здесь. Сохранённые изменения действуют со следующего ответа во всех каналах.

Как это сочетается с другими каналами и интеграциями

Webhooks API — один из каналов на странице Channels, рядом с WhatsApp, Instagram, Telegram, Viber, TikTok, Facebook, Gmail, SMS, Calls и Website Widget. Канал может быть подключён только к одному ассистенту, а каналы можно распределить между несколькими ассистентами.

У MyChatBot есть и другие способы подключить ваши системы:

• Trigger Outreach в Automations: внешняя система отправляет POST на уникальный webhook URL, чтобы создать лид и при необходимости поручить агенту написать клиенту — об обновлении заказа, напоминании о записи или событии в CRM. Можно создать до 20 именованных триггеров в режиме Capture only или Capture and send outreach и передать значение context, которое агент использует в сообщении.
• Интеграции с CRM: KeyCRM, SalesDrive, Bitrix24, Kommo, Zoho, Salesforce, GoHighLevel и HubSpot, чтобы квалифицированные чаты попадали в CRM как лиды или сделки. Посмотрите все интеграции.
• Custom MCP: дополнительные возможности для ассистента через ваш собственный MCP-сервер.
• Триггеры Agents Platform: секретная webhook-ссылка или событие в подключённом приложении запускает рутину или агента.

Когда разговор берёт человек и какие есть ограничения

Правила передачи разговора задаются в Handoff Control на странице Agent configuration и относятся к чатам ассистента:

• Stop word for manual handoff: когда оператор пишет ключевое слово, чат переходит в режим оператора.
• Implicit operator handoff: любое сообщение оператора переключает чат в режим оператора. Выберите этот режим или ключевое слово — вместе они не работают.
• Silent handoff: клиент не получает уведомления о переключении.
• Auto return: если он включён, агент снова включается в чате по умолчанию через 24 часа или через собственный интервал от 1 минуты до 1 недели.

Подробнее о передаче разговора человеку.

Несколько ограничений стоит учесть заранее:

• page_id в каждом сообщении должен точно совпадать с Unique page_id канала, а сам канал должен быть включён. Иначе сообщение игнорируется.
• Когда ассистент на паузе — вручную или по расписанию Work Hours, — он не отвечает в своих каналах. Сообщения, пришедшие в это время, остаются без ответа, но видны команде, и позже ассистент на них не отвечает.
• Если на балансе аккаунта закончились средства, ассистенты отключаются автоматически. После пополнения проверьте переключатель статуса.
• Ответы, приходящие на Reply webhook URL, показывает пользователям ваша платформа, а не MyChatBot.

Как настроить

1. Откройте Channels и выберите агента, которого хотите подключить.
2. Выберите Webhooks API в списке каналов.
3. Заполните API token, Unique page_id и Reply webhook URL.
4. Включите Connect agent to this channel и задайте Reply Delay (s).
5. Нажмите Connect Webhooks API и скопируйте входящий webhook URL со страницы Channels.
6. Отправьте тестовое сообщение с client_id, page_id, platform и text и убедитесь, что ответ пришёл на ваш эндпоинт.

Ответы не приходят? Чаще всего причина в несовпадении page_id или в выключенном канале. Код 401 означает, что токен в запросе не совпадает с API token на экране канала. Чтобы позже отключить канал, откройте тот же экран и нажмите Revoke.

Перед запуском протестируйте ассистента в приватном чате и включите переключатель канала только после проверки настроек. Тарифы указаны на странице цен.