Messages around a message

GET /v1/chats/messages/:messageId/context

Returns a message and its neighbours. Use it to open a chat at a specific message: from a link, from search or from a reply. The chat is resolved from the message, so no dialogId is needed.

Parameters

Any other parameter or a repeated parameter is rejected with 400 INVALID_PARAMS.

Read-only key. In READONLY mode this request reads an existing chat by messageId: the chat is resolved from the message, and no dialogId is passed. The read effects — auto-join and a presence update — are described below, under "Opening the context may make you a member".

This exception for named reads applies only to an ordinary employee personal key, whether it uses a webhook or previously configured OAuth tokens. In READONLY mode, 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 before the existing-chat binding is checked and the named messenger method is called. Ordinary reads without these effects remain available to application keys; keys in read-write mode are unaffected.

Examples

curl — personal key

curl "https://vibecode.bitrix24.com/v1/chats/messages/1002/context?range=10" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

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

const { data } = await res.json()
console.log('Messages:', data.messages.map((m) => m.id))

JavaScript — OAuth application

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

const { data } = await res.json()
console.log('Messages:', data.messages.map((m) => m.id))

Response fields

Response example

{
  "success": true,
  "data": {
    "messages": [
      {
        "id": 1001,
        "chatId": 42,
        "authorId": 5,
        "date": "2026-09-20T10:00:00+00:00",
        "text": "Please check the mockup",
        "params": {},
        "block": null
      },
      {
        "id": 1002,
        "chatId": 42,
        "authorId": 7,
        "date": "2026-09-20T10:01:00+00:00",
        "text": "All done",
        "params": {},
        "block": null
      }
    ],
    "users": [],
    "files": [],
    "reactions": [],
    "hasPrevPage": false,
    "hasNextPage": true
  }
}

Error response example

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

{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "MESSAGE_NOT_FOUND",
    "b24Code": "MESSAGE_NOT_FOUND"
  }
}

Errors

The full list of common API errors — Errors.

Known specifics

Opening the context may make you a member. When the message's chat allows auto-join, the call adds the current user as a member, as loading a chat does. A READONLY key may call this read operation 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. Opening the context does not itself mark the message as read. The exact boundaries of these effects are described in access rights.

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.

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, and newer ones with order=asc and lastId equal to the largest.

See also

• Load a chat
• Read messages