Para agentes de IA: markdown de esta página — /docs-content-en/notifications.md índice de la documentación — /llms.txt

Los artículos de la documentación están disponibles actualmente en inglés.

Notifications

Notifications for Bitrix24 users: sending personal and system notifications, reading the feed with its unread counter, marking as read, deleting by ID, by tag, or all at once, notification groups, and delivery settings per channel. Notifications appear in the Notifications section of the Bitrix24 account.

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

Quick start | Full example | Endpoint reference | Error codes

Quick start

Send a notification to a user by their userId:

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/notifications" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "userId": 1, "message": "Deal #1024 moved to the Paid stage" }'

Response (HTTP 201):

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

Full example

Send a notification, mark it read, and delete it:

javascript 
const BASE = 'https://vibecode.bitrix24.com/v1'
const headers = {
  'X-Api-Key': 'YOUR_API_KEY',
  'Content-Type': 'application/json',
}

// 1. Send
const sendRes = await fetch(`${BASE}/notifications`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ userId: 1, message: 'Deal #1024 moved to the Paid stage' }),
})
const { data } = await sendRes.json()
const id = data.notificationId

// 2. Mark as read
await fetch(`${BASE}/notifications/read`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ id, onlyCurrent: true }),
})

// 3. Delete
const delRes = await fetch(`${BASE}/notifications/${id}`, {
  method: 'DELETE',
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
console.log('Deleted:', delRes.status === 204)

Endpoint reference

Method Path Bitrix24 method Description
POST /v1/notifications im.notify.personal.add Send a notification to a user
GET /v1/notifications im.notify.get Read the notification feed and the unread counter
GET /v1/notifications/schema im.notify.schema.get Read the notification type dictionary
POST /v1/notifications/read im.notify.read; with format=v2 — im.v2.Notify.read Mark notifications as read
POST /v1/notifications/read-all im.v2.Notify.readAll Mark all notifications as read except the listed ones
DELETE /v1/notifications/:id im.notify.delete Delete a notification by identifier
DELETE /v1/notifications/by-tag/:tag im.notify.delete Delete notifications by tag (OAuth application only)
DELETE /v1/notifications im.v2.Notify.deleteAll Delete all notifications of the key owner — irreversible
GET /v1/notifications/groups im.v2.Notify.Group.list Read notification groups
POST /v1/notifications/groups im.v2.Notify.Group.add Create a group with its first condition
PATCH /v1/notifications/groups/:groupId im.v2.Notify.Group.update Rename a group
DELETE /v1/notifications/groups/:groupId im.v2.Notify.Group.delete Delete a group and all its conditions
POST /v1/notifications/groups/:groupId/conditions im.v2.Notify.Condition.add Add a condition to a group
DELETE /v1/notifications/groups/:groupId/conditions im.v2.Notify.Condition.delete Remove a condition from a group
GET /v1/notifications/settings im.v2.Settings.Notify.list Read the notification delivery settings
PATCH /v1/notifications/settings im.v2.Settings.Notify.update Turn one delivery channel of an event on or off
PUT /v1/notifications/settings/scheme im.v2.Settings.Notify.switchScheme Switch the settings mode: advanced or simple

Interactive method switcher with examples and response fields — Endpoints.

Error codes

HTTP Code Description
400 MISSING_PARAMS userId or message is missing when sending
400 INVALID_PARAMS id is not a positive integer when deleting by ID; for the format=v2 mode, marking all as read, deleting all, groups, conditions and settings — an unknown, repeated or malformed query parameter or body field. Checked before the Bitrix24 call
400 INVALID_LIMIT limit is not an integer when reading the feed
400 VALIDATION_ERROR The lastId and lastType cursor or the convertText value is incorrect when reading the feed
422 NOTIFICATION_NOT_DELIVERED The recipient is not on the portal or is deactivated
404 ENTITY_NOT_FOUND The group does not exist or belongs to another user — the Bitrix24 code GROUP_NOT_FOUND is in the error.b24Code field
404 ENTITY_NOT_FOUND format=v2 marking only: the notifications were not found and the portal message says Message is not found; error.b24Code is MESSAGE_NOT_FOUND
422 BITRIX_ERROR Bitrix24 refused the request; its code is in error.b24Code: MESSAGE_NOT_FOUND (for format=v2, the portal sent only the bare code without a Message is not found text), SETTINGS_ACCESS_DENIED (another user's settings without administrator rights), 400 (a repeated group condition)
403 BITRIX_ACCESS_DENIED Deletion by tag was requested with a personal key instead of an OAuth application key
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
429 RATE_LIMITED Feed reading rate exceeded — up to 600 requests per minute per portal. The exact value arrives in the x-ratelimit-limit header (the cap is divided across replicas)
502 BITRIX_UNAVAILABLE The Bitrix24 response could not be read
502 ME_ALIAS_RESOLUTION_FAILED userId was not passed in a settings request, and the key owner could not be determined. Nothing was sent to Bitrix24

Full list of common API errors — Errors.

See also