لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/bots/files.md فهرس التوثيق — /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 travels as base64 inside the request body, so the body is what limits the size: 40 MiB, i.e. just under 30 MiB of the original file. Bitrix24 itself may accept more — this ceiling is ours.

Parameters

Parameter Type Required Description
ParameterbotId (path) Typenumber Requiredyes DescriptionBot ID. List: GET /v1/bots

Request fields (body)

Field Type Required Description
FielddialogId Typestring Requiredyes DescriptionDialog ID. For a group chat, it is chatXXX and arrives in the data.chat.dialogId field of the POST /v1/bots/:botId/chats response and in the chat.dialogId field of bot events. A number means a direct dialog with the user who has that ID
Fieldfile.name Typestring Requiredyes DescriptionFile name with extension
Fieldfile.content Typestring Requiredyes DescriptionFile content in base64
Fieldmessage Typestring Requiredno DescriptionMessage 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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionUpload result
Fielddata.file Typeobject DescriptionUploaded file data
Fielddata.file.id Typenumber DescriptionUploaded file ID. Pass it to GET /v1/bots/:botId/files/:fileId to download the file
Fielddata.file.chatId Typenumber DescriptionNumeric chat ID
Fielddata.file.name Typestring DescriptionFile name
Fielddata.file.extension Typestring DescriptionFile extension
Fielddata.file.size Typenumber DescriptionFile size in bytes
Fielddata.messageId Typenumber DescriptionID of the created message with the file
Fielddata.chatId Typenumber DescriptionNumeric chat ID
Fielddata.dialogId Typestring DescriptionDialog 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

422 — Bitrix24 error:

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

Errors

HTTP Code Description
HTTP400 CodeINVALID_BOT_ID DescriptionbotId is not a number
HTTP400 CodeMISSING_PARAMS DescriptiondialogId is missing or empty
HTTP400 CodeMISSING_PARAMS DescriptionThe file name file.name or its content file.content is missing. The error message names the missing fields and any unrecognized body fields
HTTP413 CodePAYLOAD_TOO_LARGE DescriptionThe request body is larger than 40 MiB
HTTP404 CodeBOT_NOT_FOUND DescriptionNo bot found with this ID
HTTP403 CodeBOT_ACCESS_DENIED DescriptionThe bot belongs to a different API key
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 error during upload
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the imbot scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only — see access rights
HTTP410 CodeBOT_DISABLED DescriptionThe bot is disabled and does not process API calls. How to restore it — Bot disabled
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens

Full list of common API errors — Errors.

See also