สำหรับเอเจนต์ AI: markdown ของหน้านี้ — /docs-content-en/notifications/search.md ดัชนีเอกสาร — /llms.txt

บทความในเอกสารมีให้บริการเป็นภาษาอังกฤษในขณะนี้

Search notifications

GET /v1/notifications/search

Searches the token owner's notification history by text, notification type, author and date. Returns a page of up to 50 notifications. Request further pages with the lastId cursor.

Parameters

Parameter Type Required Description
text (query) string no Text to search for in notifications. If none of the type, types, authors, date, dateFrom, dateTo filters is passed, at least 3 characters after trimming leading and trailing whitespace
type (query) string no Notification type: a source module, for example crm, or a module|event pair, for example mail|new_message_v2. List of types — GET /v1/notifications/schema. If types is passed, type is ignored
types (query) string | array no Several source modules, comma-separated, types=crm,mail, or as an array, types[]=crm&types[]=mail. List of modules — GET /v1/notifications/schema. A list of one value works like type, including the module|event form. In a list of two or more values each value is compared with the module only, so a module|event pair in such a list matches nothing
authors (query) string | array no Author IDs, comma-separated, authors=1,835, or as an array, authors[]=1&authors[]=835. The value 0 selects system notifications without an author. List of employees — GET /v1/users
date (query) string no 24 hours starting from the given moment, in ISO 8601 format: 2026-10-08 or 2026-10-08T00:00:00+00:00. A date without a time means a UTC day. If dateFrom and dateTo are passed, date is ignored
dateFrom (query) string no Start of the date range in ISO 8601 format. Applied only together with dateTo
dateTo (query) string no End of the date range in ISO 8601 format. The range ends 24 hours after dateTo, so a date without a time is included in the range in full. Applied only together with dateFrom
lastId (query) string no Cursor — the id of the last notification on the previous page. Digits only. The value 0 returns the first page

Notifications arrive from newest to oldest, up to 50 per page. Send the first request without lastId. For the next page, pass the id of the last notification in lastId and repeat the other parameters unchanged. Pagination is complete when an empty page arrives or a page repeats id values already received. The server does not paginate automatically.

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/notifications/search?type=crm&dateFrom=2026-10-01&dateTo=2026-10-07" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/notifications/search?type=crm&dateFrom=2026-10-01&dateTo=2026-10-07" \
  -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/search?type=crm&dateFrom=2026-10-01&dateTo=2026-10-07', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/notifications/search?type=crm&dateFrom=2026-10-01&dateTo=2026-10-07', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

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

Response fields

Field Type Description
success boolean Always true on success
data.chatId number, null ID of the token owner's system notification chat. null when no search was performed: the request has neither text nor a filter that takes effect, or the owner has no notification chat
data.notifications array Notifications found on the page
data.notifications[].id number, null Notification ID. Passed in lastId for the next page and to DELETE /v1/notifications/:id
data.notifications[].chatId number, null ID of this notification's chat
data.notifications[].authorId number, null Author ID. 0 — a system notification without an author. The author's card is in the data.users array
data.notifications[].date string Notification date in ISO 8601 format
data.notifications[].notifyType number, null Notification type
data.notifications[].notifyModule string Source module of the notification, for example crm
data.notifications[].notifyEvent string Source event of the notification
data.notifications[].notifyTag string The tag the notification was sent with
data.notifications[].notifySubTag string The additional subTag
data.notifications[].notifyTitle string Notification title
data.notifications[].settingName string Name of the delivery setting under which the notification reached the recipient
data.notifications[].text string Notification text
data.notifications[].notifyRead boolean Whether the notification has been read
data.notifications[].notifyButtons string Notification buttons — a JSON string with an array of buttons, as in the notification feed. A notification without buttons has no such field
data.notifications[].params object, null Additional sender data. Nested keys are returned as the sender wrote them
data.users array Cards of the authors of this page's notifications. Public fields only, without emails and phone numbers
data.users[].id number, null Employee ID. The full card — Employees
data.users[].active boolean Whether the employee is active on the Bitrix24 account
data.users[].name string Display name
data.users[].firstName string First name
data.users[].lastName string Last name
data.users[].workPosition string, null Job title
data.users[].color string Color of the employee's card in the Bitrix24 interface
data.users[].avatar string Avatar URL
data.users[].bot boolean Whether the author is a bot
data.users[].type string Author type, for example user
data.totalResults number Number of notifications matching the search conditions. Counted only on the first page — without lastId or with lastId=0. On subsequent pages 0 is returned

