## Session history

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

`POST /v1/openlines/sessions/history`

Returns the transcript of a chat's latest Open Channel session by the chat identifier: messages, participants and file metadata in one response. The method returns customer conversation content, so it requires a key with the `imopenlines` scope and applies the Bitrix24 permission model.

## Request fields (body)

| Field | Type | Req. | Description |
|-------|------|:----:|-------------|
| `chatId` | number \| string | yes | Open Channel chat identifier. A number (`2043`) and the `chat2043` form are both accepted. Source: `chatId` from [`GET /v1/chats/recent`](/docs/chats/discovery/recent) or a bot event |
| `dialogId` | string | yes | The same chat in the `chat2043` form — an alternative to `chatId`. Either one field is enough |

Input is by chat identifier only. By it the platform takes the **latest** session of that chat — the transcript of the current dialog. An identifier of a specific historical session is not accepted as input.

The method has no pagination: the transcript is returned in full in one response. For page-by-page reading of chat messages use [`GET /v1/chats/:dialogId/messages`](/docs/chats/messages/list).

## Response fields

| Field | Type | Description |
|-------|------|-------------|
| `sessionId` | number | Identifier of the session the transcript belongs to |
| `chatId` | number | Chat identifier |
| `messages` | object[] | Messages in ascending `id` order |
| `messages[].id` | number | Message identifier |
| `messages[].senderId` | number | Sender (`0` — a system message) |
| `messages[].recipientId` | number | Recipient |
| `messages[].date` | string | Date, ISO 8601 |
| `messages[].text` | string | Message text |
| `messages[].textLegacy` | string | Text in the legacy markup format |
| `messages[].params` | object | Extra message parameters. The container is filled by the connector and is passed through as is, unchanged. It may carry the contact and CRM data of the person who wrote in |
| `users` | object[] | Dialog participants |
| `users[].id` | number | User identifier |
| `users[].name` | string | Display name |
| `users[].firstName` | string | First name |
| `users[].lastName` | string | Last name |
| `users[].workPosition` | string | Job title |
| `users[].connector` | boolean | Connector-user (customer) flag |
| `files` | object[] | Files attached to messages |
| `files[].id` | number | File identifier |
| `files[].name` | string | File name |
| `files[].size` | number | Size, bytes |
| `files[].urlDownload` | string | Download link |
| `chats` | object[] | Chat metadata |
| `chats[].dialogId` | string | Dialog identifier in the `chat<N>` form |
| `chats[].entityType` | string | Chat entity type (`LINES` for Open Channels) |
| `usersMessage` | object | A map: chat identifier → list of message identifiers |

## 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 }'
```

### Response

```json
{
  "success": true,
  "data": {
    "sessionId": 607,
    "chatId": 2043,
    "messages": [
      {
        "id": 88101,
        "senderId": 0,
        "recipientId": 13,
        "date": "2026-08-14T10:12:33+00:00",
        "text": "Hello, my invoice is not arriving",
        "textLegacy": "Hello, my invoice is not arriving",
        "params": {}
      }
    ],
    "users": [
      { "id": 13, "name": "Jane Miller", "firstName": "Jane", "lastName": "Miller", "workPosition": "Operator", "connector": false }
    ],
    "files": [],
    "chats": [
      { "dialogId": "chat2043", "entityType": "LINES" }
    ],
    "usersMessage": { "chat2043": ["88101"] }
  }
}
```

## Errors

| Code | HTTP | Reason |
|------|:----:|--------|
| `OPENLINES_HISTORY_DISABLED` | 403 | The capability is not enabled on the Vibecode platform yet |
| `SCOPE_DENIED` | 403 | The key has no `imopenlines` scope |
| `MISSING_PARAMS` | 400 | Neither `chatId` nor `dialogId` was provided, or the value is invalid |
| `ENTITY_NOT_FOUND` | 404 | There is no session for the given chat |
| `BITRIX_ACCESS_DENIED` | 403 | The key's user has no access to this dialog |