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

Notification feed

GET /v1/notifications

Returns a page of the token owner's notifications together with the unread counter. Pages are traversed with a cursor, and the page size is set by the limit parameter.

Parameters

Parameter Type Required Default Description
Parameterlimit (query) Typenumber Requiredno Default50 DescriptionPage size, from 1 to 50. Values 0 and above 50 are clamped to the nearest bound, and the original value is returned in meta.requestedLimit. A negative, fractional or non-numeric value returns 400 INVALID_LIMIT
ParameterlastId (query) Typenumber Requiredno Default— DescriptionThe id of the last notification on the previous page. Sent only together with lastType
ParameterlastType (query) Typenumber Requiredno Default— DescriptionTraversal stage of the feed: 1 — confirmations, 3 — regular notifications. Sent only together with lastId
ParameterconvertText (query) Typestring Requiredno Defaultoff DescriptionConversion of the notification text. The values true, 1, y turn it on and false, 0, n turn it off. The value is case-insensitive

Send the first request without a cursor — the page starts at the beginning of the feed. For the next page, send the id of the last notification in lastId together with lastType. The traversal order and the end-of-feed indicator are described in the "Known specifics" section.

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/notifications?limit=20" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/notifications?limit=20" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/notifications?limit=20', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { data } = await res.json()
console.log('Unread:', data.totalUnreadCount)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/notifications?limit=20', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data } = await res.json()
console.log('Unread:', data.totalUnreadCount)

Response fields

For all keys, including personal keys, strings containing secret webhook URLs in response fields, including nested fields, are replaced entirely with [REDACTED].

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.notifications Typearray DescriptionNotifications on the page
Fielddata.notifications[].id Typenumber, null DescriptionNotification identifier. Pass it in lastId for the next page and to DELETE /v1/notifications/:id
Fielddata.notifications[].chatId Typenumber, null DescriptionIdentifier of the chat this notification belongs to
Fielddata.notifications[].authorId Typenumber, null DescriptionAuthor identifier. The author's card is in the data.users array
Fielddata.notifications[].date Typestring DescriptionNotification date in ISO 8601 format
Fielddata.notifications[].notifyType Typenumber, null DescriptionNotification type
Fielddata.notifications[].notifyModule Typestring DescriptionSource module of the notification, for example rest
Fielddata.notifications[].notifyEvent Typestring DescriptionSource event of the notification
Fielddata.notifications[].notifyTag Typestring DescriptionThe tag the notification was sent with
Fielddata.notifications[].notifySubTag Typestring DescriptionAdditional subTag
Fielddata.notifications[].notifyTitle Typestring DescriptionNotification title
Fielddata.notifications[].settingName Typestring DescriptionName of the delivery setting under which the notification reached the recipient
Fielddata.notifications[].text Typestring DescriptionNotification text
Fielddata.notifications[].notifyRead Typeboolean DescriptionWhether the notification has been read
Fielddata.notifications[].notifyButtons Typestring DescriptionNotification buttons — a JSON string with the array of buttons, as the Bitrix24 account sent it. The value for pressing a button is the part of the button's COMMAND_PARAMS after the | character. If the notifyButtons string contains a secret webhook URL, it is replaced entirely with [REDACTED]; this value is not JSON. The field is absent on a notification without buttons
Fielddata.notifications[].params Typeobject, null DescriptionExtra data from the sender. The keys inside are the ones the sending application wrote
Fielddata.users Typearray DescriptionCards of the authors of the notifications on this page
Fielddata.users[].id Typenumber, null DescriptionUser identifier. Full card — Employees
Fielddata.users[].active Typeboolean DescriptionWhether the user is active in the Bitrix24 account
Fielddata.users[].name Typestring DescriptionDisplay name
Fielddata.users[].firstName Typestring DescriptionFirst name
Fielddata.users[].lastName Typestring DescriptionLast name
Fielddata.users[].workPosition Typestring DescriptionJob position
Fielddata.users[].color Typestring DescriptionColor of the user card in the Bitrix24 interface
Fielddata.users[].avatar Typestring DescriptionAvatar link
Fielddata.users[].bot Typeboolean DescriptionWhether the author is a bot
Fielddata.users[].type Typestring DescriptionAuthor type, for example user
Fielddata.totalCount Typenumber DescriptionFeed notification counter
Fielddata.totalUnreadCount Typenumber DescriptionUnread notification counter
Fielddata.chatId Typenumber, null DescriptionIdentifier of the system notification chat
Fielddata.hasMore Typeboolean Descriptiontrue when the page is filled up to meta.appliedLimit
Fieldmeta.appliedLimit Typenumber DescriptionPage size the request ran with. Present in every response, including one without limit
Fieldmeta.requestedLimit Typenumber DescriptionThe original limit value before clamping. Present only when the value was changed

Response example

HTTP 200:

