Para agentes de IA: markdown desta página — /docs-content-en/chats/files.md índice da documentação — /llms.txt

Os artigos da documentação estão disponíveis atualmente em inglês.

Files

List chat files, upload files to a chat, save them to your Drive, transcribe audio, get file metadata and the chat folder on Drive.

Scope: im | Base URL: https://vibecode.bitrix24.com/v1 | Authorization: X-Api-Key

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
ParameterchatId (path) Typenumber Requiredyes DescriptionChat ID. Get it: GET /v1/chats/recent
Parametergroup (query) Typestring Requiredyes DescriptionTabs 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
Parameterlimit (query) Typenumber Requiredno DescriptionHow 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
ParameterlastId (query) Typenumber Requiredno DescriptionNext-page cursor: the id of the last data.list record from the previous response
ParameterlastDate (query) Typestring Requiredno DescriptionCursor 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
Parameterorder (query) Typestring Requiredno DescriptionThe only value is date: sort by upload date, newest first. Accepted only with group=AUDIO. Without the parameter, records are ordered by descending id
Parametersearch (query) Typestring Requiredno DescriptionKeeps 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

Terminal 
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

Terminal 
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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.list Typearray DescriptionAttachment records, one per file sent in a message. One file sent twice produces two records
Fielddata.list[].id Typenumber DescriptionRecord ID. The value for lastId on the next page
Fielddata.list[].messageId Typenumber DescriptionID of the message with the attachment
Fielddata.list[].chatId Typenumber DescriptionChat ID
Fielddata.list[].authorId Typenumber DescriptionSender ID; the profile is in data.users
Fielddata.list[].dateCreate Typestring DescriptionSend date (ISO 8601). The value for lastDate on the next page
Fielddata.list[].fileId Typenumber DescriptionFile ID; the file card is in data.files
Fielddata.list[].subType Typestring DescriptionAttachment subtype, for example other
Fielddata.list[].group Typestring DescriptionLowercase category: media, file, audio
Fielddata.files Typearray DescriptionFiles referenced by data.list records, each once
Fielddata.files[].id Typenumber DescriptionFile ID. Needed to save to Drive, transcribe, and download via GET /v1/files/:fileId/download
Fielddata.files[].chatId Typenumber DescriptionChat ID
Fielddata.files[].date Typestring DescriptionFile upload date (ISO 8601)
Fielddata.files[].type Typestring DescriptionFile type: file, image, audio, video, and others
Fielddata.files[].name Typestring DescriptionFile name
Fielddata.files[].extension Typestring DescriptionLowercase extension
Fielddata.files[].size Typenumber DescriptionSize in bytes
Fielddata.files[].authorId Typenumber DescriptionFile author ID
Fielddata.files[].authorName Typestring DescriptionFile author name
Fielddata.files[].urlDownload Typestring DescriptionLink to the file in Bitrix24. Opens only within the user's Bitrix24 session
Fielddata.files[].urlShow Typestring DescriptionLink to the viewer in Bitrix24, within the same session
Fielddata.files[].urlPreview Typestring DescriptionLink to the preview. An empty string if there is no preview
Fielddata.files[].isTranscribable Typeboolean DescriptionThe file can be transcribed
Fielddata.files[].isVoiceNote Typeboolean DescriptionVoice message
Fielddata.files[].isVideoNote Typeboolean DescriptionVideo message
Fielddata.files[].duration Typenumber|null DescriptionRecording duration. May be null
Fielddata.users Typearray DescriptionSenders and file authors. Fields are the same as for a member in the chat member list: id, name, firstName, lastName, active, type, and others
Fielddata.tariffRestrictions.isHistoryLimitExceeded Typeboolean Descriptiontrue when the plan hides part of the chat's older history and its files are not included in the results
Fieldmeta.requestedLimit Typenumber DescriptionThe limit passed. Only when it is outside the 1–200 range
Fieldmeta.appliedLimit Typenumber DescriptionThe 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
HTTP400 CodeINVALID_CHAT_ID DescriptionchatId is not a positive integer. Checked before the request reaches Bitrix24
HTTP400 CodeINVALID_PARAMS Descriptiongroup 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
HTTP422 CodeBITRIX_ERROR Descriptionerror.b24Code is ACCESS_ERROR — the employee has no access to the chat, or the chat does not exist
HTTP422 CodeBITRIX_ERROR Descriptionerror.b24Code is FILE_CURSOR_INCOMPLETE — with order=date, lastId was passed without lastDate
HTTP404 CodeENTITY_NOT_FOUND DescriptionBitrix24 returned a generic NOT_FOUND error; the Bitrix24 code is in error.b24Code
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the im scope
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no Bitrix24 tokens configured
HTTP401 CodeMISSING_API_KEY DescriptionX-Api-Key not passed

Full list of common API errors — 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 — disk or crm is required.

See also