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

Начать сессию

POST /v1/openlines/sessions/start

Берёт диалог Открытой линии в работу: сотрудник, от имени которого идёт вызов, становится оператором сессии чата.

Действие выполняется от имени сотрудника, к которому привязан ключ, — см. От чьего имени выполняется действие.

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

Поле Тип Обяз. Описание
ПолеchatId Типnumber | string Обяз.да ОписаниеИдентификатор чата Открытой линии — положительное целое. Строка принимается, если состоит только из цифр и не начинается с нуля. См. Идентификатор чата

Примеры

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

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

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

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/openlines/sessions/start \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"chatId": 5255}'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/openlines/sessions/start', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ chatId: 5255 }),
})

const { success, data, error } = await res.json()
if (!success) throw new Error(`${error.code}: ${error.message}`)
console.log('Сессия начата:', data.started)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/openlines/sessions/start', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ chatId: 5255 }),
})

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

Поля ответа

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

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

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

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

404 — чата с таким chatId нет:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Open Line chat not found"
  }
}

Ошибки

HTTP Код Описание
HTTP400 КодINVALID_CHAT_ID ОписаниеchatId не передан, не положительное целое, строка не из одних цифр или с ведущим нулём, либо число больше 9007199254740991
HTTP404 КодENTITY_NOT_FOUND ОписаниеЧата с таким chatId нет
HTTP422 КодBITRIX_ERROR ОписаниеБитрикс24 отказал, его код приходит в error.b24Code
HTTP403 КодBITRIX_ACCESS_DENIED ОписаниеУ сотрудника, от имени которого идёт вызов, нет прав на действие
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 — Ошибки.

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

  • Закрытый чат открывается новой сессией. Если у чата нет открытой сессии, вызов создаёт новую со статусом answered, её оператор — сотрудник, от имени которого идёт вызов. Новая сессия появляется в списке сессий с тем же chatId.
  • Повторный вызов не создаёт вторую сессию. Если сотрудник уже оператор открытой сессии чата, ответ снова started: true, а сессия остаётся прежней.

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