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

Join a chat

POST /v1/chats/:dialogId/join

The current user joins a chat that can be entered without an invitation — the v2 messenger method im.v2.Chat.join. This works for an open chat or channel, an Open Channel, the general chat of the Bitrix24 account, a comment chat, an external chat or an open collab. Bitrix24 posts a system message about the join in the chat.

Parameters

Parameter Type Required Description
dialogId (path) string yes Chat ID as chatN, for example chat42

The endpoint accepts no query parameters and no request body: any parameter or body field is rejected with 400 INVALID_PARAMS before any call to Bitrix24.

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/chats/chat42/join \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/chats/chat42/join \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/chat42/join', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { success, data } = await res.json()
console.log('Joined:', data.result) // true

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/chat42/join', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

Response fields

Field Type Description
success boolean Always true on success
data.result boolean true — the user is in the chat

Response example

JSON 
{
  "success": true,
  "data": {
    "result": true
  }
}

Error response example

422 — a chat of this type cannot be joined on your own:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "WRONG_MESSAGE_TYPE",
    "b24Code": "WRONG_MESSAGE_TYPE"
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS A query parameter or a body field was sent — the endpoint accepts neither
404 ENTITY_NOT_FOUND Bitrix24 returned "not found"; the portal code is in error.b24Code
422 BITRIX_ERROR Bitrix24 returned an error; the portal code is in error.b24Code. WRONG_MESSAGE_TYPE — a chat of this type cannot be joined on your own, CHAT_NOT_FOUND — the chat does not exist on the portal
502 ME_ALIAS_RESOLUTION_FAILED Failed to resolve the user when using the me alias
403 BITRIX_ACCESS_DENIED Bitrix24 refused with the ACCESS_DENIED code: the user is not allowed to join chats or has no access to this chat
403 SCOPE_DENIED The API key does not have the im scope
403 WRITE_BLOCKED_READONLY_KEY The key is read-only — see access rights
401 TOKEN_MISSING The API key has no Bitrix24 tokens configured

The full list of common API errors — Errors.

Known specifics

A closed group chat is by invitation only. A regular group chat without the open flag answers 422 BITRIX_ERROR with error.b24Code WRONG_MESSAGE_TYPE: members are added to it by a member allowed to invite — adding members. The searchable: "Y" field makes a chat open when it is created in the v2 mode.

Joining again. If you are already a member of a chat that can be entered without an invitation, the answer is the same — data.result: true. The type check comes before the membership check: in a closed chat, even a member of that chat gets WRONG_MESSAGE_TYPE.

See also