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

Messenger settings

Read and change the user's general messenger settings and their status: the same settings the user sees in the Bitrix24 messenger settings window.

Scope: im | Base URL: https://vibecode.bitrix24.com/v1 | Authorization: X-Api-Key

User status

Sets the user's messenger status — "online", "do not disturb" or "away". The status changes at once in every messenger client.

Set the status

PUT /v1/chats/settings/status

The v2 messenger method im.v2.Settings.Status.update: it updates the status setting and the current status other users see. Without userId, sets the key owner's status.

Parameters

The request body is a JSON object:

Field Type Required Description
status string yes online — online, dnd — do not disturb, away — away
userId number no ID of the user whose status to set, a positive integer. Defaults to the key owner. Only a Bitrix24 administrator can change another user's status

Any other body field and any query parameter are rejected with 400 INVALID_PARAMS.

Examples

curl — personal key

Terminal 
curl -X PUT "https://vibecode.bitrix24.com/v1/chats/settings/status" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "dnd"}'

curl — OAuth application

Terminal 
curl -X PUT "https://vibecode.bitrix24.com/v1/chats/settings/status" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "online"}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/settings/status', {
  method: 'PUT',
  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ status: 'dnd' }),
})

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

JavaScript — OAuth application

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

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

Response fields

Field Type Description
success boolean Always true on success
data boolean true — the status is set

Response example

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

Error response example

400 — the status is outside the allowed set:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "`status` must be `online`, `dnd` or `away`."
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS status is missing or is not online / dnd / away, userId is not a positive integer, or another body field or query parameter was passed
401 TOKEN_MISSING The API key has no Bitrix24 tokens configured
403 SCOPE_DENIED The API key does not have the im scope
403 WRITE_BLOCKED_READONLY_KEY The key is read-only
422 BITRIX_ERROR Bitrix24 returned an error; the portal code is in error.b24Code. SETTINGS_ACCESS_DENIED — a non-administrator is changing another user's status
502 ME_ALIAS_RESOLUTION_FAILED userId was not passed, and the key owner could not be resolved
502 BITRIX_UNAVAILABLE Bitrix24 is unavailable or returned a server error

The full list of common API errors — Errors.

Known specifics

  • Only three statuses are accepted. Bitrix24 would store any other value in the setting as online and in the current status as is, and the two sources of the status would diverge. The platform therefore rejects it before calling Bitrix24.
  • The status cannot be changed through PATCH /v1/chats/settings: that would change only the setting, while the status other users see would stay the same.
  • The current status is read from the status field of the general settings.

See also