Для AI-агентов: markdown этой страницы — /docs-content/chats/files/list.md индекс документации — /llms.txt
Список файлов чата
GET /v1/chats/:chatId/files
Возвращает страницу файлов, отправленных в чат: те же вложения, что на вкладках «Медиа», «Файлы» и «Голосовые» правой панели чата. Обязательный параметр group задаёт, какие из этих вкладок попадут в выборку.
Параметры
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
ПараметрchatId (path) |
Типnumber | Обяз.да | ОписаниеID чата. Получить: GET /v1/chats/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 — личный ключ
curl "https://vibecode.bitrix24.tech/v1/chats/1001/files?group=MEDIA,FILE,AUDIO&limit=50" \
-H "X-Api-Key: YOUR_API_KEY"
curl — OAuth-приложение
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 — личный ключ
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-приложение
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 файла. Нужен для сохранения на Диск, расшифровки и скачивания через GET /v1/files/:fileId/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 | ОписаниеФайл можно расшифровать |
Полеdata.files[].isVoiceNote |
Типboolean | ОписаниеГолосовое сообщение |
Полеdata.files[].isVideoNote |
Типboolean | ОписаниеВидеосообщение |
Полеdata.files[].duration |
Типnumber|null | ОписаниеДлительность записи. Может быть null |
Полеdata.users |
Типarray | ОписаниеОтправители и авторы файлов. Поля — как у участника в списке участников чата: 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.
Пример ответа
Показаны две записи о двух отправках одного файла. Карточка сотрудника сокращена до основных полей:
{
"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:
{
"success": false,
"error": {
"code": "INVALID_PARAMS",
"message": "`group` is required: one or more of MEDIA, FILE, AUDIO, separated by commas, each once."
}
}
Ошибки
| HTTP | Код | Описание |
|---|---|---|
| HTTP400 | КодINVALID_CHAT_ID |
ОписаниеchatId не является положительным целым числом. Проверяется до обращения в Битрикс24 |
| HTTP400 | КодINVALID_PARAMS |
ОписаниеНе передан group, в нём значение не из MEDIA, FILE, AUDIO или повтор. limit не целое число, lastId не положительное целое, lastDate без lastId или не в формате RFC 3339. order не date или без group=AUDIO. Пустой search. Неизвестный параметр запроса — сообщение называет его и перечисляет допустимые |
| HTTP422 | КодBITRIX_ERROR |
Описаниеerror.b24Code равен ACCESS_ERROR — у сотрудника нет доступа к чату или чата нет |
| HTTP422 | КодBITRIX_ERROR |
Описаниеerror.b24Code равен FILE_CURSOR_INCOMPLETE — при order=date передан lastId без lastDate |
| HTTP404 | КодENTITY_NOT_FOUND |
ОписаниеБитрикс24 вернул общую ошибку NOT_FOUND, код портала — в error.b24Code |
| HTTP403 | КодSCOPE_DENIED |
ОписаниеКлючу не хватает скоупа im |
| HTTP401 | КодTOKEN_MISSING |
ОписаниеКлюч не имеет настроенных токенов Битрикс24 |
| HTTP401 | КодMISSING_API_KEY |
ОписаниеНе передан X-Api-Key |
Полный список общих ошибок API — Ошибки.
Известные особенности
- Конец выдачи. Страница, в которой записей
data.listменьшеlimit, — последняя. - Скачивание из приложения. Для
GET /v1/files/:fileId/downloadскоупаimнедостаточно — нуженdiskилиcrm.