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. Used to analyze dialog 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 a regular bot, Bitrix24 returns 422 BITRIX_ERROR: Method is available only for supervisor and personal bots. The type is set during registration via POST /v1/bots and cannot be changed without re-registration.

Parameters

Parameter Type Required Description
botId (path) number yes Bot ID
messageId (path) number yes ID of the central message
range (query) number no Number 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=20" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/bots/42/messages/1501/context?range=20" \
  -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=20', {
  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=20', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

Response fields

Field Type Description
messages array Array of messages around the central one
messages[].id number Message ID
messages[].chatId number Chat ID
messages[].authorId number Author ID
messages[].date string Send date (ISO 8601)
messages[].text string Message text
hasPrevPage boolean There are more messages before the window
hasNextPage boolean There are more messages after the window

Response example

JSON 
{
  "success": true,
  "data": {
    "messages": [
      {
        "id": 1499,
        "chatId": 123,
        "authorId": 3,
        "date": "2026-03-31T09:58:00+00:00",
        "text": "Team, I have a question about the task"
      },
      {
        "id": 1500,
        "chatId": 123,
        "authorId": 1,
        "date": "2026-03-31T09:59:00+00:00",
        "text": "Let's discuss it"
      },
      {
        "id": 1501,
        "chatId": 123,
        "authorId": 1,
        "date": "2026-03-31T10:00:00+00:00",
        "text": "Hi, bot!"
      }
    ],
    "hasPrevPage": true,
    "hasNextPage": false
  }
}

Error response example

502 — the bot has no access:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Access denied"
  }
}

Errors

HTTP Code Description
400 INVALID_BOT_ID botId is not a number
404 BOT_NOT_FOUND No bot found with this ID
403 BOT_ACCESS_DENIED The bot belongs to a different API key
502 BITRIX_ERROR Bitrix24 error (error text in message)
403 SCOPE_DENIED The API key does not have the imbot scope
401 TOKEN_MISSING The API key has no configured tokens

Full list of common API errors — Errors.

Known specifics

Only personal and supervisor: like GET /messages/:messageId, the method is available only for bots of type personal and supervisor.

Pagination: hasPrevPage and hasNextPage indicate whether there are messages beyond the window. For a full traversal you can use the boundary id values from messages as a new messageId.

See also