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

User status

Sets the user's messenger status — "online", "do not disturb" or "away".

Set the status

PUT /v1/chats/settings/status

Updates both the status setting and the current status other users see.

Request fields (body)

The request body is a JSON object:

Field Type Required Description
Fieldstatus Typestring Requiredyes Descriptiononline — online, dnd — do not disturb, away — away
FielduserId Typenumber Requiredno DescriptionID 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. User list: GET /v1/users

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": "dnd"}'

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: 'dnd' }),
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeboolean Descriptiontrue — 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
HTTP400 CodeINVALID_PARAMS Descriptionstatus is missing
HTTP400 CodeINVALID_PARAMS Descriptionstatus is not online, dnd or away
HTTP400 CodeINVALID_PARAMS DescriptionuserId is not a positive integer
HTTP400 CodeINVALID_PARAMS DescriptionThe request body is not a JSON object
HTTP400 CodeINVALID_PARAMS DescriptionThe body contains a field other than status and userId
HTTP400 CodeINVALID_PARAMS DescriptionA query parameter was passed — the method accepts none
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no Bitrix24 tokens configured
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the im scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned an error; the portal code is in error.b24Code. SETTINGS_ACCESS_DENIED — a non-administrator is changing another user's status
HTTP502 CodeME_ALIAS_RESOLUTION_FAILED DescriptionuserId was not passed, and the key owner could not be resolved
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable or returned a server error

The full list of common API errors — Errors.

Known specifics

  • The platform rejects status values other than online, dnd and away before calling Bitrix24: otherwise the status setting and the current status would diverge.
  • 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 returned in the status field when you read the settings.

See also