For AI agents: markdown of this page — /docs-content-en/chats/files/upload.md documentation index — /llms.txt

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.

Parameters

Parameter Type Required Description
chatId (path) number yes Chat ID. Get it: POST /v1/chats or GET /v1/chats/recent

Request fields (body)

Field Type Required Description
filename string yes File name with extension
content string yes File content in base64 encoding
message string no Message text attached to the file in the same message

Examples

curl — personal key

Terminal 
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

Terminal 
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

javascript 
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

javascript 
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)

Response fields

Field Type Description
success boolean Always true on success
data.fileId number ID of the uploaded file. Use it for GET /v1/chats/files/:fileId
data.name string File name
data.size string File size in bytes
data.downloadUrl string File download link

Response example

JSON 
{
  "success": true,
  "data": {
    "fileId": 9265,
    "name": "report.pdf",
    "size": "24576",
    "downloadUrl": "https://YOUR_PORTAL.bitrix24.com/rest/download/?token=..."
  }
}

Error response example

400 — required fields not provided:

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

Errors

HTTP Code Description
400 MISSING_PARAMS The required filename or content fields were not provided
404 FOLDER_NOT_FOUND The chat folder on Drive was not found
500 UPLOAD_FAILED The file upload did not complete
422 BITRIX_ERROR Bitrix24 error during upload
403 SCOPE_DENIED The key lacks the im scope
401 TOKEN_MISSING The key has no configured Bitrix24 tokens

Full list of common API errors — Errors.

Known specifics

Three steps in one call. 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 message parameter. By passing message, you attach text to the same message as the file. A separate call to send the text is not needed.

Base64 and body size. Base64 encoding increases the request body size by about 33% compared to the original file.

See also