## Session history

> **This endpoint is being enabled gradually by the Vibecode platform.** Until it is enabled on the platform, the call returns `403 OPENLINES_HISTORY_DISABLED` — a sign that the capability is not active yet, not an integration error.

`POST /v1/openlines/sessions/history`

Returns the conversation of the latest session of an Open Channel chat in one response. Suited for reviewing a client's request as a whole: messages, their authors and attached files come together.

## Request fields (body)

Pass one of the two fields.

| Field | Type | Required | Description |
|------|-----|:-----:|---------|
| `chatId` | number \| string | no | Open Channel chat identifier: the number `2043` or the string `chat2043`. Source: `sessions[].chatId` in the [`POST /v1/openlines/sessions/search`](/docs/openlines/sessions/search) response, `chatId` from [`GET /v1/openlines/crm/chats`](/docs/openlines/crm-chats), or from a bot event |
| `dialogId` | string | no | The same chat, only in the `chat2043` form. A number in this field is rejected with `400 MISSING_PARAMS` |

The only input is the chat identifier. From it, the platform takes the **latest** session of that chat — that is, the conversation of the current dialog. The identifier of a specific past session is not accepted as input.

The method has no pagination: the conversation is returned in full in one response. To read chat messages page by page, use [`GET /v1/chats/:dialogId/messages`](/docs/chats/messages/list).

## Examples

### curl — personal key

```bash
curl -X POST "https://vibecode.bitrix24.com/v1/openlines/sessions/history" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "chatId": 2043 }'
```

### curl — OAuth application

```bash
curl -X POST "https://vibecode.bitrix24.com/v1/openlines/sessions/history" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "chatId": 2043 }'
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/openlines/sessions/history', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ chatId: 2043 }),
})
const { data } = await res.json()
for (const message of data.messages) {
  console.log(message.date, message.senderId, message.text)
}
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/openlines/sessions/history', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ chatId: 2043 }),
})
const { data } = await res.json()
```

## Response fields

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | `true` on a successful request |
| `data.sessionId` | number | Identifier of the session the conversation belongs to. Session metrics — [`POST /v1/openlines/sessions/stats`](/docs/openlines/sessions/stats) |
| `data.chatId` | number | Chat identifier |
| `data.messages` | object[] | Session messages in ascending `id` order |
| `data.messages[].id` | number | Message identifier |
| `data.messages[].chatId` | number | Chat identifier |
| `data.messages[].senderId` | number | Message author, `0` for a system message. Author data is the `data.users[]` element with the same `id` |
| `data.messages[].recipientId` | string | Recipient — the chat in the `chat<N>` form |
| `data.messages[].date` | string | Send date, ISO 8601 |
| `data.messages[].text` | string | Message text with BB-code markup |
| `data.messages[].textLegacy` | string | The same text with HTML markup |
| `data.messages[].params` | object \| array \| null | Additional message parameters. The container is filled by the connector, and its contents are passed through as is, unchanged. It may carry the contact and CRM data of the person who wrote in. A message without parameters carries an empty array `[]` |
| `data.users` | object[] | Message authors, except system ones |
| `data.users[].id` | number | User identifier |
| `data.users[].name` | string | Display name |
| `data.users[].firstName` | string | First name |
| `data.users[].lastName` | string | Last name |
| `data.users[].workPosition` | string \| null | Job title |
| `data.users[].avatar` | string | Avatar image URL |
| `data.users[].gender` | string | Gender: `M` or `F` |
| `data.users[].extranet` | boolean | External user flag |
| `data.users[].connector` | boolean | `true` for a client who came through a connector |
| `data.users[].type` | string | User type, for example `user` for an employee and `extranet` for a client |
| `data.files` | object[] | Files attached to messages |
| `data.files[].id` | number | File identifier |
| `data.files[].chatId` | number | Chat identifier |
| `data.files[].date` | string | Upload date, ISO 8601 |
| `data.files[].type` | string | File type, for example `image` |
| `data.files[].name` | string | File name |
| `data.files[].extension` | string | File extension |
| `data.files[].size` | number | Size in bytes |
| `data.files[].status` | string | Upload status, `done` for an uploaded file |
| `data.files[].authorId` | number | Identifier of the file author |
| `data.files[].authorName` | string | Author name |
| `data.files[].isVoiceNote` | boolean | Voice message |
| `data.files[].isVideoNote` | boolean | Video message |
| `data.files[].isTranscribable` | boolean | Whether a transcript is available |
| `data.files[].urlPreview` | string | Link to the thumbnail |
| `data.files[].urlShow` | string | Link for viewing |
| `data.files[].urlDownload` | string | Download link |
| `data.chats` | object[] | Chat metadata |
| `data.chats[].id` | number | Chat identifier |
| `data.chats[].dialogId` | string | Dialog identifier in the `chat<N>` form |
| `data.chats[].name` | string | Chat name |
| `data.chats[].type` | string | Chat type, `lines` for an Open Channel |
| `data.chats[].entityType` | string | Chat entity type, `LINES` for an Open Channel |
| `data.chats[].messageCount` | number | Number of messages in the chat across all sessions |
| `data.chats[].dateCreate` | string | Chat creation date, ISO 8601. For the same chat it may differ from the creation date in [dialog metadata](/docs/openlines/dialog): the values are returned without normalization, so take the creation time from one endpoint only |
| `data.usersMessage` | object | A map: dialog identifier `chat<N>` → session message identifiers as strings |

