Bot platform troubleshooting

If the bot does not reply to messages, start with the sections below. Each scenario is a separate set of checks with ready-to-use curl commands and reference responses from Vibecode.

Diagnostic scenarios

• Events do not arrive — a user writes to the bot, but GET /v1/bots/:botId/events returns an empty array
• The bot was working and went silent — the bot used to reply, then stopped, and event polling no longer runs
• TOKEN_MISSING with an authorization key — vibe_app_… sent without Authorization: Bearer
• Empty events in a row — success: true, but nextOffset does not move
• BITRIX_ERROR: User is not subscribed — withUserEvents=true without a prior subscription
• INTERNAL_ERROR while polling events — a transient proxy error and a retry scheme with exponential backoff
• Bot disabled (BOT_DISABLED) — automatic disabling on AUTH_FAILURES or PORTAL_DELETED
• The code is taken but the bot is missing from the list — 409 BOT_ALREADY_EXISTS on registration and an empty GET /v1/bots
• fetch vs webhook differences — the difference in data formats and delivery behavior
• Stickers — a platform limitation
• Bot API v2 methods are missing from the Bitrix24 REST method list — the Bitrix24 REST method list does not include Bot API v2 names
• Where to reach out — what to attach to a support ticket

Events do not arrive

Symptom: a user writes to the bot in a Bitrix24 chat, the bot does not reply, GET /v1/bots/:botId/events returns events: [].

Checklist in order

1. The bot is registered and active. GET /v1/bots/:botId returns success: true with the fields bot.id, bot.code, bot.eventMode. If it returns 404, the bot is not registered: run POST /v1/bots.
2. eventMode: "fetch". Checked in the response from step 1. If it is webhook, events do not arrive via polling: Bitrix24 delivers them to webhookUrl.
3. The bot type matches the scenario. A bot of type bot receives only messages with an @mention and direct messages. To receive all messages in a chat you need the type personal or supervisor — it is specified at registration in the type field and cannot be changed afterwards. If you expect all messages but the type is bot, events will arrive only on an @mention.
4. The bot is added to the chat. The bot receives events only from chats it is a member of. For a direct dialog this happens on the user's first interaction with the bot. For a group chat the bot must be added explicitly via POST /v1/bots/:botId/chats/:dialogId/users.
5. The user is writing to this exact bot. If your Bitrix24 account has several bots, check the code of the bot being addressed in the chat and compare it with the code in the GET /v1/bots/:botId response. Messages to another bot will not land in this bot's queue.
6. Check the hint field in the GET /v1/bots/:botId/events response. The diagnostic hint is not based on the number of requests: the empty-response counter is updated periodically, so with the recommended polling interval of 2–5 seconds, the hint appears after roughly two minutes of polling with no events. See the response fields table for the conditions under which the hint appears; webhook bots receive it on the first empty response.
7. Choose the recovery path based on the API response. If the bot is active and the queue stays empty, try POST /v1/bots/:botId/resubscribe. If GET /events or /resubscribe returned 409 BOT_RECOVERY_IN_PROGRESS, the platform has detected an address change and is automatically restoring the bot's registration and Open Channels bindings. Until recovery finishes, event polling and every call that changes the bot, including /resubscribe, /reauth, PATCH and deletion through DELETE /v1/bots/:botId, return 409 BOT_RECOVERY_IN_PROGRESS: retry later, and contact support if the recovery does not finish. An address change made before this diagnostic became available does not produce a 409. If the address changed and resubscription did not restore delivery, choose the path for the bot's owner type. For a standalone Bot, delete the old registration through DELETE /v1/bots/:botId before reusing the same code, or register a new unique code, then restore the Open Channels and WELCOME_BOT bindings; the same code may reuse the old identity and does not guarantee a new bot ID. For an AI agent's bot or a managed bot, do not call DELETE /v1/bots/:botId: use the recovery procedure for the resource that owns the bot, or contact support if that recovery is unavailable.

If all 7 items pass but the queue is still empty, the Bitrix24 account is not routing events to the bot. Collect the data from the Where to reach out section and submit a ticket.

