## Chat file list

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

Returns a page of files sent to a chat: the same attachments shown on the Media, Files, and Voice tabs of the chat's right panel. The required `group` parameter sets which of these tabs are included.

## Parameters

| Parameter | Type | Required | Description |
|----------|-----|:-----:|---------|
| `chatId` (path) | number | yes | Chat ID. Get it: [`GET /v1/chats/recent`](/docs/chats/discovery/recent) |
| `group` (query) | string | yes | Tabs of the chat's right panel, comma-separated, each once: `MEDIA` — Media, `FILE` — Files, `AUDIO` — Voice. All three at once — `MEDIA,FILE,AUDIO`. Values are uppercase |
| `limit` (query) | number | no | How many `data.list` records to return, from 1 to 200. An out-of-range value is clamped to the nearest bound, and the response then includes `meta.requestedLimit` and `meta.appliedLimit` |
| `lastId` (query) | number | no | Next-page cursor: the `id` of the last `data.list` record from the previous response |
| `lastDate` (query) | string | no | Cursor date: the `dateCreate` of that same last record, in RFC 3339 format without fractional seconds, for example `2026-11-09T10:00:00+00:00`. Passed only together with `lastId`. Required together with `lastId` when `order=date` |
| `order` (query) | string | no | The only value is `date`: sort by upload date, newest first. Accepted only with `group=AUDIO`. Without the parameter, records are ordered by descending `id` |
| `search` (query) | string | no | Keeps files whose name starts with this text. An empty string is not accepted |

Other query parameters are not accepted: the method returns `400 INVALID_PARAMS` and lists the allowed ones.

## Examples

### curl — personal key

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

### curl — OAuth application

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

### JavaScript — personal key

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

