Para agentes de IA: markdown de esta página — /docs-content-en/notifications/endpoints.md índice de la documentación — /llms.txt
Los artículos de la documentación están disponibles actualmente en inglés.
"Notifications" section endpoints
Send notifications to Bitrix24 users, read the notification feed, search the history, mark notifications as read, answer a notification and press its button, delete them by ID, by tag or all at once, and manage notification groups and delivery settings. 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 |
|---|---|---|---|
FielduserId |
Typenumber | Requiredyes | DescriptionRecipient user ID. List: GET /v1/users |
Fieldmessage |
Typestring | Requiredyes | DescriptionNotification text |
Fieldtype |
Typestring | Requiredno | Descriptionpersonal — a personal notification from the application, system — a system message from Bitrix24. Defaults to personal |
Fieldtag |
Typestring | Requiredno | DescriptionNotification tag. Use it to delete notifications as a group via DELETE /v1/notifications/by-tag/:tag |
FieldsubTag |
Typestring | Requiredno | DescriptionAdditional tag within tag |
FieldmessageOut |
Typestring | Requiredno | DescriptionSeparate text for an external messenger if the recipient has one connected |
Fieldattach |
Typearray | object | string | Requiredno | DescriptionFormatting blocks shown below the notification text. Block format: Attachments. Accepted as an array of blocks, an object with a BLOCKS key, or the same structure as a JSON string. The structure is passed through without validation |
Examples
curl — personal key
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
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
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
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 |
|---|---|---|
Fieldsuccess |
Typeboolean | Descriptiontrue on successful delivery |
Fielddata.notificationId |
Typenumber | DescriptionIdentifier of the created notification. Pass it to DELETE /v1/notifications/:id to delete the notification |
Response example
HTTP 201:
{
"success": true,
"data": {
"notificationId": 37421
}
}
Error response example
422 — notification not delivered:
{
"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 |
|---|---|---|
| HTTP400 | CodeMISSING_PARAMS |
DescriptionuserId or message is missing |
| HTTP422 | CodeNOTIFICATION_NOT_DELIVERED |
DescriptionNotification not created — the recipient is not on the portal or is deactivated |
| HTTP403 | CodeSCOPE_DENIED |
DescriptionThe key lacks the im scope |
| HTTP403 | CodeWRITE_BLOCKED_READONLY_KEY |
DescriptionThe key is in read-only mode |
| HTTP401 | CodeTOKEN_MISSING |
DescriptionThe 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 sharedtag.