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)
format (query) string no v2 turns on the v2 mode — see "The v2 mode" below. Any other value is ignored and the response is unchanged. A repeated format is not rejected: with format=v1&format=v2 the last value wins, so the v2 mode is on, while format=v2&format=v1 returns the legacy response. The bracket form format[]=v2 turns on the v2 mode when all its values are v2

Request fields (body)

Field Type Required Description
users number[] yes Non-empty array of user IDs to add. Each element is a positive integer: a number, or a string of decimal digits without leading zeros or spaces, up to 2^53−1; any other shape is refused before Bitrix24 is called
hideHistory boolean no true — new members do not see the history from before they joined, default true. false — the history is open from the moment the chat was created

The v2 mode. format=v2 adds the members through the v2 messenger with the same body. Only users — at most 50 IDs per request — and hideHistory are accepted: the Bitrix24 spellings USERS and HIDE_HISTORY, other body fields and query parameters are rejected with 400 INVALID_PARAMS, and hideHistory must be a boolean. The hideHistory default is the same — true. data carries { "result": true } instead of true.

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()

curl — the v2 mode

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

Response fields

Field Type Description
success boolean Always true on success
data boolean true when added successfully
data.result boolean The v2 mode: true — the request was carried out

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
400 INVALID_CHAT_ID chatId is not a positive integer — checked before the Bitrix24 call
400 MISSING_PARAMS The users field is absent or the array is empty (including a request without a body at all)
400 INVALID_PARAMS users is not an array, or one of its elements is not a positive integer in canonical form (the index and type are named in message; "047", " 47" and values above 2^53−1 are refused). In the v2 mode also users longer than 50, a query parameter other than format, a body field other than users and hideHistory, a hideHistory that is not a boolean, a body that is not a JSON object. Nothing was sent to Bitrix24
403 WRITE_BLOCKED_READONLY_KEY The key is read-only — see access rights
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

Numeric IDs only. Bitrix24 casts each element of users to a number by PHP rules: a word becomes 0 and is silently skipped with an "added" response, and a nested array crashes Bitrix24. So that a typo does not look like a success, the elements are checked on the API side: a number and a string of decimal digits without leading zeros or spaces are accepted, anything else is 400 INVALID_PARAMS.

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