Response example

HTTP 200, showing the first two notifications of the page:

JSON 
{
  "success": true,
  "data": {
    "chatId": 7,
    "notifications": [
      {
        "id": 42441,
        "chatId": 7,
        "authorId": 835,
        "date": "2026-10-08T00:01:05+00:00",
        "notifyType": 2,
        "notifyModule": "crm",
        "notifyEvent": "changeAssignedBy",
        "notifyTag": "CRM|DEAL_RESPONSIBLE|8779",
        "notifySubTag": "",
        "notifyTitle": "",
        "settingName": "crm|changeAssignedBy",
        "text": "You have been assigned as the person responsible for the deal \"[URL=/crm/deal/details/8779/]Deal #6531[/URL]\"",
        "params": {
          "COMPONENT_ID": "CrmEntity",
          "COMPONENT_PARAMS": {
            "SUBJECT": "#AUTHOR# assigned you as the person responsible for the deal",
            "ENTITY": {
              "TITLE": "Deal #6531",
              "HREF": "/crm/deal/details/8779/",
              "ENTITY_TYPE": "deal",
              "CONTENT_TYPE": "title"
            }
          }
        },
        "notifyRead": false
      },
      {
        "id": 42399,
        "chatId": 7,
        "authorId": 835,
        "date": "2026-10-07T00:01:08+00:00",
        "notifyType": 2,
        "notifyModule": "crm",
        "notifyEvent": "changeAssignedBy",
        "notifyTag": "CRM|DEAL_RESPONSIBLE|8771",
        "notifySubTag": "",
        "notifyTitle": "",
        "settingName": "crm|changeAssignedBy",
        "text": "You have been assigned as the person responsible for the deal \"[URL=/crm/deal/details/8771/]Deal #6531[/URL]\"",
        "params": {
          "COMPONENT_ID": "CrmEntity",
          "COMPONENT_PARAMS": {
            "SUBJECT": "#AUTHOR# assigned you as the person responsible for the deal",
            "ENTITY": {
              "TITLE": "Deal #6531",
              "HREF": "/crm/deal/details/8771/",
              "ENTITY_TYPE": "deal",
              "CONTENT_TYPE": "title"
            }
          }
        },
        "notifyRead": false
      }
    ],
    "users": [
      {
        "id": 835,
        "active": true,
        "name": "Anna Brown",
        "firstName": "Anna",
        "lastName": "Brown",
        "workPosition": "",
        "color": "#3e99ce",
        "avatar": "https://example.bitrix24.com/upload/main/avatar-835.png",
        "bot": false,
        "type": "user"
      }
    ],
    "totalResults": 24
  }
}

Error response example

400 — text is shorter than 3 characters and no filters are passed:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Required: text with at least 3 characters, or a search filter."
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS text is shorter than 3 characters and no filter is passed
400 INVALID_PARAMS A parameter that is not in the "Parameters" table is passed
400 INVALID_PARAMS lastId contains something other than digits or is outside the safe integer range
400 INVALID_PARAMS authors contains a value that is not a non-negative integer, or types contains an empty value
400 INVALID_PARAMS A parameter is passed as an array where a string is expected
401 MISSING_API_KEY X-Api-Key is not passed
401 TOKEN_MISSING The key has no configured tokens
403 SCOPE_DENIED The key does not have the im scope
403 BITRIX_ACCESS_DENIED Bitrix24 denied access
422 BITRIX_ERROR Method error on the Bitrix24 side. The Bitrix24 error code is in the b24Code field. For example, a date not in ISO 8601 format
429 RATE_LIMITED Bitrix24 limited the request rate
502 BITRIX_UNAVAILABLE The Bitrix24 response could not be read
503 BITRIX_TIMEOUT Bitrix24 did not respond in time

Full list of common API errors — Errors.

Known specifics

  • The search runs over the token owner's history: with a personal key — the key owner's, with an OAuth application key — the history of the employee from the Authorization: Bearer session. There is no filter by application: notifications of other applications on the Bitrix24 account and system notifications are found together with your application's notifications.
  • A single range bound with no other search conditions returns an empty page with chatId: null, not an error. Together with text or another filter, a single bound is ignored.
  • 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.

See also