const res = await fetch(`https://vibecode.bitrix24.com/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 application

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

const res = await fetch(`https://vibecode.bitrix24.com/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)
```

## Response fields

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data.list` | array | Attachment records, one per file sent in a message. One file sent twice produces two records |
| `data.list[].id` | number | Record ID. The value for `lastId` on the next page |
| `data.list[].messageId` | number | ID of the message with the attachment |
| `data.list[].chatId` | number | Chat ID |
| `data.list[].authorId` | number | Sender ID; the profile is in `data.users` |
| `data.list[].dateCreate` | string | Send date (ISO 8601). The value for `lastDate` on the next page |
| `data.list[].fileId` | number | File ID; the file card is in `data.files` |
| `data.list[].subType` | string | Attachment subtype, for example `other` |
| `data.list[].group` | string | Lowercase category: `media`, `file`, `audio` |
| `data.files` | array | Files referenced by `data.list` records, each once |
| `data.files[].id` | number | File ID. Needed to [save to Drive](/docs/chats/files/save), [transcribe](/docs/chats/files/transcribe), and download via [`GET /v1/files/:fileId/download`](/docs/entities/files/download) |
| `data.files[].chatId` | number | Chat ID |
| `data.files[].date` | string | File upload date (ISO 8601) |
| `data.files[].type` | string | File type: `file`, `image`, `audio`, `video`, and others |
| `data.files[].name` | string | File name |
| `data.files[].extension` | string | Lowercase extension |
| `data.files[].size` | number | Size in bytes |
| `data.files[].authorId` | number | File author ID |
| `data.files[].authorName` | string | File author name |
| `data.files[].urlDownload` | string | Link to the file in Bitrix24. Opens only within the user's Bitrix24 session |
| `data.files[].urlShow` | string | Link to the viewer in Bitrix24, within the same session |
| `data.files[].urlPreview` | string | Link to the preview. An empty string if there is no preview |
| `data.files[].isTranscribable` | boolean | The file can be [transcribed](/docs/chats/files/transcribe) |
| `data.files[].isVoiceNote` | boolean | Voice message |
| `data.files[].isVideoNote` | boolean | Video message |
| `data.files[].duration` | number\|null | Recording duration. May be `null` |
| `data.users` | array | Senders and file authors. Fields are the same as for a member in the [chat member list](/docs/chats/members/list): `id`, `name`, `firstName`, `lastName`, `active`, `type`, and others |
| `data.tariffRestrictions.isHistoryLimitExceeded` | boolean | `true` when the plan hides part of the chat's older history and its files are not included in the results |
| `meta.requestedLimit` | number | The `limit` passed. Only when it is outside the 1–200 range |
| `meta.appliedLimit` | number | The `limit` applied after clamping to the bound. Only together with `meta.requestedLimit` |

Besides the fields listed, a file carries Bitrix24 display fields: `image`, `status`, `progress`, `viewerAttrs`, `mediaUrl`.

## Response example

The example shows two records for two sends of the same file. The employee profile is trimmed to the main fields:

```json
{
  "success": true,
  "data": {
    "users": [
      {
        "id": 1,
        "active": true,
        "name": "Anna Smith",
        "firstName": "Anna",
        "lastName": "Smith",
        "workPosition": "",
        "bot": false,
        "extranet": false,
        "status": "online",
        "type": "user"
      }
    ],
    "files": [
      {
        "id": 8851,
        "chatId": 1001,
        "date": "2025-07-04T14:17:35+00:00",
        "type": "file",
        "name": "presentation.mp4",
        "extension": "mp4",
        "size": 2679128,
        "image": false,
        "status": "done",
        "progress": 100,
        "authorId": 1,
        "authorName": "Anna Smith",
        "urlPreview": "https://example.bitrix24.com/bitrix/services/main/ajax.php?action=disk.api.file.showPreview&fileId=8851&fileName=preview.jpg",
        "urlShow": "https://example.bitrix24.com/bitrix/services/main/ajax.php?action=disk.api.file.download&fileId=8851&fileName=presentation.mp4",
        "urlDownload": "https://example.bitrix24.com/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.com/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+00:00",
        "fileId": 8851,
        "subType": "other",
        "group": "file"
      },
      {
        "id": 109,
        "messageId": 34211,
        "chatId": 1001,
        "authorId": 1,
        "dateCreate": "2026-03-03T11:43:35+00:00",
        "fileId": 8851,
        "subType": "other",
        "group": "file"
      }
    ]
  }
}
```

With `limit=500`, the response also carries `"meta": { "requestedLimit": 500, "appliedLimit": 200 }`.

## Error response example

400 — `group` not passed. Checked before the request reaches Bitrix24:

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

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 400 | `INVALID_CHAT_ID` | `chatId` is not a positive integer. Checked before the request reaches Bitrix24 |
| 400 | `INVALID_PARAMS` | `group` is missing, contains a value other than `MEDIA`, `FILE`, `AUDIO`, or repeats a value. `limit` is not an integer, `lastId` is not a positive integer, `lastDate` without `lastId` or not in RFC 3339 format. `order` is not `date` or is passed without `group=AUDIO`. Empty `search`. Unknown query parameter — the message names it and lists the allowed ones |
| 422 | `BITRIX_ERROR` | `error.b24Code` is `ACCESS_ERROR` — the employee has no access to the chat, or the chat does not exist |
| 422 | `BITRIX_ERROR` | `error.b24Code` is `FILE_CURSOR_INCOMPLETE` — with `order=date`, `lastId` was passed without `lastDate` |
| 404 | `ENTITY_NOT_FOUND` | Bitrix24 returned a generic NOT_FOUND error; the Bitrix24 code is in `error.b24Code` |
| 403 | `SCOPE_DENIED` | The key lacks the `im` scope |
| 401 | `TOKEN_MISSING` | The key has no Bitrix24 tokens configured |
| 401 | `MISSING_API_KEY` | `X-Api-Key` not passed |

Full list of common API errors — [Errors](/docs/errors).

## Known specifics

- **End of results.** A page with fewer `data.list` records than `limit` is the last one.
- **Downloading from an application.** The `im` scope is not enough for [`GET /v1/files/:fileId/download`](/docs/entities/files/download) — `disk` or `crm` is required.

## See also

- [Chat files](/docs/chats/files)
- [Upload a file to a chat](/docs/chats/files/upload)
- [File metadata](/docs/chats/files/file-get)
- [Save files to Drive](/docs/chats/files/save)