Для AI-агентов: markdown этой страницы — /docs-content/openlines/crm-chats.md индекс документации — /llms.txt

Чаты по карточке CRM

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

Три эндпоинта закрывают путь виджета в карточке CRM: найти диалоги открытой линии, привязанные к лиду, сделке, компании или контакту, а затем подключить к найденному диалогу текущего оператора. Все три требуют скоуп imopenlines, доступны на любом портале и не ждут обновления imopenlines 26.700.0.

Идентификатор chatId из ответа первого эндпоинта передаётся во второй и третий без преобразования. Второй источник того же идентификатора — поле sessions[].chatId в ответе Списка сессий.

Важно: sessions/intercept и sessions/join пишут в живой диалог с клиентом: после вызова оператор становится участником переписки. Права проверяет Битрикс24, и администратор портала проходит эту проверку для любого диалога портала.

Чаты карточки CRM

GET /v1/openlines/crm/chats

Параметры запроса (query)

Параметр Тип Описание
crmEntityType string Обязателен. Один из lead, deal, company, contact. Регистр не важен
crmEntityId number Обязателен. Идентификатор объекта CRM, положительное целое
activeOnly boolean | string Необязателен. true, false, Y, N, 1, 0. Без параметра приходят только открытые диалоги, false добавляет к ним завершённые

Каждый параметр передаётся ровно один раз и плоским именем: повтор (crmEntityId=1&crmEntityId=2) и скобочная форма (crmEntityId[]=1) отклоняются ответом 400 INVALID_PARAMS, а не разрешаются в пользу одного из значений.

Поля ответа

data — массив строк. У объекта без диалогов открытой линии он пустой, и это не ошибка. Так же пустым он приходит, когда объекта с таким crmEntityId нет.

Поле Тип Описание
chatId number Идентификатор чата открытой линии. Передаётся в sessions/intercept и sessions/join как есть
connectorId string | null Идентификатор канала, из которого пришёл диалог
connectorTitle string | null Название канала для показа человеку

Пример

Terminal 
curl "https://vibecode.bitrix24.tech/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" }
  ]
}

Тот же запрос с activeOnly=false по объекту, у которого диалоги уже завершены, отдаёт их в той же форме — например { "chatId": 31, "connectorId": "network", "connectorTitle": "Битрикс24 Network" }.

Перехват диалога

POST /v1/openlines/sessions/intercept

Переводит диалог на текущего оператора: прежний оператор перестаёт быть ведущим по этой сессии.

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

Ответ при успехе: { "success": true, "data": { "chatId": 4531, "intercepted": true } }.

Вход в диалог

POST /v1/openlines/sessions/join

Добавляет текущего оператора в диалог ещё одним участником, не снимая прежнего.

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

Ответ при успехе: { "success": true, "data": { "chatId": 4531, "joined": true } }.

Оба эндпоинта принимают chatId числом (4531) и строкой формы chat4531, в ответе идентификатор всегда число. Имя поля — chatId или CHAT_ID, dialogId не принимается.

Ошибки

HTTP Код Описание
400 MISSING_PARAMS Не передан обязательный параметр: crmEntityType, crmEntityId или chatId
400 INVALID_PARAMS Значение параметра недопустимо: crmEntityType вне списка, crmEntityId не положительное целое, chatId не разбирается в идентификатор чата (принимаются положительное целое и форма chat<N>), activeOnly вне набора допустимых значений. Тот же код, когда параметр запроса передан дважды или в скобочной форме
401 TOKEN_MISSING У ключа нет настроенных токенов
403 SCOPE_DENIED У ключа нет скоупа imopenlines
403 WRITE_BLOCKED_READONLY_KEY Ключ работает только на чтение, а sessions/intercept и sessions/join меняют диалог
403 BITRIX_ACCESS_DENIED У пользователя ключа нет доступа к объекту CRM или к диалогу
422 BITRIX_ERROR Битрикс24 отказал, его код приходит в error.b24Code. У sessions/join: CHAT_ID — чата с таким идентификатором нет, CHAT_TYPE — чат не является открытой линией. У sessions/intercept оба случая дают OPERATOR_WRONG. Текст error.message приходит от Битрикс24 дословно: для CHAT_ID и CHAT_TYPE — на языке портала, для OPERATOR_WRONG — по-английски
429 RATE_LIMITED Код отдают два источника. Первый — собственный лимит операций, считается на портал, а не на ключ: 300 запросов в минуту у crm/chats, 120 — у sessions/intercept и sessions/join. Действующее значение берите из заголовка X-RateLimit-Limit, остаток и время сброса — из X-RateLimit-Remaining и X-RateLimit-Reset, они приходят с каждым ответом. Второй — Битрикс24, отбивший вызов по лимиту частоты: приходит заголовок Retry-After
502 OPENLINE_SESSION_FAILED Битрикс24 ответил без подтверждения — result не true, при этом ошибку не вернул. Завершённость диалога такого ответа не даёт: вход и перехват на завершённом диалоге проходят успешно
502 BITRIX_UNAVAILABLE Битрикс24 вернул ответ неожиданной формы

Опечатка в crmEntityType отбивается до вызова Битрикс24 — ответом 400 INVALID_PARAMS со списком допустимых значений.

Полный список общих ошибок API — Ошибки.

Известные особенности

  • Завершённость диалога не проверяется. sessions/intercept и sessions/join проходят и на диалоге, сессия которого давно закрыта: оператор добавляется в участники чата, ответ — intercepted: true и joined: true. Хотите работать только с открытыми диалогами — берите chatId из crm/chats без activeOnly=false.
  • Повторный вход не ошибка. sessions/join для оператора, который уже участвует в диалоге, снова отвечает joined: true.
  • Вход виден в списке участников. После join оператор появляется среди участников чата открытой линии — это и есть проверка, что вызов подействовал.

Смотрите также