Para agentes de IA: markdown desta página — /docs-content-en/notifications.md índice da documentação — /llms.txt

Os artigos da documentação estão disponíveis atualmente em inglês.

Notifications

Notifications for Bitrix24 users: sending personal and system notifications, reading the feed with its unread counter, marking as read, and deletion by id or tag. 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 Mark notifications as read
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)

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_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 in the portal or is deactivated
403 BITRIX_ACCESS_DENIED Deletion by tag was called 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 Bitrix24 account
502 BITRIX_UNAVAILABLE The Bitrix24 response could not be read

Full list of common API errors — Errors.

See also