Messages

Read, send, edit and delete messages, mark them as read or set them aside for later, open a chat at its first page or at a specific message, see who has read a message, search and forward messages, manage reactions, pins, disappearing messages, channel comments and message blocks, show the typing indicator, 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.

Parameters

The v2 mode. format=v2 reads the message history. 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: an out-of-range value is clamped, and the passed and applied values are 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 access rights and the im scope are still checked. The read updates the employee's presence. 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. The check 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 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. Read/write mode is 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. Which collections are included depends on the Bitrix24 account.

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 — no access to the dialog:

{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "You do not have access to the specified dialog",
    "b24Code": "ACCESS_ERROR"
  }
}

Errors

The full list of common API errors — Errors.

Known specifics

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 a cloud portal returns at most 50 records per call regardless of the value passed. On-premise 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: a call returns as many messages 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 keys of the data.copilot.roles dictionary are role codes, 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