Chat discovery

Find the chat you need: list of recent dialogs, the chat of a specific CRM entity, text search, and details of an individual dialog.

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 reads differently depending on the server time zone, so the instant has to be stated unambiguously.

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

The full list of general 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.
• Ordering between pages by offset is guaranteed while the window together with the headroom for under-hydrated rows fits inside one Bitrix24 page: a call returns at most 200 records and the headroom for under-hydrated rows is 10, so the boundary falls where offset plus page size stays at or below 190. Within that boundary Vibecode slices the window on its own side, so neighbouring pages neither overlap nor drop a dialog. Past that boundary the offset is forwarded to Bitrix24, where the list is rebuilt on every new message, and neighbouring pages may overlap or skip a dialog again.
• 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*, only*, and unreadOnly filter families apply in delta mode as well, narrowing the page that is scanned.

See also

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