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

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

GET /v1/openlines/crm/chats

Возвращает чаты открытой линии, привязанные к лиду, сделке, компании или контакту. Работает на любом портале и не требует обновления открытых линий 26.700.0.

Общий параметр filter этим эндпоинтом не применяется. По умолчанию API сохраняет прежний ответ HTTP 200 и прежние данные, добавляет заголовок Warning: 299 - "filter is not supported on this endpoint and was ignored", а сервер фиксирует использование неподдерживаемого фильтра в журнале.

Параметры

Параметр Тип Обяз. По умолч. Описание
ПараметрcrmEntityType (query) Типstring Обяз.да По умолч.— ОписаниеТип карточки CRM: lead, deal, company или contact. Регистр не важен
ПараметрcrmEntityId (query) Типnumber Обяз.да По умолч.— ОписаниеID карточки CRM, положительное целое. Списки: GET /v1/leads, GET /v1/deals, GET /v1/companies, GET /v1/contacts
ПараметрactiveOnly (query) Типboolean | string Обяз.нет По умолч.true Описаниеtrue, false, Y, N, 1, 0. Без параметра приходят только открытые диалоги, false добавляет к ним завершённые

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

Примеры

curl — личный ключ

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

curl — OAuth-приложение

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

JavaScript — личный ключ

javascript 
const params = new URLSearchParams({
  crmEntityType: 'lead',
  crmEntityId: '1001213',
  activeOnly: 'false',
})
const res = await fetch(`https://vibecode.bitrix24.tech/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-приложение

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

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

Поля ответа

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

Поле Тип Описание
Полеsuccess Типboolean Описаниеtrue при успешном запросе
Полеdata[].chatId Типnumber ОписаниеИдентификатор чата открытой линии. Передаётся как есть в POST /v1/openlines/sessions/intercept и POST /v1/openlines/sessions/join — так текущий оператор подключается к диалогу карточки
Полеdata[].connectorId Типstring | null ОписаниеИдентификатор канала, из которого пришёл диалог
Полеdata[].connectorTitle Типstring | null ОписаниеНазвание канала для отображения в интерфейсе

Пример ответа

Запрос с activeOnly=false — диалог карточки уже завершён:

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

Тот же запрос без activeOnly: открытых диалогов у карточки нет.

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

Пример ответа при ошибке

400 — тип карточки вне списка:

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

Ошибки

HTTP Код Описание
HTTP200 КодWarning: 299 ОписаниеФильтр игнорируется по умолчанию; прежние данные сохраняются, предупреждение передаётся заголовком Warning.
HTTP400 только при включённом строгом режиме КодUNSUPPORTED_FILTER ОписаниеСерверный режим выключен по умолчанию; до его включения эндпоинт сохраняет HTTP 200 и прежние данные.
HTTP400 КодMISSING_PARAMS ОписаниеНе передан обязательный параметр: crmEntityType или crmEntityId
HTTP400 КодINVALID_PARAMS ОписаниеЗначение параметра недопустимо: crmEntityType вне списка, crmEntityId не положительное целое, activeOnly вне набора допустимых значений. Тот же код, когда параметр запроса передан дважды или в скобочной форме. Проверка идёт до вызова Битрикс24, в message приходит список допустимых значений
HTTP401 КодMISSING_API_KEY ОписаниеНе передан заголовок X-Api-Key
HTTP401 КодINVALID_API_KEY ОписаниеКлюч не опознан
HTTP401 КодTOKEN_MISSING ОписаниеУ личного ключа нет доступа к порталу Битрикс24, у ключа приложения не передан токен сессии в Authorization
HTTP403 КодSCOPE_DENIED ОписаниеУ ключа нет скоупа imopenlines
HTTP403 КодBITRIX_ACCESS_DENIED ОписаниеУ пользователя ключа нет доступа к объекту CRM
HTTP422 КодBITRIX_ERROR ОписаниеБитрикс24 отказал, его код приходит в error.b24Code
HTTP429 КодRATE_LIMITED ОписаниеПревышен лимит 300 запросов в минуту на портал, а не на ключ. Лимит делится между репликами платформы, поэтому код может прийти раньше 300-го запроса. Действующее значение для ключа — в заголовке x-ratelimit-limit, остаток и время сброса — в x-ratelimit-remaining и x-ratelimit-reset, они приходят с каждым ответом
HTTP429 КодRATE_LIMITED ОписаниеБитрикс24 отклонил вызов по лимиту частоты запросов к порталу. В ответе приходит заголовок Retry-After
HTTP502 КодBITRIX_UNAVAILABLE ОписаниеБитрикс24 недоступен или вернул ответ неожиданной формы
HTTP503 КодBITRIX_TIMEOUT ОписаниеБитрикс24 принял вызов, но не ответил за отведённое время

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

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