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

Remove a member

DELETE /v1/chats/:chatId/users

Removes one user from 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
userId number yes ID of the user to remove — 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

The v2 mode. format=v2 removes the member through the v2 messenger with the same body { "userId": … }. The Bitrix24 spelling USER_ID, other body fields and query parameters are rejected with 400 INVALID_PARAMS. data carries { "result": true } instead of true. Removing a user who is not in the chat returns 422 BITRIX_ERROR with error.b24Code USER_NOT_FOUND.

Examples

curl — personal key

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

curl — OAuth application

Terminal 
curl -X DELETE "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 '{ "userId": 42 }'

JavaScript — personal key

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

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

JavaScript — OAuth application

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

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

curl — the v2 mode

Terminal 
curl -X DELETE "https://vibecode.bitrix24.com/v1/chats/123/users?format=v2" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "userId": 42 }'

Response fields

Field Type Description
success boolean Always true on success
data boolean true when removed successfully
data.result boolean The v2 mode: true — the member was removed

Response example

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

Error response example

422 — the user is not a member of the chat:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "The specified user is not a member of the chat"
  }
}

Errors

HTTP Code Description
400 INVALID_CHAT_ID chatId is not a positive integer — checked before the Bitrix24 call
400 MISSING_PARAMS The userId field is absent (including a request with no body at all)
400 INVALID_PARAMS userId is not a positive integer in canonical form — an array, a word, zero, a negative or fractional value, a value with leading zeros or spaces, or a value above 2^53−1. In the v2 mode also a query parameter other than format, a body field other than userId, 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, the user is not a member of the chat, or there is no permission). In the v2 mode the portal code arrives in error.b24Code
502 BITRIX_UNAVAILABLE Bitrix24 is unavailable or returned a server error

Full list of common API errors — Errors.

Known specifics

One member at a time. The endpoint accepts a single userId (a number), not an array. To remove several members, call the method for each one separately.

Numeric ID only. Bitrix24 casts userId to a number by PHP rules: the array [47] becomes 1 — the user with ID 1, usually the Bitrix24 account owner, would be removed from the chat instead of user 47. So the shape of the value is 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.

Only chatId and userId travel to Bitrix24. Other fields of the request body are not forwarded to Bitrix24 — including native upper-case Bitrix24 keys. Bitrix24 folds parameter names case-insensitively and the last key wins: the body {"USER_ID": 47, "user_id": [1]} would pass the check on USER_ID, yet the alias would win in Bitrix24 — the user with ID 1 would be removed from the chat.

See also