Для 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 — личный ключ
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-приложение
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 — личный ключ
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-приложение
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 |
Пример ответа
{
"success": true,
"data": {
"chatId": 4531,
"joined": true
}
}
Пример ответа при ошибке
400 — chatId не передан:
{
"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. - Вход виден в списке участников. После вызова оператор появляется среди участников чата открытой линии — это и есть проверка, что вызов подействовал.