Load a chat

GET /v1/chats/:dialogId/load

Opens a chat in one request: the chat card, the first page of messages, pinned messages, participants and files. The first page is built around the last read message, or around the unread mark when the chat is marked as unread.

Parameters

Other or repeated parameters are rejected with 400 INVALID_PARAMS.

The lightweight load. shallow=true opens the chat: data carries the chat card, its members and the chat context — recentConfig, parentChat, copilot, messagesAutoDeleteConfigs, callInfo — but no page of messages, no pinned messages, no files and no hasPrevPage / hasNextPage flags. This is the call for a chat header or a settings screen. The lightweight load may make you a member too. For an ordinary employee personal key this is a permitted named read of an existing chat. shallow=false is the full load. A request without shallow gets the same full-load response and refusals.

Read-only key. In READONLY mode, this request reads an existing chat: pass 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.

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 unchanged.

Examples

curl — personal key

curl "https://vibecode.bitrix24.com/v1/chats/chat42/load?messageLimit=30" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

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

const { data } = await res.json()
console.log('Chat:', data.chat.name)
console.log('Messages:', data.messages.length, 'has older:', data.hasPrevPage)

JavaScript — OAuth application

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

const { data } = await res.json()
console.log('Chat:', data.chat.name)
console.log('Messages:', data.messages.length, 'has older:', data.hasPrevPage)

curl — the lightweight load

curl "https://vibecode.bitrix24.com/v1/chats/chat42/load?shallow=true" \
  -H "X-Api-Key: YOUR_API_KEY"

Response fields

Response example

{
  "success": true,
  "data": {
    "chat": {
      "id": 42,
      "dialogId": "chat42",
      "name": "Project",
      "type": "chat",
      "owner": 5,
      "role": "member"
    },
    "messages": [
      {
        "id": 1002,
        "chatId": 42,
        "authorId": 7,
        "date": "2026-09-20T10:01:00+00:00",
        "text": "All done",
        "params": {}
      }
    ],
    "pins": [],
    "users": [],
    "files": [],
    "reactions": [],
    "hasPrevPage": true,
    "hasNextPage": false
  }
}

Error response example

422 — the chat does not exist in the Bitrix24 account:

{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Specified chat does not exist.",
    "hint": "dialogId must be a userId (number as string) for DMs or \"chat{N}\" for group chats. Examples: \"1\" for user 1, \"chat123\" for group chat 123. Create a group chat first via POST /v1/bots/:botId/chats if needed.",
    "b24Code": "CHAT_NOT_FOUND"
  }
}

Errors

The full list of general API errors — Errors.

Known specifics

Opening a chat may make you a member. When the chat allows auto-join — for example, comment chats, collabs, task chats — the call adds the current user as a member, as opening the chat in the Bitrix24 interface does. This is Bitrix24 account behavior, and the endpoint does not hide it. A READONLY key may call this read operation as a targeted exception. The user's permissions and the im scope are still checked. Opening the chat does not itself mark messages as read. The other effects of loading a chat — presence updates, quick file access after a permission check, a subscription to chat updates and a background external-chat event — are listed in access rights. For a collab or a workgroup, this background event can trigger a deferred project conversion. The same auto-join exception applies to message history in the v2 mode and messages around a message.

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 you can look up a role directly with roles[role]. Fields inside a role are converted to camelCase.

Continue in the message history. Read older messages from the message history in the v2 mode, passing lastId equal to the smallest id on the page.

The lightweight load has no messages. After shallow=true, read the page of messages from the message history in the v2 mode, and to open the chat at a specific message, use loading around a message.

See also

• Read messages
• Messages around a message
• Load around a message
• Unread counters