## Dialog metadata `POST /v1/openlines/dialogs/lookup` Finds an Open Channel dialog by a chat or session identifier and returns its card together with the Open Channel identifier. The method does not return the conversation; it is available through the session history. ## Request fields (body) Pass exactly one of the three 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, or [`GET /v1/openlines/crm/chats`](/docs/openlines/crm-chats) for a CRM card | | `dialogId` | string | no | The same chat, only in the `chat2043` form. A number in this field is rejected with `400 INVALID_PARAMS` | | `sessionId` | number \| string | no | Open Channel session identifier — a positive integer; a string of digits is also accepted. Source: `sessions[].id` in the [`POST /v1/openlines/sessions/search`](/docs/openlines/sessions/search) response | ## Examples ### curl — personal key ```bash curl -X POST "https://vibecode.bitrix24.com/v1/openlines/dialogs/lookup" \ -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/dialogs/lookup" \ -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/dialogs/lookup', { method: 'POST', headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ chatId: 2043 }), }) const { data } = await res.json() console.log(data.lineId) ``` ### JavaScript — OAuth application ```javascript const res = await fetch('https://vibecode.bitrix24.com/v1/openlines/dialogs/lookup', { 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.id` | number | Chat identifier of the dialog | | `data.dialogId` | string | Dialog identifier in the `chat` form | | `data.name` | string | Dialog name | | `data.description` | string \| null | Dialog description | | `data.type` | string | Chat type, `lines` for an Open Channel | | `data.entityType` | string | Chat entity type, `LINES` for an Open Channel | | `data.messageCount` | number | Number of messages in the dialog | | `data.lastMessageId` | number | Identifier of the last message | | `data.dateCreate` | string | Dialog creation date, ISO 8601. For the same chat it may differ from the creation date in [session history](/docs/openlines/history): the values are returned without normalization, so take the creation time from one endpoint only | | `data.textFieldEnabled` | boolean | Whether the message input field is available | | `data.isNew` | boolean | New dialog flag | | `data.lineId` | number \| null | Open Channel identifier. Full Open Channel configuration — [`GET /v1/openline-configs/:id`](/docs/openlines/config/get). `null` if the Open Channel could not be determined | ## Response example ```json { "success": true, "data": { "id": 2043, "dialogId": "chat2043", "name": "Telegram: John", "description": null, "type": "lines", "entityType": "LINES", "messageCount": 36, "lastMessageId": 2109, "dateCreate": "2026-08-14T10:12:30+00:00", "textFieldEnabled": true, "isNew": false, "lineId": 1 } } ``` ## Error response example 403 — there is no dialog with this identifier, or the key's user has no access to it: ```json { "success": false, "error": { "code": "BITRIX_ACCESS_DENIED", "message": "You do not have access to this Open Line dialog", "hint": "Bitrix24 refused imopenlines.dialog.get with ACCESS_ERROR. Two possible causes: (1) the Open Line dialog does not exist, or (2) the Bitrix24 user this call runs as has no access to it. The cause is not determined; check the dialog identifier and whether that user can open this dialog in Bitrix24.", "cause": "unknown", "method": "imopenlines.dialog.get", "fix": { "action": "none" } } } ``` ## Errors | HTTP | Code | Description | |------|-----|---------| | 400 | `MISSING_PARAMS` | None of the identifiers `chatId`, `dialogId`, `sessionId` was passed | | 400 | `INVALID_PARAMS` | A chat identifier and `sessionId` were passed at the same time | | 400 | `INVALID_PARAMS` | The identifier value is invalid: `chatId` or `sessionId` is not a positive integer, `dialogId` is not in the `chat` 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 | `SCOPE_DENIED` | The key has no `imopenlines` scope | | 403 | `BITRIX_ACCESS_DENIED` | The dialog does not exist, the chat does not belong to an Open Channel, or the key's user has no access to the dialog. The response does not distinguish the cause; the `hint` field names both causes | | 404 | `ENTITY_NOT_FOUND` | Bitrix24 returned an empty result instead of the dialog card | | 429 | `RATE_LIMITED` | The method's own limit was exceeded: the platform ceiling of 300 requests per minute applies per portal, 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 - [Session history](/docs/openlines/history) - [Session search](/docs/openlines/sessions/search) - [Get Open Channel configuration](/docs/openlines/config/get) - [Chats by CRM card](/docs/openlines/crm-chats) - [Open Channels](/docs/openlines)