## Список файлов чата

`GET /v1/chats/:chatId/files`

Возвращает страницу файлов, отправленных в чат: те же вложения, что на вкладках «Медиа», «Файлы» и «Голосовые» правой панели чата. Обязательный параметр `group` задаёт, какие из этих вкладок попадут в выборку.

## Параметры

| Параметр | Тип | Обяз. | Описание |
|----------|-----|:-----:|---------|
| `chatId` (path) | number | да | ID чата. Получить: [`GET /v1/chats/recent`](/docs/chats/discovery/recent) |
| `group` (query) | string | да | Вкладки правой панели чата через запятую, каждая один раз: `MEDIA` — «Медиа», `FILE` — «Файлы», `AUDIO` — «Голосовые». Все три сразу — `MEDIA,FILE,AUDIO`. Значения пишутся заглавными буквами |
| `limit` (query) | number | нет | Сколько записей `data.list` вернуть, от 1 до 200. Значение вне диапазона приводится к ближайшей границе, тогда в ответе приходят `meta.requestedLimit` и `meta.appliedLimit` |
| `lastId` (query) | number | нет | Курсор следующей страницы: `id` последней записи `data.list` из предыдущего ответа |
| `lastDate` (query) | string | нет | Дата для курсора: `dateCreate` той же последней записи, в формате RFC 3339 без долей секунды, например `2026-11-09T10:00:00+03:00`. Передаётся только вместе с `lastId`. При `order=date` обязательна вместе с `lastId` |
| `order` (query) | string | нет | Единственное значение — `date`: сортировка по дате загрузки, новые первыми. Принимается только с `group=AUDIO`. Без параметра записи идут по убыванию `id` |
| `search` (query) | string | нет | Оставляет файлы, имя которых начинается с этого текста. Пустая строка не принимается |

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

## Примеры

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

```bash
curl "https://vibecode.bitrix24.tech/v1/chats/1001/files?group=MEDIA,FILE,AUDIO&limit=50" \
  -H "X-Api-Key: YOUR_API_KEY"
```

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

```bash
curl "https://vibecode.bitrix24.tech/v1/chats/1001/files?group=MEDIA,FILE,AUDIO&limit=50" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

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

```javascript
const params = new URLSearchParams({ group: 'MEDIA,FILE,AUDIO', limit: '50' })

