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

Switch the notification settings mode

PUT /v1/notifications/settings/scheme

Switches the employee's notification settings mode: advanced or simple. In advanced mode, each event is configured separately. In simple mode, event settings are built from general channel switches.

Important: switching to simple mode (simple) overwrites the settings of every event. Switching back to advanced mode (expert) does not restore the previous event settings. Before switching to simple mode, save the GET /v1/notifications/settings response. After the switch, event settings can be restored only with PATCH /v1/notifications/settings calls, one event channel per call.

Request fields (body)

Field Type Required Description
scheme string yes Mode: expert — advanced, simple — simple. Case-sensitive: SIMPLE is rejected
userId number no ID of the employee whose mode to switch — a positive integer. List: GET /v1/users. If omitted, the employee on whose behalf the call is made. Only a Bitrix24 administrator can switch another employee's mode

Examples

curl — personal key

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

curl — OAuth application

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

JavaScript — personal key

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

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

JavaScript — OAuth application

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

const { data } = await res.json()

Response fields

Field Type Description
success boolean Always true on success
data array The employee's settings after the switch — modules with events and channels in the same format as the get settings response

Response example

One module and some of its events are shown. The set of modules and events depends on the Bitrix24 account.

HTTP 200:

JSON 
{
  "success": true,
  "data": [
    {
      "id": "im",
      "label": "Chats and calls",
      "notices": [
        {
          "id": "message",
          "label": "Direct chat messages",
          "site": true,
          "mail": false,
          "push": false,
          "disabled": ["site"]
        },
        {
          "id": "like",
          "label": "Reactions to your messages",
          "site": false,
          "mail": false,
          "push": false,
          "disabled": ["push"]
        }
      ]
    }
  ]
}

Error response example

400 — the mode is not one of the allowed values:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Body field `scheme` must be one of: expert, simple."
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS scheme was not passed or is neither expert nor simple. Checked before the Bitrix24 call
400 INVALID_PARAMS userId is not a positive integer
400 INVALID_PARAMS The body contains a field other than scheme and userId, or the body is not a JSON object. The accepted fields are listed in message
400 INVALID_PARAMS A query parameter was passed. The operation accepts no query parameters
401 TOKEN_MISSING The key has no configured tokens
403 SCOPE_DENIED The key lacks the im scope
403 WRITE_BLOCKED_READONLY_KEY The key is in read-only mode
422 BITRIX_ERROR userId points to another employee, and the employee on whose behalf the call is made has no Bitrix24 administrator rights. The portal code SETTINGS_ACCESS_DENIED is in the error.b24Code field
502 ME_ALIAS_RESOLUTION_FAILED userId was not passed, and the employee on whose behalf the call is made could not be determined. The mode was not changed

Full list of common API errors — Errors.

See also