[{"data":1,"prerenderedAt":7},["ShallowReactive",2],{"docs-chats\u002Ffiles\u002Flist":3,"docs-tabs-chats\u002Ffiles\u002Flist":6},{"content":4,"lastmod":5},"## Chat file list\n\n`GET \u002Fv1\u002Fchats\u002F:chatId\u002Ffiles`\n\nReturns 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.\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|----------|-----|:-----:|---------|\n| `chatId` (path) | number | yes | Chat ID. Get it: [`GET \u002Fv1\u002Fchats\u002Frecent`](\u002Fdocs\u002Fchats\u002Fdiscovery\u002Frecent) |\n| `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 |\n| `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` |\n| `lastId` (query) | number | no | Next-page cursor: the `id` of the last `data.list` record from the previous response |\n| `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` |\n| `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` |\n| `search` (query) | string | no | Keeps files whose name starts with this text. An empty string is not accepted |\n\nOther query parameters are not accepted: the method returns `400 INVALID_PARAMS` and lists the allowed ones.\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fchats\u002F1001\u002Ffiles?group=MEDIA,FILE,AUDIO&limit=50\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### curl — OAuth application\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fchats\u002F1001\u002Ffiles?group=MEDIA,FILE,AUDIO&limit=50\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\"\n```\n\n### JavaScript — personal key\n\n```javascript\nconst params = new URLSearchParams({ group: 'MEDIA,FILE,AUDIO', limit: '50' })\n\nconst res = await fetch(`https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fchats\u002F1001\u002Ffiles?${params}`, {\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n  },\n})\n\nconst { success, data } = await res.json()\nconsole.log('Records:', data.list.length, 'Files:', data.files.length)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst params = new URLSearchParams({ group: 'MEDIA,FILE,AUDIO', limit: '50' })\n\nconst res = await fetch(`https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fchats\u002F1001\u002Ffiles?${params}`, {\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n  },\n})\n\nconst { success, data } = await res.json()\nconsole.log('Records:', data.list.length, 'Files:', data.files.length)\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|---------|\n| `success` | boolean | Always `true` on success |\n| `data.list` | array | Attachment records, one per file sent in a message. One file sent twice produces two records |\n| `data.list[].id` | number | Record ID. The value for `lastId` on the next page |\n| `data.list[].messageId` | number | ID of the message with the attachment |\n| `data.list[].chatId` | number | Chat ID |\n| `data.list[].authorId` | number | Sender ID; the profile is in `data.users` |\n| `data.list[].dateCreate` | string | Send date (ISO 8601). The value for `lastDate` on the next page |\n| `data.list[].fileId` | number | File ID; the file card is in `data.files` |\n| `data.list[].subType` | string | Attachment subtype, for example `other` |\n| `data.list[].group` | string | Lowercase category: `media`, `file`, `audio` |\n| `data.files` | array | Files referenced by `data.list` records, each once |\n| `data.files[].id` | number | File ID. Needed to [save to Drive](\u002Fdocs\u002Fchats\u002Ffiles\u002Fsave), [transcribe](\u002Fdocs\u002Fchats\u002Ffiles\u002Ftranscribe), and download via [`GET \u002Fv1\u002Ffiles\u002F:fileId\u002Fdownload`](\u002Fdocs\u002Fentities\u002Ffiles\u002Fdownload) |\n| `data.files[].chatId` | number | Chat ID |\n| `data.files[].date` | string | File upload date (ISO 8601) |\n| `data.files[].type` | string | File type: `file`, `image`, `audio`, `video`, and others |\n| `data.files[].name` | string | File name |\n| `data.files[].extension` | string | Lowercase extension |\n| `data.files[].size` | number | Size in bytes |\n| `data.files[].authorId` | number | File author ID |\n| `data.files[].authorName` | string | File author name |\n| `data.files[].urlDownload` | string | Link to the file in Bitrix24. Opens only within the user's Bitrix24 session |\n| `data.files[].urlShow` | string | Link to the viewer in Bitrix24, within the same session |\n| `data.files[].urlPreview` | string | Link to the preview. An empty string if there is no preview |\n| `data.files[].isTranscribable` | boolean | The file can be [transcribed](\u002Fdocs\u002Fchats\u002Ffiles\u002Ftranscribe) |\n| `data.files[].isVoiceNote` | boolean | Voice message |\n| `data.files[].isVideoNote` | boolean | Video message |\n| `data.files[].duration` | number\\|null | Recording duration. May be `null` |\n| `data.users` | array | Senders and file authors. Fields are the same as for a member in the [chat member list](\u002Fdocs\u002Fchats\u002Fmembers\u002Flist): `id`, `name`, `firstName`, `lastName`, `active`, `type`, and others |\n| `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 |\n| `meta.requestedLimit` | number | The `limit` passed. Only when it is outside the 1–200 range |\n| `meta.appliedLimit` | number | The `limit` applied after clamping to the bound. Only together with `meta.requestedLimit` |\n\nBesides the fields listed, a file carries Bitrix24 display fields: `image`, `status`, `progress`, `viewerAttrs`, `mediaUrl`.\n\n## Response example\n\nThe example shows two records for two sends of the same file. The employee profile is trimmed to the main fields:\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"users\": [\n      {\n        \"id\": 1,\n        \"active\": true,\n        \"name\": \"Anna Smith\",\n        \"firstName\": \"Anna\",\n        \"lastName\": \"Smith\",\n        \"workPosition\": \"\",\n        \"bot\": false,\n        \"extranet\": false,\n        \"status\": \"online\",\n        \"type\": \"user\"\n      }\n    ],\n    \"files\": [\n      {\n        \"id\": 8851,\n        \"chatId\": 1001,\n        \"date\": \"2025-07-04T14:17:35+00:00\",\n        \"type\": \"file\",\n        \"name\": \"presentation.mp4\",\n        \"extension\": \"mp4\",\n        \"size\": 2679128,\n        \"image\": false,\n        \"status\": \"done\",\n        \"progress\": 100,\n        \"authorId\": 1,\n        \"authorName\": \"Anna Smith\",\n        \"urlPreview\": \"https:\u002F\u002Fexample.bitrix24.com\u002Fbitrix\u002Fservices\u002Fmain\u002Fajax.php?action=disk.api.file.showPreview&fileId=8851&fileName=preview.jpg\",\n        \"urlShow\": \"https:\u002F\u002Fexample.bitrix24.com\u002Fbitrix\u002Fservices\u002Fmain\u002Fajax.php?action=disk.api.file.download&fileId=8851&fileName=presentation.mp4\",\n        \"urlDownload\": \"https:\u002F\u002Fexample.bitrix24.com\u002Fbitrix\u002Fservices\u002Fmain\u002Fajax.php?action=disk.api.file.download&fileId=8851&fileName=presentation.mp4\",\n        \"viewerAttrs\": {\n          \"viewerType\": \"video\",\n          \"objectId\": \"8851\",\n          \"imChatId\": 1001,\n          \"title\": \"presentation.mp4\"\n        },\n        \"mediaUrl\": {\n          \"preview\": {\n            \"250\": \"https:\u002F\u002Fexample.bitrix24.com\u002Fbitrix\u002Fservices\u002Fmain\u002Fajax.php?action=disk.api.file.showPreview&fileId=8851&width=250&height=250&fileName=preview.jpg\"\n          }\n        },\n        \"isTranscribable\": false,\n        \"isVideoNote\": false,\n        \"isVoiceNote\": false,\n        \"duration\": null\n      }\n    ],\n    \"tariffRestrictions\": {\n      \"isHistoryLimitExceeded\": false\n    },\n    \"list\": [\n      {\n        \"id\": 111,\n        \"messageId\": 34213,\n        \"chatId\": 1001,\n        \"authorId\": 1,\n        \"dateCreate\": \"2026-03-03T11:44:09+00:00\",\n        \"fileId\": 8851,\n        \"subType\": \"other\",\n        \"group\": \"file\"\n      },\n      {\n        \"id\": 109,\n        \"messageId\": 34211,\n        \"chatId\": 1001,\n        \"authorId\": 1,\n        \"dateCreate\": \"2026-03-03T11:43:35+00:00\",\n        \"fileId\": 8851,\n        \"subType\": \"other\",\n        \"group\": \"file\"\n      }\n    ]\n  }\n}\n```\n\nWith `limit=500`, the response also carries `\"meta\": { \"requestedLimit\": 500, \"appliedLimit\": 200 }`.\n\n## Error response example\n\n400 — `group` not passed. Checked before the request reaches Bitrix24:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"INVALID_PARAMS\",\n    \"message\": \"`group` is required: one or more of MEDIA, FILE, AUDIO, separated by commas, each once.\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|---------|\n| 400 | `INVALID_CHAT_ID` | `chatId` is not a positive integer. Checked before the request reaches Bitrix24 |\n| 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 |\n| 422 | `BITRIX_ERROR` | `error.b24Code` is `ACCESS_ERROR` — the employee has no access to the chat, or the chat does not exist |\n| 422 | `BITRIX_ERROR` | `error.b24Code` is `FILE_CURSOR_INCOMPLETE` — with `order=date`, `lastId` was passed without `lastDate` |\n| 404 | `ENTITY_NOT_FOUND` | Bitrix24 returned a generic NOT_FOUND error; the Bitrix24 code is in `error.b24Code` |\n| 403 | `SCOPE_DENIED` | The key lacks the `im` scope |\n| 401 | `TOKEN_MISSING` | The key has no Bitrix24 tokens configured |\n| 401 | `MISSING_API_KEY` | `X-Api-Key` not passed |\n\nFull list of common API errors — [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n- **End of results.** A page with fewer `data.list` records than `limit` is the last one.\n- **Downloading from an application.** The `im` scope is not enough for [`GET \u002Fv1\u002Ffiles\u002F:fileId\u002Fdownload`](\u002Fdocs\u002Fentities\u002Ffiles\u002Fdownload) — `disk` or `crm` is required.\n\n## See also\n\n- [Chat files](\u002Fdocs\u002Fchats\u002Ffiles)\n- [Upload a file to a chat](\u002Fdocs\u002Fchats\u002Ffiles\u002Fupload)\n- [File metadata](\u002Fdocs\u002Fchats\u002Ffiles\u002Ffile-get)\n- [Save files to Drive](\u002Fdocs\u002Fchats\u002Ffiles\u002Fsave)\n","2026-11-12",{},1794739537290]