Для 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 — личный ключ

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

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

Terminal
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 файла. Нужен для сохранения на Диск, расшифровки и скачивания через 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.

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

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

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 Код Описание
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.

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