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

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

Endpoints of the "Notifications" section

Send notifications to Bitrix24 users, read the notification feed, mark them as read, and delete by id or tag. Switch methods in the tabs — each has its own parameters, response fields, and error codes.

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

Send a notification

POST /v1/notifications

Sends a notification to a Bitrix24 user — it appears in the Notifications section of the Bitrix24 account.

Request fields (body)

Field Type Required Description
userId number yes Recipient user ID. List: GET /v1/users
message string yes Notification text
type string no personal — a personal notification from the application, system — a system message from Bitrix24. Defaults to personal
tag string no Notification tag. Use it to delete notifications as a group via DELETE /v1/notifications/by-tag/:tag
subTag string no Additional tag within tag
messageOut string no Separate text for an external messenger if the recipient has one connected

Examples

curl — personal key

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"
  }'

curl — OAuth application

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

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/notifications', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userId: 1,
    message: 'Deal #1024 moved to the Paid stage',
  }),
})

const body = await res.json()
console.log('Notification id:', body.data.notificationId)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/notifications', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userId: 1,
    message: 'Deal #1024 moved to the Paid stage',
  }),
})

Response fields

Field Type Description
success boolean true on successful delivery
data.notificationId number Identifier of the created notification. Pass it to DELETE /v1/notifications/:id to delete the notification

Response example

HTTP 201:

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

Error response example

422 — notification not delivered:

JSON 
{
  "success": false,
  "error": {
    "code": "NOTIFICATION_NOT_DELIVERED",
    "message": "Bitrix24 did not create the notification (returned false). The userId may not exist on the portal or may be deactivated."
  }
}

Errors

HTTP Code Description
400 MISSING_PARAMS userId or message is missing
422 NOTIFICATION_NOT_DELIVERED Notification not created — the recipient is not on the portal or is deactivated
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.

Known specifics

  • Each call creates a new notification with a new notificationId. Re-sending the same text shows the recipient several notifications — to show it once, delete the previous notification or send with a shared tag.

See also