Events

Receive incoming bot events by polling and process them: new messages, commands, reactions, and the bot being added to a chat.

Scope: imbot | Base URL: https://vibecode.bitrix24.com/v1 | Authorization: X-Api-Key

Get events (polling)

GET /v1/bots/:botId/events

The primary mechanism for receiving incoming messages and commands. The bot periodically requests new events. The request does not wait for them to appear: the response arrives immediately, with an empty events array when the queue is empty.

Vibecode stores lastOffset in the database — on the first request without offset, the stored value is used. This lets the bot resume where it left off after a restart.

Parameters

Examples

curl — personal key

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

curl — OAuth application

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

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/bots/42/events?limit=50', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log('Events:', data.events.length, 'More:', data.hasMore)

JavaScript — OAuth application

const res = await fetch('https://vibecode.bitrix24.com/v1/bots/42/events?limit=50', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()

Response fields

If the Bitrix24 account address changed after the bot was registered, polling returns 409 BOT_RECOVERY_IN_PROGRESS with the Retry-After: 5 header: the platform recovers the bot's registration and Open Channels bindings by itself. Until it finishes, every call that changes the bot, including POST /v1/bots/:botId/resubscribe and DELETE /v1/bots/:botId, returns the same refusal. Keep polling with that delay, 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 recovery path for the bot's owner type in Re-subscribe to events.

Response example

There are new events (persisted: true):

{
  "success": true,
  "data": {
    "events": [
      {
        "eventId": 35,
        "type": "ONIMBOTV2MESSAGEADD",
        "date": "2026-04-13T17:15:00+00:00",
        "data": {
          "message": { "id": 1501, "text": "Hi, bot!" },
          "chat": { "id": 123, "dialogId": "chat123", "type": "chat" },
          "user": { "id": 1, "name": "John Brown" }
        }
      }
    ],
    "nextOffset": 36,
    "hasMore": false,
    "storedOffset": 35,
    "persisted": true
  }
}

A persistently empty events queue (the hint field appears; the number in the text is the count of observed empty periods, not requests made):

{
  "success": true,
  "data": {
    "events": [],
    "nextOffset": 36,
    "hasMore": false,
    "storedOffset": 36,
    "persisted": false,
    "hint": "Events queue has stayed empty across 7 consecutive checks (the empty-poll counter is sampled periodically, not once per request, so this reflects sustained emptiness rather than the exact number of polls). Bot config: eventMode='fetch', code='support_bot'. If the bot is alive on B24 (chats receive messages, im.bot.list lists it) the most common cause is B24-side event-subscription decay — run POST /v1/bots/42/resubscribe first (lightweight, preserves openline / WELCOME_BOT bindings). If that does not help, verify: (1) eventMode is 'fetch' (current: 'fetch'); (2) your OAuth app's INSTALL event handler responded 200 to Bitrix24; (3) the bot was added to a chat where messages are being sent (it must be a participant for chat-message events); (4) only if all of the above are confirmed — try POST /v1/bots to re-register (destroys openline bindings; last resort)."
  }
}

Error response example

404 — bot not found:

{
  "success": false,
  "error": {
    "code": "BOT_NOT_FOUND",
    "message": "Bot 999 not found. Register it first via POST /v1/bots."
  }
}

Errors

Full list of common API errors — Errors.

Known specifics

Which token to use. For a personal key vibe_api_… the X-Api-Key header is enough. For an authorization key vibe_app_… you must add Authorization: Bearer <session_token> — without Bearer the request returns 401 TOKEN_MISSING. To obtain the session_token for an OAuth application, see Keys and authorization.

Plan access. Bot access follows your Bitrix24 account plan. A plan-based rejection is final — stop the polling loop instead of retrying it. Response shape and recovery — Billing and plans.

Server-side offset storage: Vibecode stores lastOffset in the database. Every request without offset reads the stored value. When a request advances the position, the platform saves it first and only then returns the events with persisted: true. If the position cannot be saved, 503 BOT_EVENTS_UNAVAILABLE arrives without events.

One poll at a time. Wait for the response before sending the next request. When polls for one bot overlap, only one of them advances the stored position and returns those events with persisted: true. An overlapping poll receives 409 BOT_EVENTS_BUSY with no events. A poll that does not advance the position (an explicit offset below the stored value, or an empty queue) may return 200 instead. An overlapping request may reach Bitrix24 before it is refused, and it counts against the Bitrix24 request limit. On 409 and 503, retry after one second, as the Retry-After: 1 header indicates. Polls of different bots do not wait for each other, even when they share a user-event queue.

Exactly-once processing is not guaranteed. The connection can break after the position has already been saved. So your application should guard against processing an event twice, and that guard should take the event type into account.

offset=0: event history cannot be replayed — acknowledged events are removed from the queue. An explicit offset=0 acknowledges nothing and shows the events still waiting for acknowledgement, including those the last request already received — a way to inspect the queue while debugging. Once the bot has received events, offset=0 is below the stored value, so lastOffset does not change, the response carries persisted: false, and the next request without offset continues from the stored value without losing new events.

offset=N (a specific value): the event with the given ID is itself included in the response. To avoid duplicates, always pass nextOffset from the previous response, not the eventId of the last processed event. A request with N equal to or above the stored value advances lastOffset the same way a request without offset does.

Request chain:

GET /events           → { nextOffset: 42, hasMore: true }
GET /events?offset=42 → { nextOffset: 55, hasMore: false }
GET /events?offset=55 → { events: [], hasMore: false }

Recommended polling interval: 2-5 seconds between requests — when the platform sends no nextPollAfterMs (the conditions under which the field is present, including a request with withUserEvents=true, are in the response-fields table). When it does, wait as long as the field specifies: the value may change between platform releases, so clamp it with your own bounds instead of relying on a specific number.

Polling does not keep the machine online. If the loop below runs on a Black Hole server, disable auto-sleep on it. The idle timer counts inbound requests to the server, while polling only makes outbound calls — from the timer's point of view the server is idle, and after an hour it goes to sleep along with the bot process. Turn it off with a PATCH /v1/infra/servers/:id/sleep call passing sleepAfterMinutes: null.

Polling loop (ready-to-use example):

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

async function pollEvents() {
  let offset = undefined

  while (true) {
    // Declared outside `try`: the pause below reads the response after `catch`.
    let data

    try {
      const url = new URL(`${BASE}/bots/${BOT_ID}/events`)
      if (offset !== undefined) url.searchParams.set('offset', String(offset))

      const res = await fetch(url, {
        headers: { 'X-Api-Key': API_KEY },
      })
      data = (await res.json()).data

      for (const event of data.events ?? []) {
        await handleEvent(event)
      }

      if (data.nextOffset !== undefined) {
        offset = data.nextOffset
      }
    } catch (err) {
      console.error('Poll error:', err.message)
    }

    // A pause from the platform (`nextPollAfterMs`) — the conditions for the field are in the response-fields table.
    // A bot in `fetch` mode never receives the field, so the loop falls back to its own interval.
    await new Promise(r => setTimeout(r, Math.min(data?.nextPollAfterMs ?? 3000, 3600000)))
  }
}

async function handleEvent(event) {
  const { data } = event

  switch (event.type) {
    case 'ONIMBOTV2MESSAGEADD':
      // Reply to the message
      await fetch(`${BASE}/bots/${BOT_ID}/messages`, {
        method: 'POST',
        headers: { 'X-Api-Key': API_KEY, 'Content-Type': 'application/json' },
        body: JSON.stringify({
          dialogId: data.chat.dialogId,
          fields: { message: `Received: ${data.message.text}` },
        }),
      })
      break

    case 'ONIMBOTV2COMMANDADD':
      // Reply to the command
      await fetch(`${BASE}/bots/${BOT_ID}/commands/${data.command.id}/answer`, {
        method: 'POST',
        headers: { 'X-Api-Key': API_KEY, 'Content-Type': 'application/json' },
        body: JSON.stringify({
          dialogId: data.chat.dialogId,
          messageId: data.message.id,
          fields: { message: `Command /${data.command.command}: ${data.command.params}` },
        }),
      })
      break
  }
}

pollEvents()

See also

• Troubleshooting
• Bot events
• User events
• Send message
• Reply to a command
• Configure auto-sleep
• Bot platform
• Limits and optimization