## Recent dialogs

`GET /v1/chats/recent`

Returns the list of the current user's recent dialogs, sorted by the date of the last message. Each item contains brief information about the dialog, the last message, and the unread counter.

## Parameters

| Parameter | Type | Required | Default | Description |
|----------|-----|:-----:|-----------|---------|
| `skipOpenLines` | string | no | — | Exclude Open Channels conversations. Accepts `true`, `Y`, or `y` |
| `skipChat` | string | no | — | Exclude group chats. Accepts `true`, `Y`, or `y` |
| `skipDialog` | string | no | — | Exclude private dialogs. Accepts `true`, `Y`, or `y` |
| `unreadOnly` | string | no | — | Only dialogs with unread messages. Accepts `true`, `Y`, or `y` |
| `onlyOpenLines` | string | no | — | Only Open Channels conversations. Accepts `true`, `Y`, or `y` |
| `onlyCopilot` | string | no | — | Only chats with the AI assistant. Accepts `true`, `Y`, or `y` |
| `onlyChannel` | string | no | — | Only channels. Accepts `true`, `Y`, or `y` |
| `lastMessageDate` | string | no | — | Date of the last message for pagination (ISO 8601) |
| `limit` | number | no | — | Number of items in the response. Maximum 200 |
| `offset` | number | no | `0` | Offset for pagination |

## Examples

### curl — personal key

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

### curl — OAuth application

```bash
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

```javascript
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

```javascript
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

| Field | Type | Description |
|------|-----|---------|
| `data` | object | Result object |
| `data.items` | array | Array of recent dialogs |
| `data.items[].id` | string | Dialog identifier (`chatXXX` for a group chat or a numeric ID for a private dialog) |
| `data.items[].chatId` | number | Numeric chat ID |
| `data.items[].type` | string | Dialog type: `chat`, `openlines`, `copilot`, `channel` |
| `data.items[].title` | string | Dialog title |
| `data.items[].avatar` | object | Dialog avatar |
| `data.items[].avatar.url` | string | Avatar image URL. Empty string if the avatar is not set |
| `data.items[].avatar.color` | string | Avatar color in hexadecimal format, for example `#4ba984` |
| `data.items[].message` | object | Last message in the dialog |
| `data.items[].message.id` | number | Message ID |
| `data.items[].message.text` | string | Message text |
| `data.items[].message.authorId` | number | Message author ID |
| `data.items[].message.date` | string | Message date (ISO 8601) |
| `data.items[].message.file` | boolean | Whether the message contains a file |
| `data.items[].message.attach` | boolean | Whether the message contains an attachment |
| `data.items[].message.sticker` | string \| null | Message sticker or `null` |
| `data.items[].message.status` | string | Message status (for example, `received`) |
| `data.items[].lastId` | number | ID of the last read message |
| `data.items[].unread` | boolean | Whether there are unread messages |
| `data.items[].counter` | number | Number of unread messages |
| `data.items[].pinned` | boolean | Dialog is pinned |
| `data.items[].dateUpdate` | string | Date of the last dialog update (ISO 8601) |
| `data.items[].dateLastActivity` | string | Date of the last activity (ISO 8601) |
| `data.items[].chat` | object | Extended chat information |
| `data.items[].chat.id` | number | Numeric chat ID |
| `data.items[].chat.name` | string | System chat name |
| `data.items[].chat.type` | string | Chat type: `chat`, `general`, `openlines`, `copilot`, `channel`, `mail`, `crm`, and others |
| `data.items[].chat.owner` | number | Chat owner ID |
| `data.items[].chat.userCounter` | number | Number of members |
| `data.items[].chat.role` | string | Role of the current user: `OWNER`, `MANAGER`, `MEMBER` |
| `data.items[].chat.entityType` | string | Type of the linked entity (`CRM`, `TASKS`, `MAIL`, `GENERAL`, and others) |
| `data.items[].chat.entityId` | string | ID of the linked entity |
| `data.hasMorePages` | boolean | `true` if there is a next page |
| `data.hasMore` | boolean | Duplicates `hasMorePages`. Kept for backward compatibility |

## Response example

```json
{
  "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
  }
}
```

## Error response example

403 — no `im` scope:

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

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 403 | `SCOPE_DENIED` | The API key does not have the `im` scope |
| 401 | `TOKEN_MISSING` | The API key has no Bitrix24 tokens configured |
| 422 | `BITRIX_ERROR` | Bitrix24 returned an error (details in `message`) |
| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 is unavailable or returned a server error |

The full list of general API errors — [Errors](/docs/errors).

## Known specifics

- The `skipOpenLines` and `onlyOpenLines` flags are mutually exclusive: enabling both leads to a result in which none of the Open Channels chats make it into the list.
- The `lastMessageDate` parameter is used for pagination: pass the `dateLastActivity` value of the last item of the current page to get the next batch. Also pass `offset` to avoid duplicate records at the page boundary.
- 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.

## See also

- [Search chats by text](/docs/chats/discovery/search)
- [Find a CRM entity chat](/docs/chats/discovery/find)
- [Dialog details](/docs/chats/discovery/get)
- [Chat discovery](/docs/chats/discovery)