The checklist assumes polling is running. If the bot replied at first and then went silent, and polling no longer runs, start with the next section.

The bot was working and went silent

Symptom: the bot used to reply to messages, then stopped. The last GET /v1/bots/:botId/events call went through without errors, no new requests come from the bot, and user messages go unanswered.

Cause

The virtual machine the bot runs on has been stopped by the idle timeout — on a new machine it is 60 minutes. The bot sends polling requests outbound, but only inbound requests to the application reset the timer, so polling does not keep the machine running. After an hour without inbound requests it stops together with the bot process. For ways to prevent this when starting a bot, see Where the bot runs.

Check

curl -H "X-Api-Key: YOUR_API_KEY" \
  https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID

On a stopped machine data.status is sleeping, and the timeout in effect is returned in data.sleepAfterMinutes.

Solution

Disable auto-sleep and wake the machine:

# Disable auto-sleep — only null is accepted,
# 0 is rejected with VALIDATION_ERROR
curl -X PATCH https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/sleep \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sleepAfterMinutes": null}'

# Wake it and wait until it is ready
curl -X POST -H "X-Api-Key: YOUR_API_KEY" \
  "https://vibecode.bitrix24.com/v1/infra/servers/SERVER_ID/wake?wait=true"

An application deployed through the Deploy API starts with the machine: deployment creates a systemd unit that starts the application automatically unless you passed systemd: false.

Confirm it in the chat: message the bot in a Bitrix24 chat and wait for its reply — that proves polling works again. Let the bot be the first to collect any events that accumulated while the machine was asleep: a GET /v1/bots/:botId/events response advances the cursor stored on the server, so events returned by a manual request will no longer reach the bot. If no reply arrives in the chat, check the service log — GET /v1/infra/servers/:id/logs.

See Configure auto-sleep for the allowed timeout values and restrictions on combining timeout settings with wake-schedule windows.

TOKEN_MISSING with an authorization key

Symptom:

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

Cause

The vibe_app_… key was sent without the Authorization: Bearer <session_token> header. An authorization key works in tandem with a user session token — without Bearer the request has no context identifying the user on whose behalf to call Bitrix24.

Solution

A personal key vibe_api_… — no Bearer needed:

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

An authorization key vibe_app_… — Bearer is mandatory:

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

For instructions on obtaining USER_SESSION_TOKEN for an OAuth application, see Keys and authorization.

This error also comes up in an application-side event handler that calls the V1 API in response to a delivered event. The handler has no user session, so a vibe_app_ key does not work there — use a personal vibe_api_ key. See Application-side handler.

Empty events in a row

Symptom: the response is correct, there are no errors, but events: [], nextOffset === storedOffset, persisted: false.

What the response fields mean

• persisted: false — the lastOffset cursor in the Vibecode database did not move, because Bitrix24 did not return a single event.
• nextOffset === storedOffset — nothing to process.
• hint — a diagnostic hint for a persistently empty queue, not a marker of how many requests were made.

This is normal if

• the bot was just registered — nobody has messaged it yet
• the queue is empty — clients have read all messages
• there is no activity in chats with the bot between polls.

When to move on to diagnostics

If at least one condition holds, go back to the Events do not arrive section:

• there are unread messages to the bot in the chat
• more than a minute has passed since the message was sent
• the hint field has appeared — its absence means nothing while empty polling has run for less than a couple of minutes.

BITRIX_ERROR: User is not subscribed

Symptom: GET /v1/bots/:botId/events?withUserEvents=true returns 422 with this message.

Cause

User events (types ONIMV2* — chat changes, user reactions) require a separate subscription. Without a subscription the withUserEvents=true parameter does not enable delivery.

Solution

Subscribe once before using withUserEvents=true. The full setup procedure and the list of events are in the User events section.

After subscribing, GET /v1/bots/:botId/events?withUserEvents=true starts returning user events together with bot events in the same array.

INTERNAL_ERROR while polling events

Symptom: HTTP 500 with code INTERNAL_ERROR.

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

What to do

