لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/openlines/crm-chats.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

Chats by CRM card

GET /v1/openlines/crm/chats

Returns the Open Channel chats linked to a lead, deal, company or contact. Works on any Bitrix24 account and does not require the Open Channels 26.700.0 update.

Parameters

Parameter Type Required Default Description
ParametercrmEntityType (query) Typestring Requiredyes Default— DescriptionCRM card type: lead, deal, company or contact. Case-insensitive
ParametercrmEntityId (query) Typenumber Requiredyes Default— DescriptionCRM card ID, a positive integer. Lists: GET /v1/leads, GET /v1/deals, GET /v1/companies, GET /v1/contacts
ParameteractiveOnly (query) Typeboolean | string Requiredno Defaulttrue Descriptiontrue, false, Y, N, 1, 0. Without the parameter only open dialogs are returned; false adds closed ones

Pass each parameter exactly once and under its flat name: a repeated parameter (crmEntityId=1&crmEntityId=2) and the bracket form (crmEntityId[]=1) are rejected with 400 INVALID_PARAMS. Neither value is picked.

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/openlines/crm/chats?crmEntityType=lead&crmEntityId=1001213&activeOnly=false" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/openlines/crm/chats?crmEntityType=lead&crmEntityId=1001213&activeOnly=false" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const params = new URLSearchParams({
  crmEntityType: 'lead',
  crmEntityId: '1001213',
  activeOnly: 'false',
})
const res = await fetch(`https://vibecode.bitrix24.com/v1/openlines/crm/chats?${params}`, {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { success, data, error } = await res.json()
if (!success) throw new Error(`${error.code}: ${error.message}`)
for (const chat of data) {
  console.log(chat.chatId, chat.connectorTitle)
}

JavaScript — OAuth application

javascript 
const params = new URLSearchParams({
  crmEntityType: 'lead',
  crmEntityId: '1001213',
  activeOnly: 'false',
})
const res = await fetch(`https://vibecode.bitrix24.com/v1/openlines/crm/chats?${params}`, {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()

Response fields

data is an array of chats. For a card with no Open Channel dialogs it is empty, and that is not an error. An empty array is also returned when no card with that crmEntityId exists.

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on a successful request
Fielddata[].chatId Typenumber DescriptionOpen Channel chat ID. Pass it as is to POST /v1/openlines/sessions/intercept and POST /v1/openlines/sessions/join — this is how the current operator joins the card's dialog
Fielddata[].connectorId Typestring | null DescriptionID of the channel the dialog came from
Fielddata[].connectorTitle Typestring | null DescriptionChannel name for display in the interface

Response example

Request with activeOnly=false — the card's dialog is already closed:

JSON 
{
  "success": true,
  "data": [
    { "chatId": 4531, "connectorId": "telegrambot", "connectorTitle": "Telegram" }
  ]
}

The same request without activeOnly: the card has no open dialogs.

JSON 
{
  "success": true,
  "data": []
}

Error response example

400 — card type outside the list:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "crmEntityType must be one of: lead, deal, company, contact (case-insensitive)."
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_PARAMS DescriptionA required parameter is missing: crmEntityType or crmEntityId
HTTP400 CodeINVALID_PARAMS DescriptionA parameter value is invalid: crmEntityType outside the list, crmEntityId not a positive integer, activeOnly outside the set of allowed values. The same code is returned when a query parameter is passed twice or in bracket form. The check runs before Bitrix24 is called; message lists the allowed values
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeINVALID_API_KEY DescriptionThe key is not recognized
HTTP401 CodeTOKEN_MISSING DescriptionA personal key has no access to the Bitrix24 portal, or an application key was sent without a session token in Authorization
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the imopenlines scope
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe key's user has no access to the CRM object
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 refused; its code is returned in error.b24Code
HTTP429 CodeRATE_LIMITED DescriptionThe limit of 300 requests per minute per portal, not per key, was exceeded. The limit is divided across platform replicas, so the code can arrive before the 300th request. The effective value for the key is in the x-ratelimit-limit header, the remaining quota and reset time are in x-ratelimit-remaining and x-ratelimit-reset; they come with every response
HTTP429 CodeRATE_LIMITED DescriptionBitrix24 rejected the call under its request rate limit for the portal. The response carries a Retry-After header
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable or returned a response of unexpected shape
HTTP503 CodeBITRIX_TIMEOUT DescriptionBitrix24 accepted the call but did not respond in time

Full list of common API errors — Errors.

See also