For AI agents: markdown of this page — /docs-content-en/bots/messages/context.md documentation index — /llms.txt

Message context

GET /v1/bots/:botId/messages/:messageId/context

Returns a window of messages around the specified one. Use it to analyze the conversation history — for example, to understand the context of an incoming message.

Bot type restriction. The method is available only for bots with type ∈ {personal, supervisor}. For the other types — bot and openline — the response is 422 with code BITRIX_ERROR, and the machine-readable reason code is returned in the error.b24Code field with the value BOT_TYPE_NOT_ALLOWED. The type is set during registration via POST /v1/bots and cannot be changed without re-registration.

Parameters

Parameter Type Required Description
ParameterbotId (path) Typenumber Requiredyes DescriptionBot ID
ParametermessageId (path) Typenumber Requiredyes DescriptionID of the central message
Parameterrange (query) Typenumber Requiredno DescriptionNumber of messages on each side of the central one (1-50). Default 50

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/bots/42/messages/1501/context?range=2" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/bots/42/messages/1501/context?range=2" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/bots/42/messages/1501/context?range=2', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log('Messages:', data.messages.length)
console.log('More before:', data.hasPrevPage)
console.log('More after:', data.hasNextPage)

JavaScript — OAuth application

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

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

Response fields

The table lists the main response fields.

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionThe message window and its authors
Fielddata.messages Typearray DescriptionThe central message and up to range messages on each side, in ascending id order
Fielddata.messages[].id Typenumber DescriptionMessage ID
Fielddata.messages[].chatId Typenumber DescriptionChat ID
Fielddata.messages[].authorId Typenumber DescriptionAuthor ID. The author's profile is in data.users
Fielddata.messages[].date Typestring DescriptionDate the message was sent (ISO 8601)
Fielddata.messages[].text Typestring DescriptionMessage text. An empty string for a message that contains only a file
Fielddata.messages[].isSystem Typeboolean DescriptionSystem message
Fielddata.messages[].params Typeobject | array DescriptionAdditional message parameters. FILE_ID is an array of file IDs; to download a file, see Download file. An empty array if there are no parameters
Fielddata.messages[].forward Typeobject | null DescriptionForwarding data. null for a message that was not forwarded
Fielddata.messages[].viewedByOthers Typeboolean DescriptionWhether other participants have read the message
Fielddata.users Typearray DescriptionProfiles of the authors of the messages in data.messages. Profile fields are the same as in List participants
Fielddata.hasPrevPage Typeboolean Descriptiontrue if more messages exist before the window
Fielddata.hasNextPage Typeboolean Descriptiontrue if more messages exist after the window

Response example

Main fields are shown.

JSON 
{
  "success": true,
  "data": {
    "messages": [
      {
        "id": 1499,
        "chatId": 123,
        "authorId": 42,
        "date": "2026-10-19T10:27:27+00:00",
        "text": "The report is ready",
        "isSystem": false,
        "forward": null,
        "params": [],
        "viewedByOthers": false
      },
      {
        "id": 1500,
        "chatId": 123,
        "authorId": 42,
        "date": "2026-10-19T10:27:29+00:00",
        "text": "",
        "isSystem": false,
        "forward": null,
        "params": {
          "FILE_ID": ["789"]
        },
        "viewedByOthers": false
      },
      {
        "id": 1501,
        "chatId": 123,
        "authorId": 1,
        "date": "2026-10-19T10:31:05+00:00",
        "text": "Hi, bot!",
        "isSystem": false,
        "forward": null,
        "params": [],
        "viewedByOthers": false
      }
    ],
    "users": [
      {
        "id": 42,
        "active": true,
        "name": "Support",
        "bot": true,
        "type": "bot"
      },
      {
        "id": 1,
        "active": true,
        "name": "Jane Smith",
        "bot": false,
        "type": "user"
      }
    ],
    "hasPrevPage": true,
    "hasNextPage": false
  }
}

Error response example

422 — the bot type is neither personal nor supervisor:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Bot type not allowed",
    "b24Code": "BOT_TYPE_NOT_ALLOWED"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_BOT_ID DescriptionbotId is not a number
HTTP400 CodeINVALID_PARAMS DescriptionmessageId in the path must be a positive integer from 1 to 9007199254740991, without a sign, leading zeros, fraction, exponent or whitespace. Rejected before calling Bitrix24
HTTP404 CodeBOT_NOT_FOUND DescriptionNo bot found with this ID
HTTP403 CodeBOT_ACCESS_DENIED DescriptionThe bot belongs to a different API key
HTTP422 CodeBITRIX_ERROR (error.b24Code: BOT_TYPE_NOT_ALLOWED) DescriptionThe bot type is neither personal nor supervisor
HTTP422 CodeBITRIX_ERROR (error.b24Code: MESSAGE_NOT_FOUND) DescriptionNo message found with the given messageId
HTTP422 CodeBITRIX_ERROR (error.b24Code: MESSAGE_ACCESS_DENIED) DescriptionThe bot is not a participant of the chat containing this message, or has no access to the chat history
HTTP422 CodeBITRIX_ERROR DescriptionAnother Bitrix24 error, text in message
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the imbot scope
HTTP410 CodeBOT_DISABLED DescriptionThe bot is disabled and does not process API calls. How to restore it — Bot disabled
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens

Full list of common API errors — Errors.

Known specifics

Pagination: hasPrevPage and hasNextPage indicate whether there are messages beyond the window. To traverse the full history, pass the boundary id values from messages as the new messageId.

See also