1. Do not repeat the request right away. Retries without a pause prolong the error state and become a cause of overload in their own right.
2. Use exponential backoff between attempts — start at 5 seconds, double on each subsequent failure, cap at 60 seconds. After a successful response the interval resets to the working value (2-5 seconds between polls).
3. Do not reset offset. The stored cursor was not affected — continue from the same value. A reset leads to reprocessing already delivered events.
4. If the error does not go away after several delay cycles — submit a support ticket with the botId, the time of first occurrence, the last successful nextOffset, and the interval between attempts. Do not increase the request frequency "just in case" — it will make things worse.

Ready-to-use template with exponential backoff

Polling retries 429 RATE_LIMITED / CALLER_RATE_LIMITED and transient 409 / 503 errors only after Retry-After. For 500 INTERNAL_ERROR, it uses an increasing delay without this header. Terminal 409 stops the loop: for BOT_ID_REPLACED, update the ID using error.details.botId before restarting; for BOT_UNAVAILABLE, contact support. Other terminal refusals require fixing their cause. See Polling errors.

const BOT_ID = 42
const API_KEY = 'YOUR_API_KEY'
const BASE = 'https://vibecode.bitrix24.com/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 (!res.ok && !(res.status === 500 && json.error?.code === 'INTERNAL_ERROR')) {
      const retryable =
        (res.status === 429 && ['RATE_LIMITED', 'CALLER_RATE_LIMITED'].includes(json.error?.code)) ||
        (res.status === 409 && ['BOT_EVENTS_BUSY', 'BOT_RECOVERY_IN_PROGRESS'].includes(json.error?.code)) ||
        (res.status === 503 && json.error?.code === 'BOT_EVENTS_UNAVAILABLE')
      const retryAfter = Number(res.headers.get('Retry-After'))
      if (retryable && Number.isFinite(retryAfter) && retryAfter > 0) {
        await new Promise(r => setTimeout(r, retryAfter * 1000))
        continue
      }
      console.error('Polling stopped:', json.error)
      break
    }

    if (res.status === 500 && json.error?.code === 'INTERNAL_ERROR') {
      console.warn(`INTERNAL_ERROR — pause ${backoffMs} ms`)
      await new Promise(r => setTimeout(r, backoffMs))
      backoffMs = Math.min(backoffMs * 2, 60000)
      continue
    }

    backoffMs = 5000
    for (const event of json.data?.events ?? []) {
      // handle the event
    }
  } catch {
    await new Promise(r => setTimeout(r, backoffMs))
    backoffMs = Math.min(backoffMs * 2, 60000)
  }

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

Plan access while polling. Access to the platform follows the Bitrix24 account plan. A plan denial is separate from BOT_DISABLED and is not retryable — stop the polling loop instead of retrying it. After a plan upgrade, call GET /v1/me?refresh=tariff; the fresh check automatically restores all the account's bots. /reauth and /resubscribe solve credential and event-binding problems, not plan access.

Bot disabled (BOT_DISABLED)

Symptom:

{ "success": false, "error": { "code": "BOT_DISABLED", "message": "Bot is disabled. This bot will not process API calls until it is re-enabled.", "details": { "reauthAllowed": true } } }

The HTTP status is 410 Gone. Every endpoint of a specific bot (/v1/bots/:botId/…) is affected, except those listed next. On a disabled bot, deletion (DELETE /v1/bots/:botId), /reauth, /transfer, /resubscribe and PATCH /v1/bots/:botId with the flat body {"disabled": false} keep working. For that PATCH the body form matters: disabled is read only from the top level, so {"fields": {"disabled": false}} is an ordinary update and returns 410 — see Update a bot.

The message intentionally does not expose an internal reason. The only client-facing recovery signal is the strict boolean error.details.reauthAllowed.

Solution

When reauthAllowed=true, call POST /v1/bots/:botId/reauth. The check confirms the bot's access, refreshes the token if needed, and clears the disabled state. If the response is 410 REAUTH_REQUIRED, access cannot be restored automatically; re-authorize the key via OAuth or recreate the personal key.

