For AI agents: markdown of this page — /docs-content-en/openlines/crm-chats.md documentation index — /llms.txt

Chats by CRM card

GET /v1/openlines/crm/chats · POST /v1/openlines/sessions/intercept · POST /v1/openlines/sessions/join

Three endpoints cover the CRM-card widget flow: find the Open Channel dialogs attached to a lead, deal, company or contact, then put the current operator into the dialog you found. All three require the imopenlines scope, are available on every Bitrix24 account and do not require the imopenlines 26.700.0 update.

The chatId from the first endpoint's response is passed to the second and third endpoints unchanged. The other source of the same identifier is the sessions[].chatId field in the Session list response.

Important: sessions/intercept and sessions/join write into a live conversation with a client: after the call the operator becomes a participant in the conversation. Permissions are checked by Bitrix24, and a Bitrix24 account administrator passes that check for any dialog on the account.

Chats of a CRM card

GET /v1/openlines/crm/chats

Request parameters (query)

Parameter Type Description
crmEntityType string Required. One of lead, deal, company, contact. Case-insensitive
crmEntityId number Required. Identifier of the CRM object, a positive integer
activeOnly boolean | string Optional. true, false, Y, N, 1, 0. Without the parameter only open dialogs are returned; false adds the closed ones

Each parameter is passed exactly once and under a flat name: a repeat (crmEntityId=1&crmEntityId=2) and the bracket form (crmEntityId[]=1) are rejected with 400 INVALID_PARAMS rather than resolved in favor of one of the values.

Response fields

data is an array of rows. For an object with no Open Channel dialogs it is empty, and that is not an error. It is also empty when no object with that crmEntityId exists.

Field Type Description
chatId number Open Channel chat identifier. Goes into sessions/intercept and sessions/join as is
connectorId string | null Identifier of the channel the dialog came from
connectorTitle string | null Human-readable channel name

Example

Terminal 
curl "https://vibecode.bitrix24.com/v1/openlines/crm/chats?crmEntityType=lead&crmEntityId=1001213" \
  -H "X-Api-Key: YOUR_API_KEY"
JSON 
{
  "success": true,
  "data": [
    { "chatId": 4531, "connectorId": "telegrambot", "connectorTitle": "Telegram" }
  ]
}

The same request with activeOnly=false for an object whose dialogs are already closed returns them in the same shape — for example { "chatId": 31, "connectorId": "network", "connectorTitle": "Bitrix24 Network" }.

Intercepting a dialog

POST /v1/openlines/sessions/intercept

Moves the dialog to the current operator: the previous operator is no longer in charge of this session.

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

Successful response: { "success": true, "data": { "chatId": 4531, "intercepted": true } }.

Joining a dialog

POST /v1/openlines/sessions/join

Adds the current operator to the dialog as one more participant, leaving the previous one in place.

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

Successful response: { "success": true, "data": { "chatId": 4531, "joined": true } }.

Both endpoints accept chatId as a number (4531) or as a string in the chat4531 form; in the response the identifier is always a number. The field name is chatId or CHAT_ID; dialogId is not accepted.

Errors

HTTP Code Description
400 MISSING_PARAMS A required parameter is missing: crmEntityType, crmEntityId or chatId
400 INVALID_PARAMS A parameter value is invalid: crmEntityType outside the list, crmEntityId not a positive integer, chatId cannot be parsed into a chat identifier (a positive integer and the chat<N> form are accepted), activeOnly outside the accepted set. The same code is returned when a query parameter is passed twice or in the bracket form
401 TOKEN_MISSING The key has no configured tokens
403 SCOPE_DENIED The key has no imopenlines scope
403 WRITE_BLOCKED_READONLY_KEY The key is read-only, while sessions/intercept and sessions/join change the dialog
403 BITRIX_ACCESS_DENIED The key's user has no access to the CRM object or to the dialog
422 BITRIX_ERROR Bitrix24 rejected the request; its code is returned in error.b24Code. For sessions/join: CHAT_ID — no chat with that identifier, CHAT_TYPE — the chat is not an Open Channel. For sessions/intercept both cases give OPERATOR_WRONG. The error.message text comes from Bitrix24 verbatim: for CHAT_ID and CHAT_TYPE in the portal language, for OPERATOR_WRONG in English
429 RATE_LIMITED Two sources return this code. The first is the platform's own operation limit, counted per portal rather than per key: 300 requests per minute for crm/chats, 120 for sessions/intercept and sessions/join. Take the effective value from the X-RateLimit-Limit header, the remaining quota and the reset time from X-RateLimit-Remaining and X-RateLimit-Reset; they come with every response. The second is Bitrix24 rejecting the call under its own request rate limit: the response carries a Retry-After header
502 OPENLINE_SESSION_FAILED Bitrix24 answered without confirmation — result is not true, yet no error was returned. A closed dialog does not produce this response: joining and intercepting a closed dialog succeed
502 BITRIX_UNAVAILABLE Bitrix24 returned a response of an unexpected shape

A misspelled crmEntityType is rejected before Bitrix24 is called — with 400 INVALID_PARAMS and the list of accepted values.

Full list of common API errors — Errors.

Known specifics

  • Dialog closure is not checked. sessions/intercept and sessions/join succeed on a dialog whose session was closed long ago: the operator is added to the chat participants, the response is intercepted: true and joined: true. To work with open dialogs only, take chatId from crm/chats without activeOnly=false.
  • A repeated join is not an error. sessions/join for an operator who already participates in the dialog answers joined: true again.
  • The join is visible in the participant list. After join the operator appears among the participants of the Open Channel chat — that is the check that the call took effect.

See also