## Response example

```json
{
  "success": true,
  "data": {
    "sessionId": 607,
    "chatId": 2043,
    "messages": [
      {
        "id": 88101,
        "chatId": 2043,
        "senderId": 0,
        "recipientId": "chat2043",
        "date": "2026-08-14T10:12:30+00:00",
        "text": "The request was sent to all queue members",
        "textLegacy": "The request was sent to all queue members",
        "params": []
      },
      {
        "id": 88103,
        "chatId": 2043,
        "senderId": 1211,
        "recipientId": "chat2043",
        "date": "2026-08-14T10:12:33+00:00",
        "text": "Hello, my invoice is not arriving",
        "textLegacy": "Hello, my invoice is not arriving",
        "params": { "connectorMid": ["88099"] }
      },
      {
        "id": 88107,
        "chatId": 2043,
        "senderId": 13,
        "recipientId": "chat2043",
        "date": "2026-08-14T10:13:05+00:00",
        "text": "[b]Good afternoon![/b] Checking the invoice",
        "textLegacy": "<b>Good afternoon!</b> Checking the invoice",
        "params": { "connectorMid": ["88109"] }
      }
    ],
    "users": [
      {
        "id": 13,
        "name": "Jane Miller",
        "firstName": "Jane",
        "lastName": "Miller",
        "workPosition": "Operator",
        "avatar": "/bitrix/js/im/images/blank.gif",
        "gender": "F",
        "extranet": false,
        "connector": false,
        "type": "user"
      },
      {
        "id": 1211,
        "name": "Guest",
        "firstName": "Guest",
        "lastName": "",
        "workPosition": null,
        "avatar": "/bitrix/js/im/images/blank.gif",
        "gender": "M",
        "extranet": true,
        "connector": true,
        "type": "extranet"
      }
    ],
    "files": [],
    "chats": [
      {
        "id": 2043,
        "dialogId": "chat2043",
        "name": "Guest - Open Channel",
        "type": "lines",
        "entityType": "LINES",
        "messageCount": 36,
        "dateCreate": "2026-08-14T10:12:30+00:00"
      }
    ],
    "usersMessage": { "chat2043": ["88107", "88103", "88101"] }
  }
}
```

## Error response example

422 — the session cannot be determined from the chat: the chat does not exist or does not belong to an Open Channel:

```json
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Unable to determine session ID from provided parameters",
    "b24Code": "INVALID_SESSION_ID"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 400 | `MISSING_PARAMS` | Neither `chatId` nor `dialogId` was passed. A body with only `sessionId` gets the same response |
| 400 | `MISSING_PARAMS` | The value is invalid: `chatId` is neither a positive integer nor a `chat<N>` string, `dialogId` is not in the `chat<N>` form |
| 400 | `INVALID_PARAMS` | The request body is not a JSON object |
| 400 | `INVALID_JSON_BODY` | The request body did not parse as JSON |
| 401 | `TOKEN_MISSING` | The key has no configured Bitrix24 tokens |
| 403 | `OPENLINES_HISTORY_DISABLED` | The capability is not enabled on the Vibecode platform yet |
| 403 | `SCOPE_DENIED` | The key has no `imopenlines` scope |
| 403 | `BITRIX_ACCESS_DENIED` | The key's user has no access to this dialog |
| 404 | `ENTITY_NOT_FOUND` | Bitrix24 returned an empty result instead of the session history |
| 422 | `BITRIX_ERROR` | `error.b24Code` equals `INVALID_SESSION_ID`: there is no chat with this identifier, or it does not belong to an Open Channel |
| 429 | `RATE_LIMITED` | The method's own limit was exceeded: the platform ceiling of 120 requests per minute applies per Bitrix24 account, not per key, and is split across replicas. The effective value comes in the `x-ratelimit-limit` header |
| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 returned a response of an unexpected shape |

Full list of common API errors — [Errors](/docs/errors).

## See also

- [Dialog metadata](/docs/openlines/dialog)
- [Session search](/docs/openlines/sessions/search)
- [Chats by CRM card](/docs/openlines/crm-chats)
- [Read messages](/docs/chats/messages/list)
- [Open Channels](/docs/openlines)