JSON 
{
  "success": true,
  "data": {
    "notifications": [
      {
        "id": 38963,
        "chatId": 3113,
        "authorId": 1297,
        "date": "2026-08-13T09:00:00+00:00",
        "notifyType": 2,
        "notifyModule": "rest",
        "notifyEvent": "rest_notify",
        "notifyTag": "MP|12345|DEAL_1024",
        "notifySubTag": "MP|12345|DEAL|1024",
        "notifyTitle": "",
        "settingName": "rest|rest_notify",
        "text": "Deal #1024 moved to the Paid stage",
        "params": null,
        "notifyRead": false
      },
      {
        "id": 38959,
        "chatId": 3113,
        "authorId": 1,
        "date": "2026-08-13T08:41:12+00:00",
        "notifyType": 1,
        "notifyModule": "calendar",
        "notifyEvent": "invite",
        "notifyTag": "CALENDAR|INVITE|8217|1297",
        "notifySubTag": "CALENDAR|INVITE|8217",
        "notifyTitle": "Invitation to event \"Stand-up\" from John Carter",
        "settingName": "calendar|invite",
        "text": "I would like to invite you to the event \"[B]Stand-up[/B]\". The said event will take place on [B]Thursday, August 13, 2026 11:00 am[/B].",
        "notifyButtons": "[{\"BOT_ID\":111,\"TYPE\":\"BUTTON\",\"COMMAND\":\"notifyConfirm\",\"COMMAND_PARAMS\":\"38959|Y\",\"TEXT\":\"Confirm\",\"VOTE\":\"N\",\"BLOCK\":\"N\",\"WAIT\":\"N\",\"CONTEXT\":\"ALL\",\"DISABLED\":\"N\",\"DISPLAY\":\"LINE\",\"BG_COLOR\":\"#8BC84B\",\"BG_COLOR_TOKEN\":\"base\",\"TEXT_COLOR\":\"#fff\"},{\"BOT_ID\":111,\"TYPE\":\"BUTTON\",\"COMMAND\":\"notifyConfirm\",\"COMMAND_PARAMS\":\"38959|N\",\"TEXT\":\"Decline\",\"VOTE\":\"N\",\"BLOCK\":\"N\",\"WAIT\":\"N\",\"CONTEXT\":\"ALL\",\"DISABLED\":\"N\",\"DISPLAY\":\"LINE\",\"BG_COLOR\":\"#ef4b57\",\"BG_COLOR_TOKEN\":\"base\",\"TEXT_COLOR\":\"#fff\"}]",
        "params": null,
        "notifyRead": false
      }
    ],
    "users": [
      {
        "id": 1297,
        "active": true,
        "name": "Emma Hayes",
        "firstName": "Emma",
        "lastName": "Hayes",
        "workPosition": "Sales Manager",
        "color": "#1eb4aa",
        "avatar": "https://example.bitrix24.com/upload/main/avatar-1297.png",
        "bot": false,
        "type": "user"
      },
      {
        "id": 1,
        "active": true,
        "name": "John Carter",
        "firstName": "John",
        "lastName": "Carter",
        "workPosition": "Head of Department",
        "color": "#df532d",
        "avatar": "https://example.bitrix24.com/upload/main/avatar-1.png",
        "bot": false,
        "type": "user"
      }
    ],
    "totalCount": 15,
    "totalUnreadCount": 2,
    "chatId": 3113,
    "hasMore": false
  },
  "meta": {
    "appliedLimit": 20
  }
}

Error response example

400 — limit is not an integer:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_LIMIT",
    "message": "limit must be an integer in 1..50"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_LIMIT Descriptionlimit is negative, fractional, non-numeric or was not sent as a string
HTTP400 CodeVALIDATION_ERROR DescriptionOnly half of the cursor was sent, lastType is outside the values 1 and 3, lastId is beyond the safe integer range, convertText holds an unrecognized value, or a parameter was not sent as a string
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the im scope
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no configured tokens
HTTP429 CodeRATE_LIMITED DescriptionFeed reading rate exceeded — up to 600 requests per minute per portal. The current limit is returned in the x-ratelimit-limit header
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionThe Bitrix24 response could not be read
HTTP422 CodeBITRIX_ERROR DescriptionThe method failed on the Bitrix24 side; the portal's code is in b24Code

For the full list of common API errors, see Errors.

Known specifics

  • The feed belongs to the token owner — the operation has no "whose feed to read" parameter. A personal key returns the feed of the key owner. The feed of a specific user is available only with an OAuth application key carrying the Authorization: Bearer header: the user session decides whose feed it is.
  • The feed is not filtered by application: notifications of other applications on the Bitrix24 account and system notifications arrive alongside your own. Select yours by notifyTag or notifyModule on the client side.
  • A wrongly chosen lastType raises no error — the same page comes back. Traversal order: an empty page means the end. If a page brought no new id at all, repeat the same lastId with the other lastType value, and only when that one also brings no new id treat the traversal as finished. Set your own limit on the number of pages: a complete traversal of the feed is not guaranteed by the contract.
  • hasMore: false means the page came back shorter than the requested limit. That is usually the end of the feed, but a short page can also arrive in the middle of a traversal, so the reliable end indicator is an empty page.
  • totalCount can be noticeably larger than the number of notifications the feed hands out during a traversal. Do not use it for pagination.
  • data.chatId and data.notifications[].chatId are different values. The first is the system notification chat, the second is the chat of a particular notification.
  • To read the unread counter without fetching a whole page, send a request with limit=1. On a non-empty feed such a request always returns hasMore: true.
  • The fields text, notifyTitle, notifyButtons, params and the strings in data.users are untrusted content: other applications on the Bitrix24 account write them. Escape these values before rendering them in an interface.
  • Counters Bitrix24 did not send are replaced with 0, 0 and null. A counter it did send is passed through as is, so totalCount can be non-zero on an empty page. There is no separate empty-feed indicator — check the length of notifications.

See also