Ошибки при интеграции чат-ботов: как найти и исправить
Бот зарегистрирован, подключён к линии, но не отвечает. Или отвечает не на все сообщения. Или конфликтует с AI-агентом. Или вообще не регистрируется с непонятной ошибкой. Интеграция чат-ботов в Битрикс24 — это не «настроил и забыл». Это система, где сбой на любом уровне (регистрация, события, доступность операторов, права) приводит к тому, что клиент остаётся без ответа.
В 2026 году Битрикс24 обновил API imbot.v2, добавив новые коды ошибок и изменив некоторые параметры. Например, с 6 августа 2026 года imbot.v2.Bot.register будет отклонять botToken длиннее 40 символов с ошибкой BOT_TOKEN_INVALID_LENGTH, а поле bot.appId удалено из всех ответов и событий. Появились новые коды ошибок: BOT_TOKEN_NOT_SPECIFIED, BOT_OWNERSHIP_ERROR, BOT_LIMIT_EXCEEDED. Если интеграция написана под старую версию, она может перестать работать без видимых причин.
В этой статье — полное руководство по диагностике ошибок при интеграции чат-ботов в Битрикс24: почему бот не видит сообщения, не отвечает в линии, конфликтует с AI-агентом, какие ошибки API возникают при регистрации, как проверить доступность операторов и что делать в коробочной версии. С чек-листом и конкретными решениями. Если нужна настройка чат-ботов под вашу команду — поможем.
Ошибка 1: Бот не отвечает в открытой линии
Симптом: Клиент пишет в Telegram, WhatsApp или на сайт. Сообщение появляется в Битрикс24, но бот молчит. Оператор тоже не получает диалог. Клиент ждёт.
Причины и решения:
| Причина | Как проверить | Решение |
|---|---|---|
| Бот не добавлен в очередь линии | Откройте настройки линии → вкладка «Очередь». Бот должен быть в списке операторов. | Добавьте бота в очередь. Без этого он не получает сообщения из линии. |
| Линия отключена | В списке линий красный крестик означает, что линия неактивна. | Откройте настройки линии → вкладка «Прочее» → включите «Линия активна». |
| Канал не подключён к линии | В настройках линии на вкладке «Каналы» проверьте, что нужный канал (Telegram, WhatsApp) присутствует и активен. | Подключите канал заново или активируйте его. |
| Ошибка «Канал коммуникаций не настроен» | При отправке сообщения появляется уведомление «Вы не можете отправить сообщение, так как канал коммуникаций не настроен». | Проверьте, что линия активна и подключена к каналу. Красный крестик в списке — признак неактивности. |
💡 Важно
Если бот зарегистрирован, но не добавлен в очередь, он не получит ни одного события из линии. Это самая частая ошибка при первой настройке.
Ошибка 2: События не доходят до бота
Симптом: Бот добавлен в очередь, линия активна, но обработчик событий ONIMBOTV2MESSAGEADD не срабатывает. Бот «не видит» сообщения.
Причины и решения:
- Нет подписки на события. Бот должен быть зарегистрирован с указанием событий, на которые он реагирует. Если в
imbot.v2.Bot.registerне передан список событий (включаяONIMBOTV2MESSAGEADD), бот их не получает; - Неверный eventMode. В параметрах регистрации
eventModeопределяет, как доставляются события: через webhook или через опрос. Если указан webhook, но URL недоступен, события теряются. Если указан опрос, но приложение не опрашивает — тоже; - Ошибка в обработчике. Событие приходит, но обработчик падает с ошибкой. Проверьте логи приложения и логи Битрикс24. В коробочной версии ошибки модуля imbot пишутся в
/bitrix/modules/imbot.log; - Токен истёк или отозван. Если бот был отключён (
BOT_DISABLED), все его эндпоинты возвращают 410 Gone. Восстановление — черезPOST /v1/bots/:botId/reauth.
Для диагностики включите режим отладки в настройках модуля «Чат-боты Битрикс24». В коробочной версии это позволит увидеть, приходят ли события и на каком этапе они теряются.
Ошибка 3: Конфликт бота и AI-агента
Симптом: В линии одновременно работают чат-бот и AI-агент. Ответы становятся непредсказуемыми: бот и агент отвечают одновременно, перебивают друг друга или дублируют сообщения.
Причина: Битрикс24 не позволяет чат-боту и AI-агенту одновременно отвечать в одной открытой линии. Это прямо указано в документации: перед запуском AI-агента чат-бот должен быть отключён в настройках линии.
Решение:
- Проверьте, какие боты и агенты подключены к линии. Откройте настройки линии и посмотрите список активных ботов;
- Отключите одного из них. Если вы хотите использовать AI-агента, отключите чат-бота. Если бота — отключите агента;
- Разделите линии. Если нужны оба, создайте отдельные линии для разных сценариев. Например, одна линия с ботом для квалификации, другая с AI-агентом для консультаций.
Эта ошибка часто возникает при смене «помощника»: компания включает нового агента, но забывает отключить старого бота. Ответы клиенту становятся хаотичными, и это подрывает доверие.
Ошибка 4: Ошибки регистрации бота (imbot.v2)
При регистрации бота через imbot.v2.Bot.register могут возникать ошибки. Вот основные коды и что они означают.
| Код ошибки | Причина | Решение |
|---|---|---|
BOT_TOKEN_NOT_SPECIFIED | Не передан botToken при авторизации через webhook. | Укажите botToken в параметрах запроса. Если используете webhook, токен обязателен. |
BOT_CODE_REQUIRED | Не указан код бота (fields.code). | Добавьте уникальный код бота в параметры регистрации. |
BOT_CODE_ALREADY_TAKEN | Код бота уже занят другим приложением. | Выберите другой код. Код должен быть уникальным в рамках портала. |
BOT_OWNERSHIP_ERROR | Бот не принадлежит приложению, которое пытается с ним работать. | Проверьте, что приложение, от имени которого выполняется запрос, является владельцем бота. Если бот создан другим приложением, используйте его токен. |
BOT_LIMIT_EXCEEDED | Превышен лимит ботов на приложение (100 ботов). | Удалите неиспользуемых ботов или создайте новое приложение. |
BOT_INVALID_TYPE | Неверный тип бота. Допустимые значения: bot, network, openline, supervisor, personal. | Укажите корректный тип. Для работы с открытыми линиями обычно используется openline. |
BOT_TOKEN_INVALID_LENGTH | Токен длиннее 40 символов (для ротации через Bot.update). Для регистрации лимит не введён, но для обновления — да. | Используйте токен длиной не более 40 символов при обновлении. |
💡 Важно
Поле bot.appId удалено из всех ответов методов и событий ONIMBOTV2*. Если ваш код читал это поле — он сломается. Используйте result.bot.code для идентификации бота.
Ошибка 5: Бот не отвечает из-за доступности операторов
Симптом: Бот подключён, события приходят, но в некоторых ситуациях он не срабатывает. Например, автоответ не отправляется в нерабочее время или, наоборот, приходит в рабочее.
Причина: Опция «Проверять доступность оператора при распределении обращений» влияет на то, как линия обрабатывает сообщения. Если она включена, система проверяет, есть ли доступные операторы.
- Автоответ не приходит в нерабочее время: кто-то из очереди онлайн или начал рабочий день. Система считает, что линия работает, и не отправляет автоответ;
- Автоответ приходит в рабочее время: все операторы офлайн, на перерыве или не начали рабочий день. Система считает, что линия не работает.
Решение: Определите, что важнее для вашего сценария. Если бот должен отвечать круглосуточно, отключите проверку доступности. Если бот должен срабатывать только когда операторы недоступны, оставьте проверку включённой. Но помните: при включённой проверке чаты могут назначаться офлайн-операторам, и клиент будет ждать ответа, который не придёт.
Также проверьте лимит одновременных чатов на оператора. Если у оператора больше 1000 незакрытых диалогов, новые обращения уходят другим сотрудникам или остаются в очереди.
Ошибка 6: Бот перестал отвечать из-за лимитов приложения
Симптом: Бот работал, но внезапно перестал отвечать. Настройки не менялись, линия активна, но ответов нет.
Причина: Боты из Маркетплейса работают по правилам своих разработчиков. У многих есть лимиты, тарифы и собственные настройки. Если бот перестал отвечать после смены тарифа, окончания пробного периода или исчерпания лимита, причину нужно искать в карточке самого приложения.
Решение:
- Проверьте статус подписки на приложение. Возможно, пробный период закончился или тариф не оплачен;
- Проверьте лимиты. Некоторые приложения ограничивают количество сообщений, диалогов или активных ботов;
- Обратитесь в поддержку разработчика. Если проблема не в настройках портала, скорее всего, дело в самом приложении.
Ошибка 7: Бот не работает в коробочной версии
Симптом: В облачной версии бот работал, а после переезда на коробку перестал. Или бот не работает с самого начала на коробочной версии.
Причина: Коробочная версия требует дополнительных настроек сервера для работы открытых линий и ботов.
Что проверить:
- Доступность
/pub/imconnector/из интернета. Открытые линии должны быть доступны снаружи для получения сообщений из каналов; - Доступ к
/pub/imbot.phpбез авторизации. Для коннектора «Битрикс24.Нетворк» это обязательное условие; - Модуль «Чат-боты Битрикс24 (imbot)». Убедитесь, что модуль установлен и активен;
- Режим отладки. Включите отладку в настройках модуля и проверьте лог
/bitrix/modules/imbot.log; - Лицензия. Открытые линии и боты требуют активной коммерческой лицензии. Если лицензия истекла, функции могут быть недоступны.
Если после проверки этих пунктов бот всё равно не работает, проблема может быть в SSL-сертификате, настройках firewall или DNS. Эти вопросы решает системный администратор.
Чек-лист диагностики
Регистрация и события
- Бот зарегистрирован без ошибок
- Указан
botToken(если webhook) - Список событий включает
ONIMBOTV2MESSAGEADD -
eventModeсоответствует способу доставки
Линия и канал
- Линия активна (нет красного крестика)
- Канал подключён к линии
- Бот добавлен в очередь
- Нет конфликта с AI-агентом
Доступность и лимиты
- Проверка доступности настроена осознанно
- Лимит чатов на оператора не исчерпан
- Приложение не исчерпало лимиты
- Токен не истёк
Коробочная версия
-
/pub/imconnector/доступен из интернета -
/pub/imbot.phpдоступен без авторизации - Модуль imbot установлен
- Лицензия активна
Наши рекомендации
Что вы получаете, заказывая аудит у нас
- Проверку регистрации бота — все ли параметры корректны;
- Проверку событий — доходят ли они до обработчика;
- Проверку очереди и линии — нет ли конфликтов;
- Проверку доступности — правильно ли настроена;
- Диагностику коробочной версии — если нужно;
- Исправление ошибок — с конкретными решениями;
- Обучение — как диагностировать самостоятельно.
📌 Итоговый вывод
Ошибки при интеграции чат-ботов можно исправить, если знать, где искать.
Что нужно знать:
- Бот не отвечает: проверьте очередь, активность линии, подключение канала;
- События не доходят: проверьте подписку, eventMode, обработчик, токен;
- Конфликт с AI-агентом: бот и агент не могут работать в одной линии одновременно;
- Ошибки регистрации:
BOT_TOKEN_NOT_SPECIFIED,BOT_CODE_ALREADY_TAKEN,BOT_OWNERSHIP_ERROR,BOT_LIMIT_EXCEEDED; - Доступность операторов: проверка доступности влияет на автоответы и распределение;
- Лимиты приложений: боты из Маркетплейса могут перестать работать из-за тарифов;
- Коробочная версия: проверьте
/pub/imconnector/,/pub/imbot.php, модуль imbot, лицензию; - Чек-лист: регистрация, события, линия, доступность, лимиты, коробка.
Также рекомендуем: Интеграция с чат-ботами, Открытые линии, Квалификация лидов, все статьи.