## Список коллаб

`GET /v1/chats/recent/collabs`

Возвращает чаты коллаб текущего пользователя страницами: закреплённые первыми, далее по времени последней активности. Подходит для отдельной вкладки коллаб в списке диалогов.

## Параметры

| Параметр | Тип | Обяз. | По умолч. | Описание |
|----------|-----|:-----:|-----------|---------|
| `limit` (query) | integer | нет | 50 | Строк на странице, от 50 до 200. Меньшее значение поднимается до 50, большее срезается до 200, оба раза с эхом в `meta` |
| `lastMessageDate` (query) | string | нет | — | Курсор следующей страницы — наименьшая `dateLastActivity` среди незакреплённых строк предыдущей страницы. Формат `YYYY-MM-DDTHH:MM:SS` со смещением или `Z`, без долей секунды. На первой странице не передаётся |

Другие параметры и повторы отклоняются с `400 INVALID_PARAMS`.

**Обход** — как у [последних диалогов в режиме v2](/docs/chats/discovery/recent). Курсор следующей страницы — наименьшая непустая `dateLastActivity` среди **незакреплённых** строк, сравнивайте моменты времени, а не строки. Граница включительная, а закреплённые чаты открывают каждую страницу — повторы снимайте по `chatId`. Конец списка — только `hasNextPage: false`. Если при `hasNextPage: true` курсора нет или он равен прежнему, повторите запрос с бо́льшим `limit`, вплоть до 200. Строк ответа не отбрасывайте: курсор считается по всему ответу.

## Примеры

### curl — личный ключ

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

### curl — OAuth-приложение

```bash
curl "https://vibecode.bitrix24.tech/v1/chats/recent/collabs?limit=50" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — личный ключ

```javascript
const rows = new Map()
let limit = 50
let cursor
for (;;) {
  const url = new URL('https://vibecode.bitrix24.tech/v1/chats/recent/collabs')
  url.searchParams.set('limit', String(limit))
  if (cursor) url.searchParams.set('lastMessageDate', cursor)
  const res = await fetch(url, { headers: { 'X-Api-Key': 'YOUR_API_KEY' } })
  const { data } = await res.json()
  for (const item of data.recentItems) rows.set(item.chatId, item)
  if (!data.hasNextPage) break
  const dates = data.recentItems.filter((i) => !i.pinned && i.dateLastActivity).map((i) => i.dateLastActivity)
  const next = dates.length ? dates.reduce((a, b) => (Date.parse(a) <= Date.parse(b) ? a : b)) : undefined
  if (!next || (cursor && Date.parse(next) >= Date.parse(cursor))) {
    if (limit === 200) throw new Error('Recent-list cursor did not advance; restart with a full refresh')
    limit = Math.min(limit * 2, 200)
    continue
  }
  cursor = next
  limit = 50
}
```

### JavaScript — OAuth-приложение

```javascript
const rows = new Map()
let limit = 50
let cursor
for (;;) {
  const url = new URL('https://vibecode.bitrix24.tech/v1/chats/recent/collabs')
  url.searchParams.set('limit', String(limit))
  if (cursor) url.searchParams.set('lastMessageDate', cursor)
  const res = await fetch(url, {
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  })
  const { data } = await res.json()
  for (const item of data.recentItems) rows.set(item.chatId, item)
  if (!data.hasNextPage) break
  const dates = data.recentItems.filter((i) => !i.pinned && i.dateLastActivity).map((i) => i.dateLastActivity)
  const next = dates.length ? dates.reduce((a, b) => (Date.parse(a) <= Date.parse(b) ? a : b)) : undefined
  if (!next || (cursor && Date.parse(next) >= Date.parse(cursor))) {
    if (limit === 200) throw new Error('Recent-list cursor did not advance; restart with a full refresh')
    limit = Math.min(limit * 2, 200)
    continue
  }
  cursor = next
  limit = 50
}
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|---------|
| `success` | boolean | Всегда `true` при успехе |
| `data.recentItems` | array | Строки списка в порядке портала — закреплённые первыми, далее по активности |
| `data.recentItems[].dialogId` | string | ID диалога коллабы, `chatXXX` |
| `data.recentItems[].chatId` | number | ID чата — ключ для снятия повторов |
| `data.recentItems[].messageId` | number | ID последнего сообщения |
| `data.recentItems[].pinned` | boolean | Чат закреплён у текущего пользователя |
| `data.recentItems[].unread` | boolean | Чат вручную отмечен непрочитанным |
| `data.recentItems[].dateLastActivity` | string\|null | Момент последней активности. Наименьшее значение среди незакреплённых строк — курсор следующей страницы |
| `data.chats` | array | Карточки чатов коллаб: `id`, `dialogId`, `name`, `type` со значением `collab`, `entityType` со значением `SONET_GROUP`, `entityId` — ID группы, `role` текущего пользователя и другие поля чата |
| `data.messages` | array | Последние сообщения чатов |
| `data.users` | array | Авторы последних сообщений |
| `data.files` | array | Файлы последних сообщений |
| `data.recentConfigs` | array | Разделы списка, в которых учитывается каждый чат: `chatId` и `sections` |
| `data.hasNextPage` | boolean | `false` — конец списка |
| `meta.requestedLimit` | number | Переданный `limit`. Приходит вместе с `appliedLimit`, только когда значение вышло за диапазон от 50 до 200 |
| `meta.appliedLimit` | number | Применённый `limit` — только если он был приведён к границе |

