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

Notification settings

Delivery channels for an employee's notifications about events in Bitrix24 account modules: reading the settings, turning a channel on or off for an event, and switching the settings mode.

Get notification settings

GET /v1/notifications/settings

Shows, for each module of the Bitrix24 account, through which channels the employee receives notifications about each event: in the Bitrix24 web version and desktop app, by email, and in the mobile app.

Parameters

Parameter Type Required Description
userId (query) number no ID of the employee whose settings to read. List: GET /v1/users. Without the parameter — the employee on whose behalf the call is made. Another employee's settings are available only to a Bitrix24 account administrator

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/notifications/settings" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/notifications/settings" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/notifications/settings', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { data } = await res.json()
const im = data.find((m) => m.id === 'im')
console.log(im?.notices.map((n) => `${n.id}: site=${n.site} mail=${n.mail} push=${n.push}`))

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/notifications/settings', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

Response fields

Field Type Description
success boolean Always true on success
data array Modules of the Bitrix24 account with configurable notifications
data[].id string Module identifier. Matches notifyModule of a notification in the notification feed. This value is accepted by the module field when changing a setting and by the conditions of notification groups
data[].label string Module name
data[].notices array Module events
data[].notices[].id string Event identifier. Matches notifyEvent of a notification in the notification feed
data[].notices[].label string Event name
data[].notices[].site boolean The "Web version and desktop app" channel. true — notifications about the event arrive through this channel
data[].notices[].mail boolean The "Email" channel
data[].notices[].push boolean The "Mobile devices (push notifications)" channel
data[].notices[].disabled array Event channels that cannot be changed: site, mail, push. The value of such a channel is set by the Bitrix24 account: true or false

Response example

Two modules are shown, each with some of its events. 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 message received",
          "site": true,
          "mail": true,
          "push": true,
          "disabled": ["site"]
        },
        {
          "id": "like",
          "label": "Reactions",
          "site": true,
          "mail": true,
          "push": false,
          "disabled": ["push"]
        }
      ]
    },
    {
      "id": "bizproc",
      "label": "Workflows",
      "notices": [
        {
          "id": "activity",
          "label": "Workflow notifications",
          "site": true,
          "mail": true,
          "push": true,
          "disabled": []
        },
        {
          "id": "wi_locked",
          "label": "Workflow aborted",
          "site": true,
          "mail": false,
          "push": false,
          "disabled": ["push"]
        }
      ]
    }
  ]
}

Error response example

400 — userId is not a positive integer:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "The query parameter `userId` must be a positive integer."
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS userId is not a positive integer or was passed twice, or another query parameter was passed. Checked before the Bitrix24 call
422 BITRIX_ERROR Another employee's settings were requested without 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 settings were not requested
403 SCOPE_DENIED The key lacks the im scope
401 TOKEN_MISSING The key has no configured tokens

Full list of common API errors — Errors.

Known specifics

  • For an administrator, a non-existent userId does not cause an error: the response contains the default settings. A successful response does not confirm that an employee with this ID exists in the Bitrix24 account.

Change a notification setting

PATCH /v1/notifications/settings

Turns one delivery channel on or off for one module event.

Request fields (body)

Field Type Required Description
module string yes Module identifier, 1 to 255 characters. List: data[].id in the GET /v1/notifications/settings response
event string yes Identifier of an event of this module, 1 to 255 characters. List: data[].notices[].id in the same response
channel string yes Delivery channel: site, mail or push
enabled boolean yes true — turn the channel on, false — turn it off. Strings and numbers are rejected
userId number no ID of the employee whose setting to change. List: GET /v1/users. Without the field — the employee on whose behalf the call is made. Only a Bitrix24 account administrator can change another employee's settings

Examples

curl — personal key

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/notifications/settings" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "module": "bizproc", "event": "activity", "channel": "site", "enabled": false }'

curl — OAuth application

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/notifications/settings" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "module": "bizproc", "event": "activity", "channel": "site", "enabled": false }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/notifications/settings', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ module: 'bizproc', event: 'activity', channel: 'site', enabled: false }),
})

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/notifications/settings', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ module: 'bizproc', event: 'activity', channel: 'site', enabled: false }),
})

Response fields

Field Type Description
success boolean true on success
data boolean Always true. The success indicator is the HTTP code 200, not the value

Response example

HTTP 200:

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

Error response example

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

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Body field `channel` must be one of: site, mail, push."
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS module or event is not a string of 1 to 255 characters, channel is not site, mail or push, enabled is neither true nor false, userId is not a positive integer, the body has an extra field, or a query parameter was passed. The field is named in message. Checked before the Bitrix24 call
422 BITRIX_ERROR Changing another employee's settings without 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 setting was not changed
403 SCOPE_DENIED The key lacks the im scope
403 WRITE_BLOCKED_READONLY_KEY The key is in read-only mode
401 TOKEN_MISSING The key has no configured tokens

Full list of common API errors — Errors.

Known specifics

  • A true response does not confirm the change. The setting stays the same, and the response is still true, in two cases: the channel is listed in disabled for this event, or the Bitrix24 account has no module or event with this identifier. When the result matters, read the settings again with GET /v1/notifications/settings.

Switch the settings mode

PUT /v1/notifications/settings/scheme

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

Important: switching to simple mode overwrites the settings of every event. Switching back to advanced expert mode 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. List: GET /v1/users. Without the field — the employee on whose behalf the call is made. Only a Bitrix24 account 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 notification settings response

Response example

One module and some of its events are shown.

HTTP 200:

JSON 
{
  "success": true,
  "data": [
    {
      "id": "im",
      "label": "Chats and calls",
      "notices": [
        {
          "id": "message",
          "label": "Direct chat message received",
          "site": true,
          "mail": true,
          "push": true,
          "disabled": ["site"]
        },
        {
          "id": "like",
          "label": "Reactions",
          "site": true,
          "mail": true,
          "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 is not expert or simple, userId is not a positive integer, the body has an extra field, or a query parameter was passed. The field is named in message. Checked before the Bitrix24 call
422 BITRIX_ERROR Switching another employee's mode without 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
403 SCOPE_DENIED The key lacks the im scope
403 WRITE_BLOCKED_READONLY_KEY The key is in read-only mode
401 TOKEN_MISSING The key has no configured tokens

Full list of common API errors — Errors.

See also