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
Fieldscheme Typestring Requiredyes DescriptionMode: expert — advanced, simple — simple. Case-sensitive: SIMPLE is rejected
FielduserId Typenumber Requiredno DescriptionID 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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionThe 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
HTTP400 CodeINVALID_PARAMS Descriptionscheme was not passed or is neither expert nor simple. Checked before the Bitrix24 call
HTTP400 CodeINVALID_PARAMS DescriptionuserId is not a positive integer
HTTP400 CodeINVALID_PARAMS DescriptionThe body contains a field other than scheme and userId, or the body is not a JSON object. The accepted fields are listed in message
HTTP400 CodeINVALID_PARAMS DescriptionA query parameter was passed. The operation accepts no query parameters
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no configured tokens
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the im scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is in read-only mode
HTTP422 CodeBITRIX_ERROR DescriptionuserId 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
HTTP502 CodeME_ALIAS_RESOLUTION_FAILED DescriptionuserId 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