## Пример ответа

Показаны основные поля, `limit=10` поднят до 50:

```json
{
  "success": true,
  "data": {
    "recentItems": [
      {
        "dialogId": "chat53",
        "chatId": 53,
        "messageId": 413,
        "type": "chat",
        "pinned": false,
        "unread": false,
        "dateUpdate": "2026-06-15T12:31:26+00:00",
        "dateLastActivity": "2026-04-21T10:55:53+00:00"
      }
    ],
    "chats": [
      {
        "id": 53,
        "dialogId": "chat53",
        "name": "Запуск партнёрской программы",
        "type": "collab",
        "entityType": "SONET_GROUP",
        "entityId": "3",
        "owner": 1,
        "role": "owner"
      }
    ],
    "recentConfigs": [
      { "chatId": 53, "sections": ["default", "collab"] }
    ],
    "hasNextPage": false
  },
  "meta": {
    "requestedLimit": 10,
    "appliedLimit": 50
  }
}
```

## Пример ответа при ошибке

400 — курсор без смещения:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "`lastMessageDate` must be a datetime YYYY-MM-DDTHH:MM:SS with a UTC offset (+03:00) or Z and no fractional seconds — the smallest `dateLastActivity` among the unpinned rows of the previous page."
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 400 | `INVALID_PARAMS` | Параметр вне `limit` и `lastMessageDate`, повтор параметра, нечисловой `limit` или `lastMessageDate` не в формате `YYYY-MM-DDTHH:MM:SS` со смещением или `Z` либо с несуществующей датой или временем (`2026-02-30`, `24:00`). Проверяется до обращения к Битрикс24 |
| 422 | `BITRIX_ERROR` | Битрикс24 вернул ошибку, код портала — в `error.b24Code` |
| 403 | `BITRIX_ACCESS_DENIED` | Битрикс24 отказал в доступе |
| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `im` |
| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов Битрикс24 |
| 502 | `BITRIX_UNAVAILABLE` | Битрикс24 недоступен или вернул ошибку сервера |

Полный список общих ошибок API — [Ошибки](/docs/errors).

## Известные особенности

**Пол `limit` — 50.** Закреплённых чатов бывает до 45, и они повторяются на каждой странице. Страница меньше 50 строк могла бы целиком состоять из повторов и не дать курсора.

**Обход — не снимок.** Коллаба, поднятая новой активностью из-под курсора во время обхода, в нём не появится. После обхода перечитайте первую страницу.

## Смотрите также

- [Последние диалоги](/docs/chats/discovery/recent)
- [Список каналов](/docs/chats/discovery/recent-channels)
- [Внешние чаты раздела](/docs/chats/discovery/recent-external)
- [Поиск чатов](/docs/chats/discovery)