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

Upload a file to a chat folder

POST /v1/chats/:chatId/files/uploads

This method is rolling out in im 26.1500.0. It is not available on every Bitrix24 account yet. Until the method arrives, the API returns 422 METHOD_NOT_YET_AVAILABLE with error.release.

Uploads one file into the chat folder without posting a message. To publish it, call the publish route with data.file.id in uploadIds.

Parameters

Parameter Type Required Description
chatId (path) number yes Chat ID. Get it from: POST /v1/chats or the chatId field of a GET /v1/chats/recent row

Request fields (body)

Field Type Required Description
filename string yes File name with extension
content string yes Base64 content, up to 4 MiB after decoding

Other fields and query parameters are rejected with 400 INVALID_PARAMS.

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/chats/42/files/uploads \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename":"a.txt","content":"YWJj"}'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/chats/42/files/uploads \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"filename":"a.txt","content":"YWJj"}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/42/files/uploads', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"filename": "a.txt", "content": "YWJj"}),
})
const { success, data, error } = await res.json()
console.log(success ? data : error)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/42/files/uploads', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({"filename": "a.txt", "content": "YWJj"}),
})
const { success, data, error } = await res.json()
console.log(success ? data : error)

Response fields

Field Type Description
success boolean true on success
data.file object File in the chat folder. Token-bearing URLs are set to null
data.file.id number Uploaded file ID. Pass it in uploadIds when publishing
data.file.name string File name
data.file.size number File size in bytes
data.chatId number Chat ID
data.dialogId string Dialog ID. No messageId

Response example

JSON 
{
  "success": true,
  "data": {
    "file": {
      "id": 7701,
      "name": "a.txt",
      "size": 3
    },
    "chatId": 42,
    "dialogId": "chat42"
  }
}

Error response example

400 — the content exceeds 4 MiB:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "`content` exceeds the 4 MiB file limit."
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS Invalid body or unexpected parameters
400 INVALID_CHAT_ID chatId in the path is not a positive integer
401 TOKEN_MISSING No Bitrix24 access tokens
403 SCOPE_DENIED The API key does not have the im scope
403 WRITE_BLOCKED_READONLY_KEY The key is read-only
403 BITRIX_ACCESS_DENIED No access to the chat in Bitrix24
413 PAYLOAD_TOO_LARGE JSON body exceeds 40 MiB. Reduce the request
422 METHOD_NOT_YET_AVAILABLE The method is not available on the Bitrix24 account yet — see the notice at the top of the page
422 BITRIX_ERROR Bitrix24 refused the file
429 LARGE_BODY_BACKEND_BUSY Too many large bodies are being accepted right now. Retry according to Retry-After
429 QUEUE_TIMEOUT The Bitrix24 queue is overloaded. Retry according to Retry-After

For the generic 422 BITRIX_ERROR, the error.b24Code field is present only when the code is recognized. The platform does not retry an upload after an unknown outcome.

Full list of common API errors — Errors.

See also