When reauthAllowed=false, do not call /reauth: ordinary disabled states return 409 BOT_REAUTH_NOT_ALLOWED. If ownership or state changes during the probe, the response is 409 BOT_REAUTH_STATE_CHANGED, and the newer state is preserved. Manual /reauth is also allowed as an active credential check after an ownership transfer.

To reset only the authorization error counter, without an access check, use PATCH /v1/bots/:botId with the body {"disabled": false}:

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

PORTAL_DELETED — the bot is restored automatically when the Bitrix24 account returns to the ACTIVE status. Forced enabling via PATCH is not required in this case.

PATCH … {"disabled": true} is forbidden — it returns 400 DISABLE_NOT_ALLOWED. Disabling is system-imposed. To delete, use DELETE /v1/bots/:botId.

The code is taken but the bot is missing from the list

Symptom: POST /v1/bots responds with 409 BOT_ALREADY_EXISTS, while GET /v1/bots under the same key returns an empty bots array.

Cause

The bot was registered using another key of the same Bitrix24 account. The list is filtered by the calling key, while codes are unique across the account. Recreating an OAuth application also changes its identity and does not authorize a transfer.

Solution

Only 409 BOT_ALREADY_EXISTS with data.botId identifies a local record for a possible transfer. An app-owned OAuth bot can transfer only to an eligible key of the same OAuth application (client_id). Restore access to that matching application and key; a recreated application with another client_id cannot take ownership: 400 TARGET_KEY_INVALID with error.reason=application_mismatch. If the matching application cannot be restored, contact support. Unmarked legacy/token-based and personal-webhook bots retain their existing transfer rules and can use an eligible key of the same Bitrix24 account. Transfer to a compatible key preserves botId, chats and history. See Bot access recovery.

fetch vs webhook differences

Vibecode supports two event delivery modes: fetch (default) and webhook. The mode is set by the eventMode field at bot registration and does not change afterwards.

With eventMode: "webhook", GET /v1/bots/:botId/events always returns an empty array — events are delivered directly to webhookUrl and never land in the polling queue.

webhook requires a publicly reachable URL

In webhook mode, Bitrix24 sends events as a POST request directly to webhookUrl — without a user signing in to Vibecode. So webhookUrl must be publicly reachable from the internet.

If webhookUrl points directly at a Black Hole server subdomain, whether the event reaches the app depends on that server's key.

New OAuth bots support fetch and webhook. The platform verifies bot ownership through the same OAuth application and an exact id/code match, without sending botToken to the OAuth API. Delivery to /api/bot/webhook requires a fresh verified INSTALL/placement of the bound application; otherwise registration returns 409 BOT_APP_EVENT_ENROLLMENT_REQUIRED. A historical application token does not replace this verification. Events received before initial registration completes are retained in a bounded encrypted inbox. Bot-token changes for new application-owned bots are refused (409 BOT_OAUTH_POLICY_INVALID); unmarked legacy bots are not automatically converted. A standalone OAuth key without a bound application can use fetch or its own receiver, but is not trusted by the platform receiver.

The platform receiver is available to Agent and ManagedBot bots with a verified owner. An application bot without a verified owner receives 409 BOT_APP_EVENT_CONSUMER_REQUIRED before any data is written to Bitrix24. It can use fetch or its own callback. Events for an already published bot after a Bitrix24 account address change may remain in encrypted quarantine until the recovered identity is verified and published. Delivery requires an unchanged callback binding, continued eligibility of the application, author and owner membership, and verified authority to deliver the recovered events. If that basis changes or cannot be verified, held events are permanently discarded while bot identity recovery continues. Bounded retention does not guarantee delivery. Each recovery can retain at most 256 events and 4 MiB of ciphertext for 72 hours. A duplicate event does not extend retention. On overflow, the receiver returns 503 without acknowledging receipt.

