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

Transfer chat ownership

POST /v1/chats/:chatId/owner

Transfers ownership of a group chat to another participant. The new owner must already be a member of the chat.

Parameters

Parameter Type Required Description
chatId (path) number yes Chat ID (positive integer)
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 transfer ownership to. The user must be a participant in the chat. Participant list: GET /v1/chats/:chatId/users

The v2 mode. format=v2 transfers ownership through the v2 messenger, with the same body { "userId": … } and the same response true. The Bitrix24 spelling USER_ID, other body fields and query parameters are rejected with 400 INVALID_PARAMS. Before the transfer the API checks that the new owner is in the chat: a user who is not in the chat is rejected with 400 INVALID_PARAMS, and ownership does not change.

Examples

curl — personal key

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

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/chats/456/owner \
  -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/456/owner', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ userId: 42 }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/456/owner', {
  method: 'POST',
  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 POST "https://vibecode.bitrix24.com/v1/chats/456/owner?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 ownership was transferred successfully

Response example

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

Error response example

422 — the ownership transfer condition was violated:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Change owner can only owner and user must be member in 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 missing or is not a positive integer
400 INVALID_PARAMS The v2 mode only: a query parameter other than format, a body field other than userId, a body that is not a JSON object, or a userId outside the chat. Ownership does not change
403 BITRIX_ACCESS_DENIED No permission to transfer ownership of this chat
403 WRITE_BLOCKED_READONLY_KEY The key is read-only — see access rights
422 BITRIX_ERROR Only the current owner can transfer ownership, and the new owner must be a chat participant. In the v2 mode — Bitrix24 did not save the change; the portal code is in error.b24Code
502 BITRIX_UNAVAILABLE Bitrix24 is unavailable or returned a server error
403 SCOPE_DENIED The API key lacks the im scope
401 TOKEN_MISSING The API key has no configured tokens

Full list of common API errors — Errors.

Known specifics

If the target user is not yet in the chat, add them via POST /v1/chats/:chatId/users before calling this endpoint.

Owner leaving the chat. The chat creator remains the owner even after calling POST /v1/chats/:chatId/leave — leaving does not remove the owner status. To leave a chat completely: first transfer ownership to another participant with this endpoint, then call leave.

The transfer cannot be undone by you. The former owner stays in the chat, but only the new owner can give ownership back: a repeated call from the former owner gets 403 BITRIX_ACCESS_DENIED.

See also