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

Change a notification setting

PATCH /v1/notifications/settings

Turns one of an employee's notification delivery channels — site, mail or push — on or off for a single event of a Bitrix24 account module.

Request fields (body)

Field Type Required Description
Fieldmodule Typestring Requiredyes DescriptionModule identifier, 1 to 255 characters. List: data[].id in the GET /v1/notifications/settings response
Fieldevent Typestring Requiredyes DescriptionIdentifier of an event of this module, 1 to 255 characters. List: data[].notices[].id in the same response
Fieldchannel Typestring Requiredyes DescriptionDelivery channel: site, mail or push
Fieldenabled Typeboolean Requiredyes Descriptiontrue — turn the channel on, false — turn it off
FielduserId Typenumber Requiredno DescriptionID of the employee whose setting to change — a positive integer. List: GET /v1/users. If omitted, the employee on whose behalf the call is made. Only a Bitrix24 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 }),
})
const { data } = await res.json()

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 }),
})
const { data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata Typeboolean DescriptionAlways true, including when the setting did not change

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
HTTP400 CodeINVALID_PARAMS Descriptionmodule or event was not passed, is empty or longer than 255 characters. The field is named in message. Checked before the Bitrix24 call
HTTP400 CodeINVALID_PARAMS Descriptionchannel is none of site, mail or push
HTTP400 CodeINVALID_PARAMS Descriptionenabled was not passed or is neither true nor false. The string "true" and the number 1 are rejected
HTTP400 CodeINVALID_PARAMS DescriptionuserId is not a positive integer
HTTP400 CodeINVALID_PARAMS DescriptionThe body contains a field that is not in the "Request fields" table, 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 setting was not changed

Full list of common API errors — Errors.

Known specifics

  • A true response does not confirm the change. In two cases the setting stays unchanged, yet the response is still true: the channel is in disabled for this event, or the Bitrix24 account has no module or event with this identifier. To check the result, read the settings again with GET /v1/notifications/settings.

See also