#Диагностика проблем бот-платформы

Если бот не отвечает на сообщения, начните с разделов ниже. Каждый сценарий — отдельный набор проверок с готовыми curl-командами и эталонными ответами от Вайбкод.

#Сценарии диагностики

#События не приходят

Симптом: пользователь пишет боту в чате Битрикс24, бот не отвечает, GET /v1/bots/:botId/events возвращает events: [].

#Чек-лист по порядку

  1. Бот зарегистрирован и активен. GET /v1/bots/:botId возвращает success: true с полями bot.id, bot.code, bot.eventMode. Если 404 — бот не зарегистрирован, выполните POST /v1/bots.
  2. eventMode: "fetch". Проверяется в ответе шага 1. Если webhook — события через polling не приходят, бот пушит их на webhookUrl.
  3. Тип бота соответствует сценарию. Бот типа bot получает только сообщения с @упоминанием и личные сообщения. Для приёма всех сообщений в чате нужен тип personal или supervisor — указывается при регистрации в поле type и не меняется потом. Если ожидаете все сообщения, а тип bot, события придут только при @упоминании.
  4. Бот добавлен в чат. Бот получает события только из чатов, где он состоит. Для личного диалога это происходит при первом обращении пользователя к боту. Для группового чата бота нужно добавить явно через POST /v1/bots/:botId/chats/:dialogId/users.
  5. Пользователь пишет именно этому боту. Если на портале есть несколько ботов, проверьте code бота, к которому идёт обращение в чате, и сравните с code в ответе GET /v1/bots/:botId. Сообщения другому боту в очередь этого бота не попадут.
  6. После 5+ пустых опросов проверьте поле hint в ответе GET /v1/bots/:botId/events. Платформа добавляет диагностическую подсказку, если очередь пуста подряд.
  7. Перепривяжите подписку на события. Если бот активен (в чаты приходят сообщения), но очередь пуста и появилось поле hint, вызовите `POST /v1/bots/:botId/resubscribe`. Перепривязка восстанавливает доставку и сохраняет привязки открытых линий и приветственного бота, в отличие от повторной регистрации через POST /v1/bots.

Если все 7 пунктов пройдены, а очередь по-прежнему пуста — это значит, что портал Битрикс24 не направляет события боту. Соберите данные по разделу Куда обратиться и отправьте тикет.

#TOKEN_MISSING при ключе авторизации

Симптом:

JSON 
{ "success": false, "error": { "code": "TOKEN_MISSING", "message": "API key has no tokens configured." } }

#Причина

Ключ vibe_app_… отправлен без заголовка Authorization: Bearer <session_token>. Ключ авторизации работает в паре с токеном пользовательской сессии — без Bearer у запроса нет контекста, от чьего имени обращаться к Битрикс24.

#Решение

Личный ключ vibe_api_… — Bearer не нужен:

Terminal 
curl https://vibecode.bitrix24.tech/v1/bots/42/events \
  -H "X-Api-Key: YOUR_API_KEY"

Ключ авторизации vibe_app_… — обязательно с Bearer:

Terminal 
curl https://vibecode.bitrix24.tech/v1/bots/42/events \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

Получение USER_SESSION_TOKEN для OAuth-приложения — см. Ключи и авторизация.

#Пустые events подряд

Симптом: ответ корректный, ошибок нет, но events: [], nextOffset === storedOffset, persisted: false.

#Что значат поля ответа

  • persisted: false — курсор lastOffset в базе Вайбкод не сдвинулся, потому что Битрикс24 не отдал ни одного события.
  • nextOffset === storedOffset — нечего обрабатывать.
  • hint появляется после 5+ пустых опросов подряд — диагностическая подсказка.

#Это нормально, если

  • бот только что зарегистрирован — никто ещё не писал
  • очередь пуста — клиенты прочитали все сообщения
  • между опросами нет активности в чатах с ботом.

#Когда нужно перейти к диагностике

Если выполняется хотя бы одно условие — возвращайтесь к разделу События не приходят:

  • в чате есть непрочитанные сообщения боту
  • прошло больше минуты с момента отправки сообщения
  • появилось поле hint.

#BITRIX_ERROR: User is not subscribed

Симптом: GET /v1/bots/:botId/events?withUserEvents=true отдаёт 502 с этим сообщением.

#Причина

User-события (типы ONIMV2* — изменения в чатах, реакции пользователей) требуют отдельной подписки. Без подписки параметр withUserEvents=true не активирует доставку.

#Решение

Подписаться один раз перед использованием withUserEvents=true. Полный порядок настройки и список событий — в разделе User-события.

После подписки GET /v1/bots/:botId/events?withUserEvents=true начинает отдавать user-события вместе с bot-событиями в одном массиве.

#INTERNAL_ERROR при опросе событий

Симптом:

JSON 
{ "success": false, "error": { "code": "INTERNAL_ERROR", "message": "Internal server error" } }

