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

Add members

POST /v1/chats/:chatId/users

Adds one or more users to a group chat.

Parameters

Parameter Type Required Description
chatId (path) number yes Numeric chat ID (without the chat prefix)

Request fields (body)

Field Type Required Description
users number[] yes Array of user IDs to add
hideHistory boolean no true — new members do not see the history before they joined, default true. false — the history is open from the moment the chat was created

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/chats/123/users" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "users": [42, 53] }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/chats/123/users" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "users": [42, 53] }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/123/users', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ users: [42, 53] }),
})

const { success, data } = await res.json()
console.log('Added:', data)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/123/users', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ users: [42, 53] }),
})

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

Response fields

Field Type Description
success boolean Always true on success
data boolean true when added successfully

Response example

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

Error response example

403 — the API key does not have the im scope:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'im' scope"
  }
}

Errors

HTTP Code Description
403 SCOPE_DENIED The API key does not have the im scope
401 TOKEN_MISSING The API key has no configured Bitrix24 tokens
422 BITRIX_ERROR Bitrix24 returned an error — the text is in the message field (for example, chat not found or no permission)
502 BITRIX_UNAVAILABLE Bitrix24 is unavailable or returned a server error

Full list of common API errors — Errors.

Known specifics

Nonexistent users are skipped. If the users array contains IDs of nonexistent or inactive users, they are ignored without an error. The operation is performed for the remaining members.

History is hidden by default. When adding without an explicit hideHistory, new members do not see messages sent before they joined. To give new members access to the history from when the chat was created, pass hideHistory: false.

See also