const res = await fetch(`https://vibecode.bitrix24.tech/v1/chats/1001/files?${params}`, {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log('Records:', data.list.length, 'Files:', data.files.length)
```

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

```javascript
const params = new URLSearchParams({ group: 'MEDIA,FILE,AUDIO', limit: '50' })

const res = await fetch(`https://vibecode.bitrix24.tech/v1/chats/1001/files?${params}`, {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()
console.log('Records:', data.list.length, 'Files:', data.files.length)
```

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

| Поле | Тип | Описание |
|------|-----|---------|
| `success` | boolean | Всегда `true` при успехе |
| `data.list` | array | Записи о вложениях, по одной на каждую отправку файла в сообщении. Один файл, отправленный дважды, даёт две записи |
| `data.list[].id` | number | ID записи. Значение для `lastId` следующей страницы |
| `data.list[].messageId` | number | ID сообщения с вложением |
| `data.list[].chatId` | number | ID чата |
| `data.list[].authorId` | number | ID отправителя, карточка — в `data.users` |
| `data.list[].dateCreate` | string | Дата отправки (ISO 8601). Значение для `lastDate` следующей страницы |
| `data.list[].fileId` | number | ID файла, карточка — в `data.files` |
| `data.list[].subType` | string | Подтип вложения, например `other` |
| `data.list[].group` | string | Категория в нижнем регистре: `media`, `file`, `audio` |
| `data.files` | array | Файлы, на которые ссылаются записи `data.list`, каждый один раз |
| `data.files[].id` | number | ID файла. Нужен для [сохранения на Диск](/docs/chats/files/save), [расшифровки](/docs/chats/files/transcribe) и скачивания через [`GET /v1/files/:fileId/download`](/docs/entities/files/download) |
| `data.files[].chatId` | number | ID чата |
| `data.files[].date` | string | Дата загрузки файла (ISO 8601) |
| `data.files[].type` | string | Тип файла: `file`, `image`, `audio`, `video` и другие |
| `data.files[].name` | string | Имя файла |
| `data.files[].extension` | string | Расширение в нижнем регистре |
| `data.files[].size` | number | Размер в байтах |
| `data.files[].authorId` | number | ID автора файла |
| `data.files[].authorName` | string | Имя автора файла |
| `data.files[].urlDownload` | string | Ссылка на файл в Битрикс24. Открывается только в сессии пользователя в Битрикс24 |
| `data.files[].urlShow` | string | Ссылка на просмотр в Битрикс24, в той же сессии |
| `data.files[].urlPreview` | string | Ссылка на превью. Пустая строка, если превью нет |
| `data.files[].isTranscribable` | boolean | Файл можно [расшифровать](/docs/chats/files/transcribe) |
| `data.files[].isVoiceNote` | boolean | Голосовое сообщение |
| `data.files[].isVideoNote` | boolean | Видеосообщение |
| `data.files[].duration` | number\|null | Длительность записи. Может быть `null` |
| `data.users` | array | Отправители и авторы файлов. Поля — как у участника в [списке участников чата](/docs/chats/members/list): `id`, `name`, `firstName`, `lastName`, `active`, `type` и другие |
| `data.tariffRestrictions.isHistoryLimitExceeded` | boolean | `true`, когда тариф скрывает часть старой истории чата и её файлы не попадают в выдачу |
| `meta.requestedLimit` | number | Переданный `limit`. Только когда он вне диапазона 1–200 |
| `meta.appliedLimit` | number | Применённый `limit` после приведения к границе. Только вместе с `meta.requestedLimit` |

Кроме перечисленных, файл несёт поля Битрикс24 для отображения — `image`, `status`, `progress`, `viewerAttrs`, `mediaUrl`.

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

Показаны две записи о двух отправках одного файла. Карточка сотрудника сокращена до основных полей:

```json
{
  "success": true,
  "data": {
    "users": [
      {
        "id": 1,
        "active": true,
        "name": "Анна Смирнова",
        "firstName": "Анна",
        "lastName": "Смирнова",
        "workPosition": "",
        "bot": false,
        "extranet": false,
        "status": "online",
        "type": "user"
      }
    ],
    "files": [
      {
        "id": 8851,
        "chatId": 1001,
        "date": "2025-07-04T14:17:35+03:00",
        "type": "file",
        "name": "presentation.mp4",
        "extension": "mp4",
        "size": 2679128,
        "image": false,
        "status": "done",
        "progress": 100,
        "authorId": 1,
        "authorName": "Анна Смирнова",
        "urlPreview": "https://example.bitrix24.ru/bitrix/services/main/ajax.php?action=disk.api.file.showPreview&fileId=8851&fileName=preview.jpg",
        "urlShow": "https://example.bitrix24.ru/bitrix/services/main/ajax.php?action=disk.api.file.download&fileId=8851&fileName=presentation.mp4",
        "urlDownload": "https://example.bitrix24.ru/bitrix/services/main/ajax.php?action=disk.api.file.download&fileId=8851&fileName=presentation.mp4",
        "viewerAttrs": {
          "viewerType": "video",
          "objectId": "8851",
          "imChatId": 1001,
          "title": "presentation.mp4"
        },
        "mediaUrl": {
          "preview": {
            "250": "https://example.bitrix24.ru/bitrix/services/main/ajax.php?action=disk.api.file.showPreview&fileId=8851&width=250&height=250&fileName=preview.jpg"
          }
        },
        "isTranscribable": false,
        "isVideoNote": false,
        "isVoiceNote": false,
        "duration": null
      }
    ],
    "tariffRestrictions": {
      "isHistoryLimitExceeded": false
    },
    "list": [
      {
        "id": 111,
        "messageId": 34213,
        "chatId": 1001,
        "authorId": 1,
        "dateCreate": "2026-03-03T11:44:09+03:00",
        "fileId": 8851,
        "subType": "other",
        "group": "file"
      },
      {
        "id": 109,
        "messageId": 34211,
        "chatId": 1001,
        "authorId": 1,
        "dateCreate": "2026-03-03T11:43:35+03:00",
        "fileId": 8851,
        "subType": "other",
        "group": "file"
      }
    ]
  }
}
```

При `limit=500` ответ дополнительно несёт `"meta": { "requestedLimit": 500, "appliedLimit": 200 }`.

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

400 — не передан `group`. Проверяется до обращения в Битрикс24:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "`group` is required: one or more of MEDIA, FILE, AUDIO, separated by commas, each once."
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 400 | `INVALID_CHAT_ID` | `chatId` не является положительным целым числом. Проверяется до обращения в Битрикс24 |
| 400 | `INVALID_PARAMS` | Не передан `group`, в нём значение не из `MEDIA`, `FILE`, `AUDIO` или повтор. `limit` не целое число, `lastId` не положительное целое, `lastDate` без `lastId` или не в формате RFC 3339. `order` не `date` или без `group=AUDIO`. Пустой `search`. Неизвестный параметр запроса — сообщение называет его и перечисляет допустимые |
| 422 | `BITRIX_ERROR` | `error.b24Code` равен `ACCESS_ERROR` — у сотрудника нет доступа к чату или чата нет |
| 422 | `BITRIX_ERROR` | `error.b24Code` равен `FILE_CURSOR_INCOMPLETE` — при `order=date` передан `lastId` без `lastDate` |
| 404 | `ENTITY_NOT_FOUND` | Битрикс24 вернул общую ошибку NOT_FOUND, код портала — в `error.b24Code` |
| 403 | `SCOPE_DENIED` | Ключу не хватает скоупа `im` |
| 401 | `TOKEN_MISSING` | Ключ не имеет настроенных токенов Битрикс24 |
| 401 | `MISSING_API_KEY` | Не передан `X-Api-Key` |

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

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

- **Конец выдачи.** Страница, в которой записей `data.list` меньше `limit`, — последняя.
- **Скачивание из приложения.** Для [`GET /v1/files/:fileId/download`](/docs/entities/files/download) скоупа `im` недостаточно — нужен `disk` или `crm`.

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

- [Файлы чатов](/docs/chats/files)
- [Загрузить файл в чат](/docs/chats/files/upload)
- [Метаданные файла](/docs/chats/files/file-get)
- [Сохранить файлы на Диск](/docs/chats/files/save)
