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

Папки чатов

GET /v1/chats/folders

Возвращает папки чатов текущего пользователя. Системные папки — разделы мессенджера: чаты, задачи, коллабы, открытые линии, витрина открытых каналов и другие, набор зависит от портала. Личные папки пользователь собирает сам из выбранных чатов. Список чатов папки — GET /v1/chats/folders/:folderId/recent.

Параметры

Параметров нет. Любой параметр запроса отклоняется с 400 INVALID_PARAMS.

Примеры

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/chats/folders" \
  -H "X-Api-Key: YOUR_API_KEY"

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/chats/folders" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/chats/folders', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { data } = await res.json()
const personal = data.folders.filter((f) => f.type === 'personal')
console.log('Личных папок:', personal.length)

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

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

const { data } = await res.json()

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data.folders array Папки пользователя
data.folders[].id number ID папки — folderId для списка чатов папки
data.folders[].type string system — раздел мессенджера, personal — личная папка
data.folders[].code string Код системной папки, например default, tasksTask, collab, lines, openChannel. У личной папки поля нет
data.folders[].title string Название папки
data.folders[].sort number Порядок папки в интерфейсе
data.folders[].visible boolean Папка показывается в интерфейсе
data.folders[].description string | null Описание. У личной папки — null
data.folders[].displaysNestedInRoot boolean Вложенные чаты показываются и в корневом списке
data.folders[].definition object Что держит папка. У системной — recentSection (раздел списка) и parentChatId. У личной — chats, список { chatId, dialogId }

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

JSON 
{
  "success": true,
  "data": {
    "folders": [
      {
        "id": 1,
        "type": "system",
        "code": "default",
        "title": "Чаты",
        "sort": 2,
        "visible": true,
        "description": "Все чаты, каналы и проекты",
        "displaysNestedInRoot": false,
        "definition": { "recentSection": "default", "parentChatId": 0 }
      },
      {
        "id": 15,
        "type": "personal",
        "title": "Клиенты",
        "sort": 12,
        "visible": true,
        "description": null,
        "displaysNestedInRoot": false,
        "definition": { "chats": [{ "chatId": 42, "dialogId": "chat42" }] }
      }
    ]
  }
}

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

400 — передан параметр запроса:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Query parameter `type` is not accepted by GET /v1/chats/folders. It takes no query parameters."
  }
}

Ошибки

HTTP Код Описание
400 INVALID_PARAMS Передан параметр запроса — эндпоинт их не принимает
403 SCOPE_DENIED API-ключ не имеет скоупа im
403 WRITE_BLOCKED_READONLY_KEY Ключ только для чтения: список папок может изменить состояние портала
401 TOKEN_MISSING API-ключ не имеет настроенных токенов Битрикс24
422 BITRIX_ERROR Битрикс24 вернул ошибку. Код портала — в error.b24Code
502 BITRIX_UNAVAILABLE Битрикс24 недоступен или вернул ошибку сервера

Полный список общих ошибок API — Ошибки.

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

  • При первом обращении или сбросе кеша вызов может создать системные папки, перенести старые закрепления и заполнить источники папок. Поэтому ключ только для чтения получает 403 WRITE_BLOCKED_READONLY_KEY до вызова портала. Список чатов папки остаётся чтением.
  • Не у каждой системной папки есть список чатов: витрина открытых каналов на запрос списка отвечает кодом FOLDER_OPERATION_NOT_SUPPORTED.

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