لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/notifications/settings.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

Notification settings

The operations read and change the delivery channels for an employee's notifications about events in Bitrix24 modules, and switch the settings mode — advanced or simple.

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

Get notification settings

GET /v1/notifications/settings

Returns the channels through which an employee receives notifications about events in each module of the Bitrix24 account.

Parameters

Parameter Type Required Description
ParameteruserId (query) Typenumber Requiredno DescriptionID of the employee whose settings to read — a positive integer. List: GET /v1/users. If omitted, the settings of the employee on whose behalf the call is made are returned. Another employee's settings are available only to a Bitrix24 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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionModules of the Bitrix24 account with configurable notifications
Fielddata[].id Typestring DescriptionModule identifier. Matches notifyModule of a notification in the feed. The same value is passed in the module field when changing a setting and in notification group conditions
Fielddata[].label Typestring DescriptionModule name
Fielddata[].notices Typearray DescriptionModule events
Fielddata[].notices[].id Typestring DescriptionEvent identifier. Matches notifyEvent of a notification in the feed
Fielddata[].notices[].label Typestring DescriptionEvent name
Fielddata[].notices[].site Typeboolean DescriptionThe "Web version and desktop app" channel. true — notifications about the event arrive through this channel
Fielddata[].notices[].mail Typeboolean DescriptionThe "Email" channel
Fielddata[].notices[].push Typeboolean DescriptionThe "Mobile devices (push notifications)" channel
Fielddata[].notices[].disabled Typearray DescriptionEvent 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 messages",
          "site": true,
          "mail": false,
          "push": false,
          "disabled": ["site"]
        },
        {
          "id": "like",
          "label": "Reactions to your messages",
          "site": false,
          "mail": false,
          "push": false,
          "disabled": ["push"]
        }
      ]
    },
    {
      "id": "bizproc",
      "label": "Workflows",
      "notices": [
        {
          "id": "activity",
          "label": "Workflow notifications",
          "site": true,
          "mail": false,
          "push": false,
          "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
HTTP400 CodeINVALID_PARAMS DescriptionuserId is not a positive integer. Checked before the Bitrix24 call
HTTP400 CodeINVALID_PARAMS DescriptionuserId was passed more than once or with brackets, for example userId[]=5
HTTP400 CodeINVALID_PARAMS DescriptionA query parameter other than userId was passed. The accepted parameters are listed in message
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no configured tokens
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the im scope
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 settings were not requested

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. To check the employee, use GET /v1/users/:id.

See also