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

Files

Upload files to a chat on behalf of the bot and download files that users send.

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

Upload file

POST /v1/bots/:botId/files

Uploads a file to a chat on behalf of the bot. The content is passed as base64. Maximum size: 100 MB.

Request fields (body)

Parameter Type Required Description
dialogId string yes Dialog ID: numeric user ID for direct chats, chatXXX for group chats
file.name string yes File name with extension
file.content string yes File content in base64
message string no Message text attached to the file

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/bots/42/files \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dialogId": "chat123",
    "file": {
      "name": "report.pdf",
      "content": "JVBERi0xLjQKJcOkw7zDtsOfCjEgMCBv..."
    },
    "message": "Here is the requested report"
  }'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/bots/42/files \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dialogId": "chat123",
    "file": {
      "name": "report.pdf",
      "content": "JVBERi0xLjQKJcOkw7zDtsOfCjEgMCBv..."
    },
    "message": "Here is the requested report"
  }'

JavaScript — personal key

javascript 
import { readFileSync } from 'fs'

const base64 = readFileSync('./report.pdf').toString('base64')

const res = await fetch('https://vibecode.bitrix24.com/v1/bots/42/files', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    dialogId: 'chat123',
    file: { name: 'report.pdf', content: base64 },
    message: 'Here is the requested report',
  }),
})

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

JavaScript — OAuth application

javascript 
import { readFileSync } from 'fs'

const base64 = readFileSync('./report.pdf').toString('base64')

const res = await fetch('https://vibecode.bitrix24.com/v1/bots/42/files', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    dialogId: 'chat123',
    file: { name: 'report.pdf', content: base64 },
    message: 'Here is the requested report',
  }),
})

const { success, data } = await res.json()

Response fields

Field Type Description
file object Uploaded file data
file.id number Uploaded file ID (use it for GET /v1/bots/:botId/files/:fileId)
file.chatId number Numeric chat ID
file.name string File name
file.extension string File extension
file.size number File size in bytes
messageId number ID of the created message with the file
chatId number Numeric chat ID
dialogId string Dialog ID

Response example

JSON 
{
  "success": true,
  "data": {
    "file": {
      "id": 789,
      "chatId": 5,
      "name": "report.pdf",
      "extension": "pdf",
      "size": 35341
    },
    "messageId": 1520,
    "chatId": 5,
    "dialogId": "chat123"
  }
}

Error response example

502 — Bitrix24 error:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "File size exceeds limit"
  }
}

Errors

HTTP Code Description
400 INVALID_BOT_ID botId is not a number
404 BOT_NOT_FOUND No bot with this ID found
403 BOT_ACCESS_DENIED Bot belongs to a different API key
502 BITRIX_ERROR Bitrix24 error during upload
403 SCOPE_DENIED API key does not have the imbot scope
401 TOKEN_MISSING API key has no configured tokens

Full list of common API errors — Errors.

Known specifics

Base64: the file content is passed in full as base64. For large files this increases the body size by ~33%.

Message with the file: the message parameter attaches text to the same message as the file — no separate call is needed to send the text.

See also