#Что делать

  1. Не повторять запрос сразу. Частые повторы без паузы могут продлить состояние ошибки и сами стать причиной перегрузки.
  2. Использовать растущую паузу между попытками — старт 5 секунд, удвоение на каждой следующей неудаче, потолок 60 секунд. После успешного ответа интервал сбрасывается к рабочему значению (2-5 секунд между опросами).
  3. Не сбрасывать offset. Сохранённый курсор не пострадал — продолжайте с того же значения. Сброс приведёт к повторной обработке уже доставленных событий.
  4. Если ошибка не уходит после нескольких циклов задержки — отправьте тикет в поддержку с botId, временем первого появления, последним успешным nextOffset и интервалом между попытками. Не наращивайте частоту запросов «на всякий случай» — это ухудшит ситуацию.

#Готовый шаблон с растущей паузой

javascript 
const BOT_ID = 42
const API_KEY = 'YOUR_API_KEY'
const BASE = 'https://vibecode.bitrix24.tech/v1'

let backoffMs = 5000

while (true) {
  try {
    const res = await fetch(`${BASE}/bots/${BOT_ID}/events`, {
      headers: { 'X-Api-Key': API_KEY },
    })
    const json = await res.json()

    if (!json.success && json.error?.code === 'INTERNAL_ERROR') {
      console.warn(`INTERNAL_ERROR — пауза ${backoffMs} мс`)
      await new Promise(r => setTimeout(r, backoffMs))
      backoffMs = Math.min(backoffMs * 2, 60000)
      continue
    }

    backoffMs = 5000
    for (const event of json.data?.events ?? []) {
      // обработка события
    }
  } catch {
    await new Promise(r => setTimeout(r, backoffMs))
    backoffMs = Math.min(backoffMs * 2, 60000)
  }

  await new Promise(r => setTimeout(r, 3000))
}

#Бот отключён (BOT_DISABLED)

Симптом:

JSON 
{ "success": false, "error": { "code": "BOT_DISABLED", "message": "Bot is disabled (reason: …)" } }

HTTP-код — 410 Gone. Затронуты все эндпоинты бота: события, сообщения, чаты, команды, обновление, удаление.

#Возможные причины (поле `reason`)

  • AUTH_FAILURES — 10 подряд 401 INVALID_CREDENTIALS от Битрикс24. Платформа защищает портал от шумных запросов и автоматически отключает бота со сломанной авторизацией.
  • PORTAL_DELETED — портал Битрикс24 удалён или подтверждён недоступным.

#Решение

AUTH_FAILURES — вызовите `POST /v1/bots/:botId/reauth`. Проверка подтверждает доступ бота, при необходимости обновляет токен и снимает отключение. Если в ответ пришёл 410 REAUTH_REQUIRED — доступ восстановить автоматически нельзя, ключ нужно авторизовать заново через OAuth или пересоздать личный ключ.

Сбросить только счётчик ошибок авторизации, без проверки доступа, можно через PATCH /v1/bots/:botId с body {"disabled": false}:

Terminal 
curl -X PATCH https://vibecode.bitrix24.tech/v1/bots/42 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"disabled": false}'

PORTAL_DELETED — бот восстанавливается автоматически, когда портал возвращается к статусу ACTIVE. Принудительное включение через PATCH для этой причины не требуется.

PATCH … {"disabled": true} запрещён — вернётся 400 DISABLE_NOT_ALLOWED. Отключение системное, для удаления используйте DELETE /v1/bots/:botId.

#Отличия fetch от webhook

Вайбкод поддерживает два режима доставки событий: fetch (по умолчанию) и webhook. Режим задаётся полем eventMode при регистрации бота и не меняется после.

fetch webhook
Как работает Клиент сам запрашивает события через GET /v1/bots/:botId/events Битрикс24 пушит события HTTP POST на webhookUrl
Типы значений Нативные: number, boolean, null Всё приходит строками ("1", "true", "") — следствие сериализации тела на стороне Битрикс24
Объект bot в событии Без поля auth Содержит auth с OAuth-токенами портала
Тайм-аут Нет (long-poll) 10 секунд — Битрикс24 ждёт 200 от вашего сервера и закрывает соединение
Повторная доставка Серверное хранение offset — пропустить событие нельзя Нет автоматических повторов при таймауте или 5xx ответе
Когда выбирать Большинство сценариев, особенно AI-агенты Когда нужно минимальное время реакции и есть публично доступный сервер

При eventMode: "webhook" GET /v1/bots/:botId/events всегда возвращает пустой массив — события доставляются напрямую на webhookUrl, в polling они не попадают.

#Стикеры

Боты не могут отправлять стикеры пользователям. Это ограничение Bot API v2 Битрикс24.

Боты могут получать стикеры: если пользователь отправил стикер, событие ONIMBOTV2MESSAGEADD придёт, но поле message.text будет пустым. Реагировать на стикеры можно, отправив текстовое сообщение или вложение через POST /v1/bots/:botId/messages.

#Куда обратиться

Если ни один из разделов выше не помог — оставьте тикет в разделе Обратная связь. К тикету приложите:

  • botId (число)
  • ответ GET /v1/bots/:botId целиком
  • последние 3 ответа GET /v1/bots/:botId/events с полями nextOffset, storedOffset, persisted, hint
  • время первого появления симптома (UTC)
  • тип ключа (vibe_api_… или vibe_app_…) — без самого ключа
  • скриншот чата с непрочитанным сообщением, если есть.

#Смотрите также