Chat discovery

Find a chat through recent dialogs, unread counters, folders and list sections, channels, collabs and external chats, shared chats, changes since a moment, CRM entity chats, search, dialog details, external dialog IDs and access checks.

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

Recent dialogs

GET /v1/chats/recent

Returns the list of the current user's recent dialogs: pinned dialogs first, then by the time of the last message. Each item contains brief information about the dialog, the last message, and the unread counter.

Parameters

Delta mode. The updatedAfter parameter switches the endpoint into a "what changed since the given instant" mode: GET /v1/chats/recent?updatedAfter=2026-06-28T00:00:00Z. The response contains an array of dialogs whose dateUpdate is not earlier than the given instant. The boundary is inclusive — a dialog whose dateUpdate equals the given instant is included, so if you advance the cursor to the highest value you have seen, that boundary record arrives again on the next call.

The page size in this mode is controlled by the server: one page of up to 200 dialogs is read. The limit you pass does not affect it and is returned in meta.requestedLimit together with the applied meta.appliedLimit.

When meta contains truncated with the value true, the delta may be incomplete: Bitrix24 reported that more dialogs exist beyond the returned page, or the response shape could not be parsed. In that case do not move updatedAfter — read the full list using the paged mode with the lastMessageDate cursor. The number of rows returned is not a completeness signal — a short response also arrives when more data exists beyond it.

A date without an explicit offset — for example 2026-06-29 10:00:00 — is rejected with 400 INVALID_PARAMS: such a value is interpreted differently depending on the server time zone, so the instant has to be stated unambiguously.

The v2 mode. format=v2 switches the endpoint to the v2 messenger methods: the first page comes from im.v2.Recent.load (without lastMessageDate), subsequent pages from im.v2.Recent.tail (with it). data carries the v2 object — recentItems and the chats, users, messages, files collections — with camelCase keys. The mode accepts only format, limit, lastMessageDate and unreadOnly (true or false); any other parameter, including the parameters of the legacy mode and their upper-case forms (OFFSET, LIMIT, LAST_UPDATE), is refused with 400 INVALID_PARAMS naming the parameter. The list is always the general one, without nested sections. The mode has its own rate-limit bucket, separate from that of the legacy mode.

The cursor of the next page is the smallest non-empty dateLastActivity among the unpinned rows of the current page; compare instants, not strings: dates may carry different offsets. The bound is inclusive, and pinned chats dated no later than the cursor appear at the top of every page — deduplicate by chatId. The list ends only at hasNextPage: false. If hasNextPage is true but there is no cursor or it equals the previous one, repeat the request with a larger limit, up to 200; true without progress even at 200 is a failure, not the end of the list. Do not discard rows from a response even if you display fewer: the cursor is computed over the whole response, and discarded rows are not returned again. A walk is not a snapshot: a chat lifted above the cursor by new activity during the walk does not appear in it, so re-read the first page after the walk. For a full walk use limit=200: pinned rows repeat on every page, and small pages waste requests on repeats.

Examples

curl — personal key

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

curl — OAuth application

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

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/chats/recent?limit=20', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()
console.log('Recent dialogs:', data.items)

JavaScript — OAuth application

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

Response fields

In delta mode data is an array of dialogs with the same item fields listed above for data.items. The hasMorePages and hasMore fields are not returned in this mode — meta.truncated serves that role instead.

Response example

Paged mode:

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "chat456",
        "chatId": 456,
        "type": "chat",
        "title": "Development team",
        "avatar": {
          "url": "",
          "color": "#4ba984"
        },
        "message": {
          "id": 1201,
          "text": "Task update is ready",
          "authorId": 1,
          "date": "2026-06-03T16:51:12+00:00",
          "file": false,
          "attach": false,
          "sticker": null,
          "status": "received"
        },
        "lastId": 1195,
        "pinned": false,
        "unread": false,
        "counter": 0,
        "dateUpdate": "2026-06-03T16:51:12+00:00",
        "dateLastActivity": "2026-06-03T16:51:12+00:00",
        "chat": {
          "id": 456,
          "name": "Development team",
          "type": "chat",
          "owner": 1,
          "userCounter": 5,
          "role": "OWNER",
          "entityType": "",
          "entityId": ""
        }
      },
      {
        "id": "chat123",
        "chatId": 123,
        "type": "crm",
        "title": "Deal chat",
        "avatar": {
          "url": "",
          "color": "#f76187"
        },
        "message": {
          "id": 980,
          "text": "Contract approved",
          "authorId": 7,
          "date": "2026-06-02T14:08:10+00:00",
          "file": false,
          "attach": false,
          "sticker": null,
          "status": "received"
        },
        "lastId": 0,
        "pinned": false,
        "unread": false,
        "counter": 0,
        "dateUpdate": "2026-06-02T14:08:10+00:00",
        "dateLastActivity": "2026-06-02T14:08:10+00:00",
        "chat": {
          "id": 123,
          "name": "Deal chat",
          "type": "crm",
          "owner": 1,
          "userCounter": 2,
          "role": "MEMBER",
          "entityType": "CRM",
          "entityId": "DEAL|42"
        }
      }
    ],
    "hasMorePages": true,
    "hasMore": true
  }
}

Delta mode. The main item fields are shown; the full set is in the table above:

{
  "success": true,
  "data": [
    {
      "id": "chat456",
      "chatId": 456,
      "type": "chat",
      "title": "Development team",
      "pinned": false,
      "unread": false,
      "counter": 0,
      "dateUpdate": "2026-06-29T10:12:44+00:00",
      "dateLastActivity": "2026-06-29T10:12:44+00:00"
    }
  ],
  "meta": {
    "mode": "delta",
    "returned": 1
  }
}

Error response example

403 — no im scope:

{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'im' scope"
  }
}

Errors

Full list of common API errors — Errors.

Known specifics

• The skipOpenLines and onlyOpenLines flags are mutually exclusive: enabling both yields a result in which no Open Channels chat appears in the list.
• In legacy mode a deep offset is forwarded to Bitrix24. A small window is read from one buffered page, and a hollow boundary row may require one refill. This preserves the pre-Stage-2 bd93898 behavior; new activity between requests can still reorder the list. In legacy mode the date bound is inclusive: pass the last unpinned item’s dateLastActivity, omit offset and deduplicate by chatId. Pinned rows and rows with the same boundary date may repeat. If the cursor does not advance, increase limit up to 200.
• The response contains a data.copilot field with the configuration of the Bitrix24 account's AI assistant. The structure is used to display roles in the Bitrix24 interface and is not part of the list of dialogs.
• In delta mode a dialog whose dateUpdate cannot be read stays in the response: an extra record is safer than a lost change.
• The skip* and only* filter families and unreadOnly apply in delta mode as well, narrowing the page that is scanned.
• In the v2 mode, keys that name fields are converted to camelCase, while keys that are data stay as they are: the data.copilot.roles dictionary is keyed by the role code, and copilot_assistant arrives as copilot_assistant — the same value that role carries on a chat, so a role is found directly as roles[role].
• On a Bitrix24 account without the v2 methods, the mode responds with 422 BITRIX_ERROR and the Bitrix24 error code in error.b24Code, and does not silently fall back to the legacy response: the response shape is different.

See also

• Search chats by text
• Find a CRM entity chat
• Dialog details
• Chat discovery