## 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](/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=20" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
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](/docs/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

- [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)