A personal vibe_api_… key. There is no way to identify the sender, so only the PUBLIC policy accepts the event. Under OWNER_ONLY (the default), NAMED_USERS, DEPARTMENT, PORTAL, and AUTHENTICATED the request is rejected, and the event never reaches the app. There are two options. Switch the server to the PUBLIC policy via PATCH /v1/infra/servers/:id/access-policy — it opens the subdomain to everyone without authorization, so enable it deliberately. Or receive events by polling: eventMode: "fetch" and GET /v1/bots/:botId/events.

For webhook bots registered with a personal key, another option is an external publicly reachable webhookUrl, not on a Black Hole subdomain.

A server created for an AI agent always stays on the OWNER_ONLY policy — it cannot be changed. An Agent or ManagedBot bot with verified ownership and application enrollment can use the platform receiver /api/bot/webhook: the platform receives the event and delivers it through the owner's tunnel. For direct delivery from Bitrix24 without the platform receiver, use your own publicly reachable webhookUrl outside the private server subdomain.

Bitrix24 does not retry webhook delivery. For direct delivery to your own URL, the receiver must be available when the event arrives; a sleeping server cannot receive it. Events already accepted by the platform receiver are retained in the platform queue for delivery after the tunnel returns, for up to 72 hours. This queue does not protect direct delivery to your own URL. Automatic sleep also stops the machine running a fetch-mode bot, because outbound polling does not reset the timeout: see The bot was working and went silent.

The reachability of webhookUrl is not verified at registration — the bot will register even with an unreachable address.

Stickers

Bots cannot send stickers to users. This is a limitation of the Bitrix24 Bot API v2.

Bots can receive stickers: if a user sends a sticker, the ONIMBOTV2MESSAGEADD event arrives, but the message.text field will be empty. You can react to stickers by sending a text message or an attachment via POST /v1/bots/:botId/messages.

Bot API v2 methods are missing from the Bitrix24 REST method list

Symptom: the integration calls the methods REST method on the Bitrix24 account with no parameters and looks for Bot API v2 method names in the response, for example imbot.v2.Chat.Message.send. Those names are not in the response, and the integration concludes that sending messages and bot reactions are unavailable.

Cause

The Bitrix24 REST method list is incomplete with regard to Bot API v2. Some bot methods are present in it under previous-generation names, and version 2 methods are not part of that list. A check of the form "is the name in the list" therefore reports a capability as missing even though it works on the account. This is Bitrix24 platform behavior, not a Vibecode limitation.

A method missing from the list is different from a method being unavailable on the account: calling a nonexistent method returns a "method not found" error, while calling a Bot API v2 method with incomplete parameters returns a missing-parameter error. This explains the symptom, but it is not a way to check availability: bot capabilities on Vibecode are defined by the endpoint reference, not by the account's responses.

Solution

Do not use the Bitrix24 REST method list to check bot capabilities. The procedure is:

1. Register the bot — Register a bot, POST /v1/bots.
2. Receive events — Get events (polling), GET /v1/bots/:botId/events.
3. Send messages — Send message, POST /v1/bots/:botId/messages.
4. Add and remove reactions — Add reaction, Remove reaction.

The full list of bot capabilities is the Endpoint reference: every Vibecode bot platform endpoint and the Bitrix24 method behind it.

The bot platform revision of the account is returned by Bot platform revision, GET /v1/bots/revision. A growing data.rest value means that new REST capabilities of the bot platform have appeared on the account. It is a revision number, not a list of endpoints: there is no "number — capability" mapping, and no threshold such as "reactions are available once rest reaches N".

Where to reach out

If none of the sections above helped, leave a ticket in the Feedback section. Attach the following to the ticket:

• the botId (a number)
• the full GET /v1/bots/:botId response
• the last 3 GET /v1/bots/:botId/events responses with the fields nextOffset, storedOffset, persisted, hint
• the time when the symptom first appeared (UTC)
• the key type (vibe_api_… or vibe_app_…) — without the key itself
• a screenshot of the chat with the unread message, if any.

See also

• Bot platform
• Bot access recovery
• Get events (polling)
• User events
• Register a bot
• Bot platform revision
• Application-side handler
• Configure auto-sleep
• Keys and authorization
• Error codes
• Limits and optimization