## 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](/docs/bots/management/create) 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

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

### curl — OAuth application

```bash
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 |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data` | object | The message window and its authors |
| `data.messages` | array | The central message and up to `range` messages on each side, in ascending `id` order |
| `data.messages[].id` | number | Message ID |
| `data.messages[].chatId` | number | Chat ID |
| `data.messages[].authorId` | number | Author ID. The author's profile is in `data.users` |
| `data.messages[].date` | string | Date the message was sent (ISO 8601) |
| `data.messages[].text` | string | Message text. An empty string for a message that contains only a file |
| `data.messages[].isSystem` | boolean | System message |
| `data.messages[].params` | object \| array | Additional message parameters. `FILE_ID` is an array of file IDs; to download a file, see [Download file](/docs/bots/files/download). An empty array if there are no parameters |
| `data.messages[].forward` | object \| null | Forwarding data. `null` for a message that was not forwarded |
| `data.messages[].viewedByOthers` | boolean | Whether other participants have read the message |
| `data.users` | array | Profiles of the authors of the messages in `data.messages`. Profile fields are the same as in [List participants](/docs/bots/chats/user-list) |
| `data.hasPrevPage` | boolean | `true` if more messages exist before the window |
| `data.hasNextPage` | boolean | `true` 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 |
|------|-----|---------|
| 400 | `INVALID_BOT_ID` | `botId` is not a number |
| 400 | `INVALID_PARAMS` | `messageId` 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 |
| 404 | `BOT_NOT_FOUND` | No bot found with this ID |
| 403 | `BOT_ACCESS_DENIED` | The bot belongs to a different API key |
| 422 | `BITRIX_ERROR` (`error.b24Code: BOT_TYPE_NOT_ALLOWED`) | The bot type is neither `personal` nor `supervisor` |
| 422 | `BITRIX_ERROR` (`error.b24Code: MESSAGE_NOT_FOUND`) | No message found with the given `messageId` |
| 422 | `BITRIX_ERROR` (`error.b24Code: MESSAGE_ACCESS_DENIED`) | The bot is not a participant of the chat containing this message, or has no access to the chat history |
| 422 | `BITRIX_ERROR` | Another Bitrix24 error, text in `message` |
| 403 | `SCOPE_DENIED` | The API key does not have the `imbot` scope |
| 410 | `BOT_DISABLED` | The bot is disabled and does not process API calls. How to restore it — [Bot disabled](/docs/bots/troubleshooting#bot-disabled-bot_disabled) |
| 401 | `TOKEN_MISSING` | The API key has no configured tokens |

Full list of common API errors — [Errors](/docs/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

- [Get message](/docs/bots/messages/get)
- [Read messages](/docs/bots/messages/read)
- [Events](/docs/bots/events)
- [Bot platform](/docs/bots)
- [Limits and optimization](/docs/optimization)