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

Войти в диалог

POST /v1/openlines/sessions/join

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

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

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

Поле Тип Обяз. Описание
ПолеchatId Типnumber | string Обяз.да ОписаниеИдентификатор чата открытой линии: число (4531) или строка формы chat4531. Вместо chatId принимается CHAT_ID, а dialogId не принимается. Источники: GET /v1/openlines/crm/chats по карточке CRM, поле sessions[].chatId в ответе POST /v1/openlines/sessions/search

Примеры

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

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 }'

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

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

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

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

const { success, data, error } = await res.json()
if (!success) throw new Error(`${error.code}: ${error.message}`)
console.log('Вошёл:', data.joined)

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

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

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

Поля ответа

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

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

JSON
{
  "success": true,
  "data": {
    "chatId": 4531,
    "joined": true
  }
}

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

400 — chatId не передан:

JSON
{
  "success": false,
  "error": {
    "code": "MISSING_PARAMS",
    "message": "A chat id is required — pass one of: chatId, CHAT_ID. Take it from `data.chat.id` of the bot event (its `data.dialogId` twin is the same id prefixed with `chat`), or from `sessions[].chatId` of POST /v1/openlines/sessions/search."
  }
}

Ошибки

HTTP Код Описание
HTTP400 КодMISSING_PARAMS ОписаниеНе передан chatId
HTTP400 КодINVALID_PARAMS ОписаниеchatId не разбирается в идентификатор чата: принимаются положительное целое и форма chat<N>. Тот же код, когда тело запроса не JSON-объект
HTTP400 КодINVALID_JSON_BODY ОписаниеТело запроса не разбирается как JSON
HTTP401 КодMISSING_API_KEY ОписаниеНе передан заголовок X-Api-Key
HTTP401 КодINVALID_API_KEY ОписаниеКлюч не опознан
HTTP401 КодTOKEN_MISSING ОписаниеУ личного ключа нет доступа к порталу Битрикс24, у ключа приложения не передан токен сессии в Authorization
HTTP403 КодSCOPE_DENIED ОписаниеУ ключа нет скоупа imopenlines
HTTP403 КодWRITE_BLOCKED_READONLY_KEY ОписаниеКлюч работает только на чтение, а sessions/join меняет диалог
HTTP403 КодBITRIX_ACCESS_DENIED ОписаниеУ пользователя ключа нет доступа к диалогу
HTTP422 КодBITRIX_ERROR ОписаниеБитрикс24 отказал, его код приходит в error.b24Code: CHAT_ID — чата с таким идентификатором нет, CHAT_TYPE — чат не является открытой линией. Текст error.message приходит от Битрикс24 дословно, на языке портала
HTTP429 КодRATE_LIMITED ОписаниеКод возвращают два источника. Первый — собственный лимит операций: потолок платформы 120 запросов в минуту на портал, а не на ключ, делится на реплики. Действующее значение берите из заголовка x-ratelimit-limit, остаток и время сброса — из x-ratelimit-remaining и x-ratelimit-reset, они приходят с каждым ответом. Второй — Битрикс24, отклонивший вызов по лимиту частоты: приходит заголовок Retry-After
HTTP502 КодOPENLINE_SESSION_FAILED ОписаниеБитрикс24 ответил без подтверждения — result не true, при этом ошибку не вернул
HTTP502 КодBITRIX_UNAVAILABLE ОписаниеБитрикс24 недоступен или вернул ответ неожиданной формы
HTTP503 КодBITRIX_TIMEOUT ОписаниеБитрикс24 принял вызов, но не ответил за отведённое время. Вызов при этом мог выполниться

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

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

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

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