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

Upload a file to a chat

POST /v1/chats/:chatId/files

Uploads a file to a chat. The content is passed in base64 and published in the chat as a message.

To download the file content in the v2 mode, use the authenticated GET /v1/files/:fileId/download. Requires disk or crm. The im scope alone is not enough. Uploading a file to a chat requires im.

Parameters

Request fields (body)

The v2 mode. format=v2 uploads the file and publishes the message in one call. The response is HTTP 200 with the v2 object: file — the chat file entity, messageId, chatId, dialogId; keys are in camelCase. The mode accepts only filename, content and message in the body and only format in the query string. Any other field or parameter is rejected with 400 INVALID_PARAMS before any call to Bitrix24. The v2 response carries no links that embed Bitrix24 account credentials: the links in file open only in the user's own Bitrix24 session, and the file content comes from GET /v1/files/:fileId/download.

The message text is limited to 20000 Unicode code points. The complete outgoing string is counted, including markup, URLs and mentions, without truncation or trimming. For example, 😀 is one code point, while a compound emoji may consist of several code points. Requests over the limit are rejected before any call to Bitrix24.

Without format=v2, matching text aliases message, MESSAGE, Message and fields.message are accepted, including other case variants. Their values must agree. A conflict returns 400 INVALID_PARAMS. An object is never converted to text. The v2 mode keeps its flat body whitelist: case variants and fields are not accepted.

Examples

curl — personal key

curl -X POST https://vibecode.bitrix24.com/v1/chats/1001/files \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "report.pdf",
    "content": "aGVsbG8=",
    "message": "Report for the period"
  }'

curl — OAuth application

curl -X POST https://vibecode.bitrix24.com/v1/chats/1001/files \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "report.pdf",
    "content": "aGVsbG8=",
    "message": "Report for the period"
  }'

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/chats/1001/files', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filename: 'report.pdf',
    content: 'aGVsbG8=',
    message: 'Report for the period',
  }),
})

const { success, data } = await res.json()
console.log('File ID:', data.fileId)

JavaScript — OAuth application

const res = await fetch('https://vibecode.bitrix24.com/v1/chats/1001/files', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filename: 'report.pdf',
    content: 'aGVsbG8=',
    message: 'Report for the period',
  }),
})

const { success, data } = await res.json()
console.log('File ID:', data.fileId)

curl — v2 mode

curl -X POST "https://vibecode.bitrix24.com/v1/chats/1001/files?format=v2" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "report.pdf",
    "content": "aGVsbG8=",
    "message": "Report for the period"
  }'

Response fields

The usual mode — without format=v2:

The v2 mode — format=v2:

Besides the fields above, the file entity carries Bitrix24 display fields — image, status, progress, authorName, viewerAttrs, mediaUrl, isVideoNote, isVoiceNote, duration.

Response example

The usual mode, HTTP 201:

{
  "success": true,
  "data": {
    "fileId": 9265,
    "name": "report.pdf",
    "size": "24576"
  }
}

Response example — v2 mode

{
  "success": true,
  "data": {
    "file": {
      "id": 7701,
      "chatId": 1001,
      "date": "2026-09-25T10:00:00+00:00",
      "type": "file",
      "name": "report.pdf",
      "extension": "pdf",
      "size": 24576,
      "image": false,
      "status": "done",
      "progress": 100,
      "authorId": 5,
      "authorName": "John Smith",
      "urlPreview": "",
      "urlShow": "https://YOUR_PORTAL.bitrix24.com/bitrix/services/main/ajax.php?action=disk.api.file.download&SITE_ID=s1&humanRE=1&fileId=7701&exact=N&fileName=report.pdf",
      "urlDownload": "https://YOUR_PORTAL.bitrix24.com/bitrix/services/main/ajax.php?action=disk.api.file.download&SITE_ID=s1&humanRE=1&fileId=7701&exact=N&fileName=report.pdf",
      "isTranscribable": false,
      "isVideoNote": false,
      "isVoiceNote": false,
      "duration": null
    },
    "messageId": 36890,
    "chatId": 1001,
    "dialogId": "chat1001"
  }
}

Error response example

400 — required fields not provided:

{
  "success": false,
  "error": {
    "code": "MISSING_PARAMS",
    "message": "Required: filename (string) and content (base64-encoded file content)"
  }
}

Errors

Full list of common API errors — Errors.

Known specifics

Three steps in one call. In the usual mode the upload is performed in three steps: getting the chat folder, uploading the file to Drive, publishing in the chat. If any step fails, the corresponding error is returned. If Bitrix24 returns HTTP 503 or a rate-limit error for a step, the step is retried automatically. If the upload or publishing step fails or times out, the file may remain in the chat folder on Drive: the error response does not include its fileId, and calling again uploads another copy. HTTP 201 does not confirm that the message with the file appeared in the chat: the result of the publishing step is not checked. Before retrying, check the chat history and the chat folder on Drive.

The v2 mode — one call. With format=v2 the file is uploaded and published in one Bitrix24 call, with no separate steps and no intermediate errors. If the chat allows auto-join — for example, a comment chat or a collab — the call makes the current user a member.

Base64 and body size. Base64 encoding increases the request body size by about 33% compared to the original file. The body of this method is limited to 40 MiB, so the maximum original file size is just under 30 MiB.

See also

• Chat files
• File metadata
• Save files to Drive
• Chat folder on Drive
• Send a message