Load a chat

GET /v1/chats/:dialogId/load

Opens a chat in one request — the v2 messenger method im.v2.Chat.load: 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. The me alias passed as dialogId addresses the current user's personal dialog.

Parameters

Other or repeated parameters are rejected with 400 INVALID_PARAMS.

The lightweight load. shallow=true opens the chat with the v2 messenger method im.v2.Chat.shallowLoad: 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; without shallow the response and the refusals are unchanged.

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 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; 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 behavior, and the endpoint does not hide it. A READONLY key is allowed 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. Access rights describes the other Chat.load effects: presence updates, quick file access after a permission check, PullWatch, and a background external-chat event that can trigger lazy 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 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 you can look up a role directly with roles[role]. Fields inside a role are converted to camelCase as usual.

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

The lightweight load has no messages. With shallow=true, data holds only chat, users and the chat context. Read the page of messages afterwards with 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