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

Открыть чат клиента

POST /v1/openlines/sessions/open

Находит чат Открытой линии по коду клиента в коннекторе. Идентификатор найденного чата нужен, чтобы взять диалог в работу и выполнять действия оператора.

Поля запроса (body)

Поле Тип Обяз. Описание
ПолеuserCode Типstring Обяз.да ОписаниеКод клиента в коннекторе вида connector|lineId|externalChatId|userId. Передаётся без изменений. Источник: поле userCode в ответе POST /v1/openlines/sessions/search

Примеры

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

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/openlines/sessions/open \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"userCode": "doccheck|59|cloud-chat-2|1575"}'

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

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/openlines/sessions/open \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"userCode": "doccheck|59|cloud-chat-2|1575"}'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/openlines/sessions/open', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ userCode: 'doccheck|59|cloud-chat-2|1575' }),
})

const { data } = await res.json()
console.log('ID чата:', data.chatId)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/openlines/sessions/open', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ userCode: 'doccheck|59|cloud-chat-2|1575' }),
})

const { data } = await res.json()

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean Описаниеtrue при успешном ответе
Полеdata.chatId Типnumber ОписаниеИдентификатор чата Открытой линии. См. Идентификатор чата

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

JSON 
{
  "success": true,
  "data": {
    "chatId": 5255
  }
}

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

400 — не передан код клиента:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELDS",
    "message": "userCode is required and must be a non-empty string"
  }
}

Ошибки

HTTP Код Описание
HTTP400 КодMISSING_REQUIRED_FIELDS ОписаниеПоле userCode не передано, не строка, пустое или состоит из пробелов
HTTP422 КодBITRIX_ERROR ОписаниеБитрикс24 отклонил запрос. Текст отказа — в message
HTTP403 КодBITRIX_ACCESS_DENIED ОписаниеУ сотрудника, от имени которого идёт вызов, нет прав на действие, или клиента с таким userCode нет. Обе причины дают одинаковый ответ
HTTP502 КодOPENLINE_OPERATOR_FAILED ОписаниеБитрикс24 не вернул идентификатор чата
HTTP403 КодSCOPE_DENIED ОписаниеУ ключа нет скоупа imopenlines
HTTP403 КодWRITE_BLOCKED_READONLY_KEY ОписаниеКлюч работает только на чтение. Поиск чата по коду клиента требует ключа с разрешённой записью
HTTP401 КодMISSING_API_KEY ОписаниеНе передан заголовок X-Api-Key
HTTP401 КодINVALID_API_KEY ОписаниеКлюч не опознан
HTTP401 КодTOKEN_MISSING ОписаниеУ личного ключа нет доступа к порталу Битрикс24, у ключа приложения не передан токен сессии в Authorization
HTTP502 КодBITRIX_UNAVAILABLE ОписаниеБитрикс24 недоступен или соединение с ним оборвалось до полного ответа

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

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

  • Вызов не начинает сессию. Для диалога с закрытой сессией метод возвращает chatId, а сессия остаётся закрытой. Взять диалог в работу — POST /v1/openlines/sessions/start.

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