[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"docs-bots\u002Ftroubleshooting":3,"docs-tabs-bots\u002Ftroubleshooting":6},{"content":4,"lastmod":5},"\n# Диагностика проблем бот-платформы\n\nЕсли бот не отвечает на сообщения, начните с разделов ниже. Каждый сценарий — отдельный набор проверок с готовыми curl-командами и эталонными ответами от Вайбкод.\n\n## Сценарии диагностики\n\n- [События не приходят](#события-не-приходят) — пользователь пишет боту, но `GET \u002Fv1\u002Fbots\u002F:botId\u002Fevents` возвращает пустой массив\n- [TOKEN_MISSING при ключе авторизации](#token_missing-при-ключе-авторизации) — `vibe_app_…` отправлен без `Authorization: Bearer`\n- [Пустые events подряд](#пустые-events-подряд) — `success: true`, но `nextOffset` не двигается\n- [BITRIX_ERROR: User is not subscribed](#bitrix_error-user-is-not-subscribed) — `withUserEvents=true` без предварительной подписки\n- [INTERNAL_ERROR при опросе событий](#internal_error-при-опросе-событий) — временная ошибка прокси и схема повтора с растущей паузой\n- [Бот отключён (BOT_DISABLED)](#бот-отключён-bot_disabled) — автоматическое отключение по `AUTH_FAILURES` или `PORTAL_DELETED`\n- [Отличия fetch от webhook](#отличия-fetch-от-webhook) — разница форматов данных и поведения при доставке событий\n- [Стикеры](#стикеры) — ограничение платформы\n- [Куда обратиться](#куда-обратиться) — что приложить к тикету в поддержку\n\n---\n\n## События не приходят\n\nСимптом: пользователь пишет боту в чате Битрикс24, бот не отвечает, `GET \u002Fv1\u002Fbots\u002F:botId\u002Fevents` возвращает `events: []`.\n\n### Чек-лист по порядку\n\n1. **Бот зарегистрирован и активен.** `GET \u002Fv1\u002Fbots\u002F:botId` возвращает `success: true` с полями `bot.id`, `bot.code`, `bot.eventMode`. Если 404 — бот не зарегистрирован, выполните `POST \u002Fv1\u002Fbots`.\n2. **`eventMode: \"fetch\"`.** Проверяется в ответе шага 1. Если `webhook` — события через polling не приходят, бот отправляет их на `webhookUrl`.\n3. **Тип бота соответствует сценарию.** Бот типа `bot` получает только сообщения с `@упоминанием` и личные сообщения. Для приёма всех сообщений в чате нужен тип `personal` или `supervisor` — указывается при регистрации в поле `type` и не меняется потом. Если ожидаете все сообщения, а тип `bot`, события придут только при `@упоминании`.\n4. **Бот добавлен в чат.** Бот получает события только из чатов, где он состоит. Для личного диалога это происходит при первом обращении пользователя к боту. Для группового чата бота нужно добавить явно через `POST \u002Fv1\u002Fbots\u002F:botId\u002Fchats\u002F:dialogId\u002Fusers`.\n5. **Пользователь пишет именно этому боту.** Если на портале есть несколько ботов, проверьте `code` бота, к которому идёт обращение в чате, и сравните с `code` в ответе `GET \u002Fv1\u002Fbots\u002F:botId`. Сообщения другому боту в очередь этого бота не попадут.\n6. **После 5+ пустых опросов проверьте поле `hint`** в ответе `GET \u002Fv1\u002Fbots\u002F:botId\u002Fevents`. Платформа добавляет диагностическую подсказку, если очередь пуста подряд.\n7. **Перепривяжите подписку на события.** Если бот активен (в чаты приходят сообщения), но очередь пуста и появилось поле `hint`, вызовите [`POST \u002Fv1\u002Fbots\u002F:botId\u002Fresubscribe`](\u002Fdocs\u002Fbots\u002Fmanagement\u002Fresubscribe). Перепривязка восстанавливает доставку и сохраняет привязки открытых линий и приветственного бота, в отличие от повторной регистрации через `POST \u002Fv1\u002Fbots`.\n\nЕсли все 7 пунктов пройдены, а очередь по-прежнему пуста — это значит, что портал Битрикс24 не направляет события боту. Соберите данные по разделу [Куда обратиться](#куда-обратиться) и отправьте тикет.\n\n---\n\n## TOKEN_MISSING при ключе авторизации\n\nСимптом:\n\n```json\n{ \"success\": false, \"error\": { \"code\": \"TOKEN_MISSING\", \"message\": \"API key has no tokens configured.\" } }\n```\n\n### Причина\n\nКлюч `vibe_app_…` отправлен без заголовка `Authorization: Bearer \u003Csession_token>`. Ключ авторизации работает в паре с токеном пользовательской сессии — без Bearer у запроса нет контекста, от чьего имени обращаться к Битрикс24.\n\n### Решение\n\nЛичный ключ `vibe_api_…` — Bearer не нужен:\n\n```bash\ncurl https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fbots\u002F42\u002Fevents \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\nКлюч авторизации `vibe_app_…` — обязательно с Bearer:\n\n```bash\ncurl https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fbots\u002F42\u002Fevents \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\nПолучение `USER_SESSION_TOKEN` для OAuth-приложения — см. [Ключи и авторизация](\u002Fdocs\u002Fkeys-auth).\n\nЧастый источник этой ошибки — обработчик события портала, который вызывает V1 API в ответ на событие. У обработчика нет пользовательской сессии, поэтому ключ `vibe_app_` там не работает — используйте персональный ключ `vibe_api_`. Подробнее — [Обработчик на стороне приложения](\u002Fdocs\u002Finfra\u002Fevent-subscriptions\u002Fhandler).\n\n---\n\n## Пустые events подряд\n\nСимптом: ответ корректный, ошибок нет, но `events: []`, `nextOffset === storedOffset`, `persisted: false`.\n\n### Что значат поля ответа\n\n- `persisted: false` — курсор `lastOffset` в базе Вайбкод не сдвинулся, потому что Битрикс24 не отдал ни одного события.\n- `nextOffset === storedOffset` — нечего обрабатывать.\n- `hint` появляется после 5+ пустых опросов подряд — диагностическая подсказка.\n\n### Это нормально, если\n\n- бот только что зарегистрирован — никто ещё не писал\n- очередь пуста — клиенты прочитали все сообщения\n- между опросами нет активности в чатах с ботом.\n\n### Когда нужно перейти к диагностике\n\nЕсли выполняется хотя бы одно условие — возвращайтесь к разделу [События не приходят](#события-не-приходят):\n\n- в чате есть непрочитанные сообщения боту\n- прошло больше минуты с момента отправки сообщения\n- появилось поле `hint`.\n\n---\n\n## BITRIX_ERROR: User is not subscribed\n\nСимптом: `GET \u002Fv1\u002Fbots\u002F:botId\u002Fevents?withUserEvents=true` отдаёт 502 с этим сообщением.\n\n### Причина\n\nUser-события (типы `ONIMV2*` — изменения в чатах, реакции пользователей) требуют отдельной подписки. Без подписки параметр `withUserEvents=true` не активирует доставку.\n\n### Решение\n\nПодписаться один раз перед использованием `withUserEvents=true`. Полный порядок настройки и список событий — в разделе [User-события](\u002Fdocs\u002Fbots\u002Fevents\u002Fuser-events).\n\nПосле подписки `GET \u002Fv1\u002Fbots\u002F:botId\u002Fevents?withUserEvents=true` начинает отдавать user-события вместе с bot-событиями в одном массиве.\n\n---\n\n## INTERNAL_ERROR при опросе событий\n\nСимптом:\n\n```json\n{ \"success\": false, \"error\": { \"code\": \"INTERNAL_ERROR\", \"message\": \"Internal server error\" } }\n```\n\n### Что делать\n\n1. **Не повторять запрос сразу.** Частые повторы без паузы могут продлить состояние ошибки и сами стать причиной перегрузки.\n2. **Использовать растущую паузу между попытками** — старт 5 секунд, удвоение на каждой следующей неудаче, потолок 60 секунд. После успешного ответа интервал сбрасывается к рабочему значению (2-5 секунд между опросами).\n3. **Не сбрасывать `offset`.** Сохранённый курсор не пострадал — продолжайте с того же значения. Сброс приведёт к повторной обработке уже доставленных событий.\n4. **Если ошибка не уходит после нескольких циклов задержки** — отправьте тикет в поддержку с `botId`, временем первого появления, последним успешным `nextOffset` и интервалом между попытками. Не наращивайте частоту запросов «на всякий случай» — это ухудшит ситуацию.\n\n### Готовый шаблон с растущей паузой\n\n```javascript\nconst BOT_ID = 42\nconst API_KEY = 'YOUR_API_KEY'\nconst BASE = 'https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1'\n\nlet backoffMs = 5000\n\nwhile (true) {\n  try {\n    const res = await fetch(`${BASE}\u002Fbots\u002F${BOT_ID}\u002Fevents`, {\n      headers: { 'X-Api-Key': API_KEY },\n    })\n    const json = await res.json()\n\n    if (!json.success && json.error?.code === 'INTERNAL_ERROR') {\n      console.warn(`INTERNAL_ERROR — пауза ${backoffMs} мс`)\n      await new Promise(r => setTimeout(r, backoffMs))\n      backoffMs = Math.min(backoffMs * 2, 60000)\n      continue\n    }\n\n    backoffMs = 5000\n    for (const event of json.data?.events ?? []) {\n      \u002F\u002F обработка события\n    }\n  } catch {\n    await new Promise(r => setTimeout(r, backoffMs))\n    backoffMs = Math.min(backoffMs * 2, 60000)\n  }\n\n  await new Promise(r => setTimeout(r, 3000))\n}\n```\n\n---\n\n## Бот отключён (BOT_DISABLED)\n\nСимптом:\n\n```json\n{ \"success\": false, \"error\": { \"code\": \"BOT_DISABLED\", \"message\": \"Bot is disabled (reason: …)\" } }\n```\n\nHTTP-код — `410 Gone`. Затронуты все эндпоинты бота: события, сообщения, чаты, команды, обновление, удаление.\n\n### Возможные причины (поле `reason`)\n\n- `AUTH_FAILURES` — 10 подряд `401 INVALID_CREDENTIALS` от Битрикс24. Платформа защищает портал от шумных запросов и автоматически отключает бота со сломанной авторизацией.\n- `PORTAL_DELETED` — портал Битрикс24 удалён или подтверждён недоступным.\n\n### Решение\n\n`AUTH_FAILURES` — вызовите [`POST \u002Fv1\u002Fbots\u002F:botId\u002Freauth`](\u002Fdocs\u002Fbots\u002Fmanagement\u002Freauth). Проверка подтверждает доступ бота, при необходимости обновляет токен и снимает отключение. Если в ответ пришёл `410 REAUTH_REQUIRED` — доступ восстановить автоматически нельзя, ключ нужно авторизовать заново через OAuth или пересоздать личный ключ.\n\nСбросить только счётчик ошибок авторизации, без проверки доступа, можно через `PATCH \u002Fv1\u002Fbots\u002F:botId` с body `{\"disabled\": false}`:\n\n```bash\ncurl -X PATCH https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fbots\u002F42 \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"disabled\": false}'\n```\n\n`PORTAL_DELETED` — бот восстанавливается автоматически, когда портал возвращается к статусу `ACTIVE`. Принудительное включение через `PATCH` для этой причины не требуется.\n\n`PATCH … {\"disabled\": true}` запрещён — вернётся `400 DISABLE_NOT_ALLOWED`. Отключение системное, для удаления используйте `DELETE \u002Fv1\u002Fbots\u002F:botId`.\n\n---\n\n## Отличия fetch от webhook\n\nВайбкод поддерживает два режима доставки событий: `fetch` (по умолчанию) и `webhook`. Режим задаётся полем `eventMode` при регистрации бота и не меняется после.\n\n| | `fetch` | `webhook` |\n|---|---|---|\n| Как работает | Клиент сам запрашивает события через `GET \u002Fv1\u002Fbots\u002F:botId\u002Fevents` | Битрикс24 отправляет события HTTP POST на `webhookUrl` |\n| Типы значений | Сохраняют тип: `number`, `boolean`, `null` | Всё приходит строками (`\"1\"`, `\"true\"`, `\"\"`) — следствие сериализации тела на стороне Битрикс24 |\n| Объект `bot` в событии | Без поля `auth` | Содержит `auth` с OAuth-токенами портала |\n| Тайм-аут | Нет (long-poll) | 10 секунд — Битрикс24 ждёт 200 от вашего сервера и закрывает соединение |\n| Повторная доставка | Серверное хранение offset — пропустить событие нельзя | Нет автоматических повторов при таймауте или 5xx ответе |\n| Формат тела | JSON в ответе `GET \u002Fv1\u002Fbots\u002F:botId\u002Fevents` | `application\u002Fx-www-form-urlencoded` в собственном формате Битрикс24 (`event=…&data[bot][id]=…&auth[member_id]=…`) |\n| Когда выбирать | Большинство сценариев, особенно AI-агенты | Когда нужно минимальное время реакции и есть публично доступный сервер |\n\n**При `eventMode: \"webhook\"` `GET \u002Fv1\u002Fbots\u002F:botId\u002Fevents` всегда возвращает пустой массив** — события доставляются напрямую на `webhookUrl`, в polling они не попадают.\n\n### webhook требует публично достижимого URL\n\nВ режиме `webhook` Битрикс24 отправляет события POST-запросом напрямую на `webhookUrl` — **без авторизации Вайбкод**. Поэтому `webhookUrl` должен быть публично доступен из интернета.\n\nСервер Black Hole с политикой доступа по умолчанию `OWNER_ONLY` такой запрос не принимает: без сессии Вайбкод он останавливается на странице-заставке туннеля, и событие до приложения не доходит. Чтобы сервер Black Hole принимал входящие события, переведите его в политику `PUBLIC` через [`PATCH \u002Fv1\u002Finfra\u002Fservers\u002F:id\u002Faccess-policy`](\u002Fdocs\u002Finfra\u002Faccess\u002Faccess-policy). Политика `PUBLIC` открывает субдомен всем без авторизации — включайте её осознанно. Альтернатива — указать внешний публично доступный `webhookUrl`, не на субдомене Black Hole.\n\nСервер, созданный для AI-агента, всегда остаётся в политике `OWNER_ONLY` — сменить её нельзя. Для webhook-бота на таком сервере используйте внешний публично доступный `webhookUrl`.\n\nСервер должен работать в момент прихода события. Спящий сервер Black Hole событие не получит, а повторов доставки нет — для webhook-бота отключите автоматический переход в сон, чтобы сервер оставался доступен.\n\nДостижимость `webhookUrl` при регистрации не проверяется — бот зарегистрируется и с недоступным адресом.\n\n---\n\n## Стикеры\n\nБоты **не могут отправлять** стикеры пользователям. Это ограничение Bot API v2 Битрикс24.\n\nБоты могут **получать** стикеры: если пользователь отправил стикер, событие `ONIMBOTV2MESSAGEADD` придёт, но поле `message.text` будет пустым. Реагировать на стикеры можно, отправив текстовое сообщение или вложение через `POST \u002Fv1\u002Fbots\u002F:botId\u002Fmessages`.\n\n---\n\n## Куда обратиться\n\nЕсли ни один из разделов выше не помог — оставьте тикет в разделе [Обратная связь](\u002Fdocs\u002Ffeedback). К тикету приложите:\n\n- `botId` (число)\n- ответ `GET \u002Fv1\u002Fbots\u002F:botId` целиком\n- последние 3 ответа `GET \u002Fv1\u002Fbots\u002F:botId\u002Fevents` с полями `nextOffset`, `storedOffset`, `persisted`, `hint`\n- время первого появления симптома (UTC)\n- тип ключа (`vibe_api_…` или `vibe_app_…`) — без самого ключа\n- скриншот чата с непрочитанным сообщением, если есть.\n\n---\n\n## Смотрите также\n\n- [Бот-платформа](\u002Fdocs\u002Fbots)\n- [Получить события (polling)](\u002Fdocs\u002Fbots\u002Fevents\u002Fpolling)\n- [User-события](\u002Fdocs\u002Fbots\u002Fevents\u002Fuser-events)\n- [Зарегистрировать бота](\u002Fdocs\u002Fbots\u002Fmanagement\u002Fcreate)\n- [Обработчик на стороне приложения](\u002Fdocs\u002Finfra\u002Fevent-subscriptions\u002Fhandler)\n- [Ключи и авторизация](\u002Fdocs\u002Fkeys-auth)\n- [Лимиты и оптимизация](\u002Fdocs\u002Foptimization)\n","2026-07-13",{}]