## Папки чатов

`GET /v1/chats/folders`

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

## Параметры

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

## Примеры

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

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

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

```bash
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 — [Ошибки](/docs/errors).

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

- При первом обращении или сбросе кеша вызов может создать системные папки, перенести старые закрепления и заполнить источники папок. Поэтому ключ только для чтения получает `403 WRITE_BLOCKED_READONLY_KEY` до вызова портала. [Список чатов папки](/docs/chats/discovery/folder-recent) остаётся чтением.
- Не у каждой системной папки есть список чатов: витрина открытых каналов на запрос списка отвечает кодом `FOLDER_OPERATION_NOT_SUPPORTED`.

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

- [Чаты папки](/docs/chats/discovery/folder-recent)
- [Последние диалоги](/docs/chats/discovery/recent)
- [Счётчики непрочитанного](/docs/chats/discovery/counters)
- [Поиск чатов](/docs/chats/discovery)