Для AI-агентов: markdown этой страницы — /docs-content/chats/discovery/folder-recent.md индекс документации — /llms.txt

Чаты папки

GET /v1/chats/folders/:folderId/recent

Возвращает список последних диалогов одной папки. Папки и их ID — в GET /v1/chats/folders. Ответ и постраничный обход устроены так же, как у списка последних диалогов в режиме v2: в data приходит объект v2 — recentItems и коллекции chats, users, messages, files — с ключами в формате camelCase.

Параметры

Параметр	Тип	Обяз.	По умолч.	Описание
`folderId` (path)	number	да	—	ID папки, положительное целое
`limit` (query)	number	нет	50	Строк на странице, от 50 до 200: меньшее значение поднимается до 50, большее срезается до 200, оба раза с эхом в `meta.requestedLimit` и `meta.appliedLimit`
`lastMessageDate` (query)	string	нет	—	Курсор следующей страницы, формат `YYYY-MM-DDTHH:MM:SS` со смещением или `Z`, без долей секунды. На первой странице не передаётся
`unreadOnly` (query)	boolean	нет	`false`	`true` — только чаты с непрочитанным. Личная папка этот фильтр не применяет

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

Обход. Курсор следующей страницы — наименьшая непустая dateLastActivity среди незакреплённых строк текущей страницы. Сравнивайте моменты времени, а не строки. Граница включительная. Конец списка — только hasNextPage: false. Если при hasNextPage: true курсора нет или он равен прежнему, повторите запрос с бо́льшим limit, вплоть до 200. true без продвижения и при 200 — отказ, а не конец списка. Строки в ответе повторяются: закреплённые открывают страницы — у системной папки первую, у личной и следующие, — а папка всех чатов подмешивает коллег, с которыми ещё нет переписки. Повторы снимайте по dialogId.

Примеры

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

Terminal

curl "https://vibecode.bitrix24.tech/v1/chats/folders/1/recent?limit=200" \
  -H "X-Api-Key: YOUR_API_KEY"

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

Terminal

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

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

javascript

// Полный обход папки страницами по 200 строк
const seen = new Map()
let cursor = null
for (;;) {
  const qs = new URLSearchParams({ limit: '200' })
  if (cursor) qs.set('lastMessageDate', cursor)
  const res = await fetch(`https://vibecode.bitrix24.tech/v1/chats/folders/1/recent?${qs}`, {
    headers: { 'X-Api-Key': 'YOUR_API_KEY' },
  })
  const { data } = await res.json()
  for (const row of data.recentItems) seen.set(row.dialogId, row)
  if (!data.hasNextPage) break
  const dates = data.recentItems
    .filter((r) => !r.pinned && r.dateLastActivity)
    .map((r) => r.dateLastActivity)
  const next = dates.sort((a, b) => Date.parse(a) - Date.parse(b))[0]
  // При limit=200 курсор без продвижения — отказ, а не конец списка
  if (!next || (cursor && Date.parse(next) === Date.parse(cursor))) throw new Error('Курсор не продвинулся')
  cursor = next
}
console.log('Чатов в папке:', seen.size)

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

javascript

const res = await fetch('https://vibecode.bitrix24.tech/v1/chats/folders/1/recent?limit=200', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data } = await res.json()

Поля ответа

Поле	Тип	Описание
`success`	boolean	Всегда `true` при успехе
`data.recentItems`	array	Строки списка: закреплённые первыми, далее по активности
`data.recentItems[].dialogId`	string	ID диалога (`chatXXX` или ID пользователя) — ключ для снятия повторов
`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	Чаты строк
`data.users`	array	Пользователи строк
`data.messages`	array	Последние сообщения строк
`data.files`	array	Файлы последних сообщений
`data.hasNextPage`	boolean	`false` — конец списка
`meta.requestedLimit`	number	Переданный `limit`. Приходит вместе с `appliedLimit`, только когда значение меньше 50 или больше 200
`meta.appliedLimit`	number	Применённое значение `limit` — только если он был приведён к границе

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

JSON

{
  "success": true,
  "data": {
    "recentItems": [
      {
        "dialogId": "chat42",
        "chatId": 42,
        "messageId": 1002,
        "type": "chat",
        "pinned": false,
        "unread": false,
        "options": [],
        "invited": false,
        "lastReadMessageId": 1002,
        "dateUpdate": "2026-09-20T10:01:00+03:00",
        "dateLastActivity": "2026-09-20T10:01:00+03:00",
        "ownMessageId": 1001
      }
    ],
    "chats": [
      { "id": 42, "dialogId": "chat42", "name": "Проект", "type": "chat", "owner": 5, "role": "member" }
    ],
    "users": [
      { "id": 7, "active": true, "name": "Иван Петров", "firstName": "Иван", "lastName": "Петров", "type": "user" }
    ],
    "messages": [
      { "id": 1002, "chatId": 42, "authorId": 7, "date": "2026-09-20T10:01:00+03:00", "text": "Макет готов" }
    ],
    "files": [],
    "hasNextPage": false
  }
}

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

422 — папки нет: