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

Notifications

Send notifications to Bitrix24 users: personal and system notifications, 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
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
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

Full list of common API errors — Errors.

See also