## Список каналов `GET /v1/chats/recent/channels` Возвращает открытые каналы портала страницами — от канала с самым свежим сообщением к более старым. Подходит для витрины каналов, на которые пользователь может подписаться. ## Параметры | Параметр | Тип | Обяз. | По умолч. | Описание | |----------|-----|:-----:|-----------|---------| | `limit` (query) | integer | нет | 50 | Строк на странице, от 1 до 200. Меньшее значение поднимается до 1, большее срезается до 200, оба раза с эхом в `meta` | | `lastMessageId` (query) | integer | нет | — | Курсор следующей страницы — наименьший положительный `messageId` среди строк предыдущей страницы. На первой странице не передаётся | Другие параметры и повторы отклоняются с `400 INVALID_PARAMS`. **Обход.** Строки упорядочены по ID последнего сообщения канала, от большего к меньшему. Следующую страницу запрашивайте с `lastMessageId`, равным наименьшему положительному `messageId` текущей страницы. Граница строгая: канал с этим `messageId` на следующей странице не повторяется. Конец списка — только `hasNextPage: false`. Если при `hasNextPage: true` на странице нет строки с положительным `messageId`, повторите запрос с бо́льшим `limit`, вплоть до 200. ## Примеры ### curl — личный ключ ```bash curl "https://vibecode.bitrix24.tech/v1/chats/recent/channels?limit=50" \ -H "X-Api-Key: YOUR_API_KEY" ``` ### curl — OAuth-приложение ```bash curl "https://vibecode.bitrix24.tech/v1/chats/recent/channels?limit=50" \ -H "X-Api-Key: YOUR_APP_KEY" \ -H "Authorization: Bearer USER_SESSION_TOKEN" ``` ### JavaScript — личный ключ ```javascript const channels = [] const seen = new Set() let limit = 50 let cursor for (;;) { const url = new URL('https://vibecode.bitrix24.tech/v1/chats/recent/channels') url.searchParams.set('limit', String(limit)) if (cursor) url.searchParams.set('lastMessageId', String(cursor)) const res = await fetch(url, { headers: { 'X-Api-Key': 'YOUR_API_KEY' } }) const { data } = await res.json() for (const item of data.recentItems) { if (!seen.has(item.chatId)) { seen.add(item.chatId); channels.push(item) } } if (!data.hasNextPage) break const ids = data.recentItems.map((i) => i.messageId).filter((id) => id > 0) const next = ids.length ? Math.min(...ids) : undefined if (next === undefined || (cursor !== undefined && next >= cursor)) { if (limit === 200) throw new Error('Channel cursor did not advance; restart with a full refresh') limit = Math.min(limit * 2, 200) continue } cursor = next limit = 50 } ``` ### JavaScript — OAuth-приложение ```javascript const channels = [] const seen = new Set() let limit = 50 let cursor for (;;) { const url = new URL('https://vibecode.bitrix24.tech/v1/chats/recent/channels') url.searchParams.set('limit', String(limit)) if (cursor) url.searchParams.set('lastMessageId', String(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) { if (!seen.has(item.chatId)) { seen.add(item.chatId); channels.push(item) } } if (!data.hasNextPage) break const ids = data.recentItems.map((i) => i.messageId).filter((id) => id > 0) const next = ids.length ? Math.min(...ids) : undefined if (next === undefined || (cursor !== undefined && next >= cursor)) { if (limit === 200) throw new Error('Channel 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 последнего сообщения канала, `0` у канала без сообщений. Наименьшее положительное значение страницы — курсор следующей | | `data.recentItems[].pinned` | boolean | Канал закреплён у текущего пользователя. На порядок строк не влияет | | `data.recentItems[].dateLastActivity` | null | В этом списке всегда `null`: каналы упорядочены по ID сообщения, а не по дате | | `data.chats` | array | Карточки каналов: `id`, `dialogId`, `name`, `type`, `owner`, `role` текущего пользователя и другие поля чата | | `data.messages` | array | Последние сообщения каналов | | `data.users` | array | Авторы последних сообщений | | `data.recentConfigs` | array | Разделы списка, в которых учитывается каждый канал: `chatId` и `sections` | | `data.hasNextPage` | boolean | `false` — конец списка | | `meta.requestedLimit` | number | Переданный `limit`. Приходит вместе с `appliedLimit`, только когда значение вышло за диапазон от 1 до 200 | | `meta.appliedLimit` | number | Применённый `limit` — только если он был приведён к границе | ## Пример ответа Показаны основные поля: ```json { "success": true, "data": { "recentItems": [ { "dialogId": "chat206", "chatId": 206, "messageId": 329393, "type": "chat", "pinned": false, "unread": false, "dateUpdate": null, "dateLastActivity": null }, { "dialogId": "chat2", "chatId": 2, "messageId": 0, "type": "chat", "pinned": false, "unread": false, "dateUpdate": null, "dateLastActivity": null } ], "chats": [ { "id": 206, "dialogId": "chat206", "name": "Новости компании", "type": "openChannel", "owner": 4, "role": "guest" } ], "messages": [ { "id": 329393, "chatId": 206, "authorId": 4, "date": "2026-09-10T09:15:00+00:00", "text": "Итоги квартала опубликованы" } ], "recentConfigs": [ { "chatId": 206, "sections": ["default", "openChannel", "channel"] } ], "hasNextPage": false } } ``` ## Пример ответа при ошибке 400 — курсор не положительное число: ```json { "success": false, "error": { "code": "INVALID_PARAMS", "message": "`lastMessageId` must be an integer, 1 or more — the smallest positive `messageId` among the rows of the previous page." } } ``` ## Ошибки | HTTP | Код | Описание | |------|-----|---------| | 400 | `INVALID_PARAMS` | Параметр вне `limit` и `lastMessageId`, повтор параметра, нечисловой `limit` или `lastMessageId` меньше `1`. Проверяется до обращения к Битрикс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). ## Известные особенности **В списке все открытые каналы портала, а не только ваши.** Канал, где пользователь не участник, тоже приходит — с ролью `guest` в `data.chats[].role`. **Каналы без сообщений идут последними.** У них `messageId` равен `0`, курсором они не служат. Если такие каналы не помещаются на одну страницу из 200 строк, продолжить за ними нельзя: у следующей страницы не будет курсора. ## Смотрите также - [Последние диалоги](/docs/chats/discovery/recent) - [Список коллаб](/docs/chats/discovery/recent-collabs) - [Внешние чаты раздела](/docs/chats/discovery/recent-external) - [Поиск чатов](/docs/chats/discovery)