Messages

Read, send, edit and delete messages, mark them as read or set them aside for later, open a chat or its first page or at a specific message, view readers, search and forward messages, manage reactions, pins, disappearing messages, channel comments and message blocks, show typing, and load messages from several dialogs in a single request.

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

Read messages

GET /v1/chats/:dialogId/messages

Returns dialog messages with cursor-based pagination. The me alias passed as dialogId addresses the current user's personal dialog — see the Chats overview for details.

Parameters

The v2 mode. format=v2 reads the message history with im.v2.Chat.Message.tail. data carries the v2 object — messages, users, files, reactions and other collections — and hasNextPage, with camelCase keys; reactions arrive on the same page. The mode accepts only format, limit (from 1 to 200; out-of-range values are clamped and echoed in meta), lastId and order; firstId is rejected with 400 INVALID_PARAMS — page forward with order=asc and lastId. The lastId bound is exclusive: the page after 52523 starts at 52522. hasNextPage: false marks the end of the history. A request in this mode differs from the examples below only in the query string: GET /v1/chats/chat42/messages?format=v2&limit=50&lastId=1002 returns 50 messages older than 1002; the authorization headers are the same. The v2 mode may make you a member: when the chat allows auto-join — a comment chat, a collab or a task chat, for example — the call adds the current user as a member, as loading a chat does. A READONLY key may use the v2 mode as a targeted exception; the user's Bitrix24 access and the im scope are still checked. Bitrix24 updates the employee's online presence on this read. Reading the history does not itself mark messages as read. These effects and their exact method boundaries are listed under access rights.

Read-only key. In READONLY mode, this request reads an existing chat both with and without format=v2: use its chatN, or a numeric peer ID confirmed in the same employee's recent dialogs. For me, the check requires an existing personal dialog. It scans at most 4000 raw rows of recent dialogs; if the binding is not confirmed, the request returns 403 WRITE_BLOCKED_READONLY_KEY without calling a method that could create a chat. The check's limits and the permitted read effects are described in access rights.

For format=v2, this exception for named reads applies only to an ordinary employee personal key, whether it uses a webhook or previously configured OAuth tokens. An application key with a user Bearer session, a management key, or a key whose owner type is unconfirmed receives 403 WRITE_BLOCKED_READONLY_KEY in READONLY or PORTAL_READONLY mode before the existing-chat binding check and before the named messenger method is called. Ordinary reads without these effects remain available to application keys; keys in read/write mode are unaffected. In regular mode without format=v2, the named-method exception does not apply: ordinary scope and user access checks remain, and the existing-binding check is still required for a read-only key.

Examples

curl — personal key

curl "https://vibecode.bitrix24.com/v1/chats/chat42/messages?limit=20" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

curl "https://vibecode.bitrix24.com/v1/chats/chat42/messages?limit=20" \
  -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/chats/chat42/messages?limit=20',
  {
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
    },
  }
)

const { success, data } = await res.json()
console.log('Messages:', data.messages)
console.log('Participants:', data.users)

JavaScript — OAuth application

const res = await fetch(
  'https://vibecode.bitrix24.com/v1/chats/chat42/messages?limit=20',
  {
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  }
)

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

Response fields

The regular mode — without format=v2:

The v2 mode — format=v2. This mode has no data.chatId field: every message carries the chat ID.

Besides the ones listed, the v2 object may carry other messenger collections — for example, additionalMessages with the messages that the page's messages reply to, and copilot; Bitrix24 determines which ones are included.

Response example

The regular mode:

{
  "success": true,
  "data": {
    "chatId": 42,
    "messages": [
      {
        "id": 1001,
        "chatId": 42,
        "authorId": 5,
        "date": "2026-06-05T10:00:00+00:00",
        "text": "Good afternoon! How are you?",
        "unread": false,
        "uuid": null,
        "replaces": [],
        "params": [],
        "disappearingDate": null
      },
      {
        "id": 1002,
        "chatId": 42,
        "authorId": 7,
        "date": "2026-06-05T10:01:00+00:00",
        "text": "All good, thanks.",
        "unread": true,
        "uuid": null,
        "replaces": [],
        "params": [],
        "disappearingDate": null
      }
    ],
    "users": [
      {
        "id": 5,
        "active": true,
        "name": "John Brown",
        "firstName": "John",
        "lastName": "Brown",
        "workPosition": "Manager",
        "color": "#3bc8f5",
        "gender": "M",
        "bot": false,
        "type": "user"
      }
    ],
    "files": []
  }
}

Response example — the v2 mode

{
  "success": true,
  "data": {
    "messages": [
      {
        "id": 1002,
        "chatId": 42,
        "authorId": 7,
        "date": "2026-09-20T10:01:00+00:00",
        "text": "All done",
        "params": {}
      },
      {
        "id": 1001,
        "chatId": 42,
        "authorId": 5,
        "date": "2026-09-20T10:00:00+00:00",
        "text": "Please review the mockup",
        "params": {}
      }
    ],
    "users": [],
    "files": [],
    "reactions": [
      {
        "messageId": 1001,
        "reactionCounters": { "like": 1 },
        "reactionUsers": { "like": [7] },
        "ownReactions": []
      }
    ],
    "hasNextPage": true
  }
}

Error response example

422 — the regular mode, dialog not found or no access:

{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Access denied"
  }
}

Errors

Full list of common API errors — Errors.

Known specifics

Cursor-based pagination. The endpoint uses cursor pagination, not page-number offsets. To load older messages, pass lastId equal to the smallest id from the last response. To load newer ones, pass firstId equal to the largest id.

The page ceiling in the regular mode is 50 messages per call. The limit parameter accepts values up to 200, but in the regular mode, cloud Bitrix24 returns at most 50 records per call regardless of the value passed. Self-hosted portals may return more. Read history beyond the latest 50 messages with the lastId cursor — page by page. The v2 mode has no such ceiling: the im.v2.Chat.Message.tail method returns as many messages per call as passed in limit, up to 200.

Message order. Messages are returned in descending order — from newest to oldest. In the v2 mode with order=asc the order is reversed: from oldest to newest, starting with the one after lastId.

The v2 mode and response keys. Keys that name fields are converted to camelCase: the FILE_ID message parameter arrives as fileId. Keys that are data stay as they are: the data.copilot.roles dictionary is keyed by the role code, and copilot_assistant arrives as copilot_assistant — the same value that role carries on a chat and a message in data.copilot, so a role is found directly as roles[role]. Fields inside a role are converted to camelCase. A request for a chat that does not exist in the Bitrix24 account returns 422 BITRIX_ERROR with error.b24Code set to CHAT_NOT_FOUND.

See also

• Messages
• Send a message
• Chat discovery