For AI agents: markdown of this page — /docs-content-en/openlines/sessions/join.md documentation index — /llms.txt

Join a dialog

POST /v1/openlines/sessions/join

Adds the current operator to the dialog as one more participant without removing the previous one. Works on any Bitrix24 account and does not wait for the imopenlines 26.700.0 update.

Important: the call changes a live dialog with the client — after it, the operator becomes a participant in the conversation. Permissions are checked by Bitrix24, and a Bitrix24 account administrator passes this check for any dialog in the account.

Request fields (body)

Field Type Required Description
FieldchatId Typenumber | string Requiredyes DescriptionOpen Channel chat identifier: a number (4531) or a string of the form chat4531. CHAT_ID is accepted instead of chatId, but dialogId is not. Sources: GET /v1/openlines/crm/chats by CRM card, the sessions[].chatId field in the POST /v1/openlines/sessions/search response

Examples

curl — personal key

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

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/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 — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/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('Joined:', data.joined)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/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()

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on a successful join
Fielddata.chatId Typenumber DescriptionChat identifier from the request. The chat4531 form is returned as a number
Fielddata.joined Typeboolean DescriptionAlways true

Response example

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

Error response example

400 — chatId was not passed:

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."
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_PARAMS DescriptionchatId was not passed
HTTP400 CodeINVALID_PARAMS DescriptionchatId does not parse into a chat identifier: a positive integer and the chat<N> form are accepted. The same code when the request body is not a JSON object
HTTP400 CodeINVALID_JSON_BODY DescriptionThe request body does not parse as JSON
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not passed
HTTP401 CodeINVALID_API_KEY DescriptionThe key was not recognized
HTTP401 CodeTOKEN_MISSING DescriptionThe personal key has no access to the Bitrix24 account, or the application key was sent without a session token in Authorization
HTTP403 CodeSCOPE_DENIED DescriptionThe key has no imopenlines scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only, while sessions/join changes the dialog
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe key's user has no access to the dialog
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 refused, and its code comes in error.b24Code: CHAT_ID — a chat with this identifier does not exist, CHAT_TYPE — the chat is not an Open Channel. The error.message text comes from Bitrix24 verbatim, in the Bitrix24 account language
HTTP429 CodeRATE_LIMITED DescriptionTwo sources return this code. The first is the platform's own operation limit: a platform ceiling of 120 requests per minute per Bitrix24 account rather than per key, split across replicas. Take the effective value from the x-ratelimit-limit header, the remaining quota and the reset time from x-ratelimit-remaining and x-ratelimit-reset. These headers come with every response. The second is Bitrix24 rejecting the call under its request rate limit: the response carries a Retry-After header
HTTP502 CodeOPENLINE_SESSION_FAILED DescriptionBitrix24 responded without confirmation — result is not true, yet it returned no error
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable or returned a response of an unexpected shape
HTTP503 CodeBITRIX_TIMEOUT DescriptionBitrix24 accepted the call but did not respond within the allotted time. The call may still have been executed

Full list of common API errors: Errors.

Known specifics

  • Dialog completion is not checked. Joining succeeds even on a dialog whose session closed long ago: the operator is added to the chat participants, and the response is joined: true. To work only with open dialogs, take chatId from GET /v1/openlines/crm/chats without activeOnly=false.
  • Joining again is not an error. Calling it for an operator who is already in the dialog returns joined: true again.
  • The join is visible in the participant list. After the call, the operator appears among the Open Channel chat participants — this is how to check that the call took effect.

See also