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. Returns HTTP 201 with the identifier and metadata of the uploaded file. With format=v2 the upload goes through the v2 messenger method im.v2.File.upload and returns HTTP 200 with the v2 object — see "The v2 mode" below. The legacy mode returns downloadUrl, the Vibecode API download address, and retains retries as in main bd93898fc422; commit=false introduces no new 502 and no compensating deletion is made.

To download bytes in the v2 mode, use the authenticated GET /v1/files/:fileId/download. Requires disk or crm; im alone is insufficient. Chat upload still requires im.

Parameters

Request fields (body)

The v2 mode. format=v2 uploads the file and publishes the message in one im.v2.File.upload 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.

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

{
  "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.

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.

The message parameter. By passing message, you attach text to the same message as the file. No separate call is needed to send the text.

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. Requests over the limit are rejected with the PAYLOAD_TOO_LARGE code.

See also

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