Для AI-агентов: markdown этой страницы — /docs-content/chats/files/upload.md индекс документации — /llms.txt

Загрузить файл в чат

POST /v1/chats/:chatId/files

Загружает файл в чат. Содержимое передаётся в base64 и публикуется в чате как сообщение.

Для скачивания содержимого в режиме v2 используйте авторизованный GET /v1/files/:fileId/download. Нужен disk или crm. Скоупа im одного недостаточно. Загрузка файла в чат требует im.

Параметры

Параметр Тип Обяз. Описание
chatId (path) number да ID чата. Получить: POST /v1/chats или поле chatId строки GET /v1/chats/recent
format (query) string нет v2 включает режим v2. Любое другое значение игнорируется, загрузка идёт прежним способом. Повтор format не отклоняется: из format=v1&format=v2 берётся последнее значение, то есть режим v2, а format=v2&format=v1 даёт прежнюю загрузку. Форма format[]=v2 включает режим v2, если все её значения — v2

Поля запроса (body)

Поле Тип Обяз. Описание
filename string да Имя файла с расширением
content string да Содержимое файла в кодировке base64
message string нет Текст сообщения, прикреплённый к файлу в том же сообщении

Режим v2. format=v2 загружает файл и публикует сообщение одним вызовом. Ответ — HTTP 200 с объектом v2: file — сущность файла чата, messageId, chatId, dialogId, ключи в camelCase. Режим принимает в теле только filename, content и message, а в строке запроса — только format. Другое поле или параметр отклоняется с 400 INVALID_PARAMS до обращения к Битрикс24. Ссылок с учётными данными портала в ответе режима v2 нет: ссылки file открываются только в сессии пользователя в Битрикс24, а содержимое файла отдаёт GET /v1/files/:fileId/download.

Примеры

curl — личный ключ

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/chats/1001/files \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "report.pdf",
    "content": "aGVsbG8=",
    "message": "Отчёт за период"
  }'

curl — OAuth-приложение

Terminal 
curl -X POST https://vibecode.bitrix24.tech/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": "Отчёт за период"
  }'

JavaScript — личный ключ

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/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: 'Отчёт за период',
  }),
})

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

JavaScript — OAuth-приложение

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/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: 'Отчёт за период',
  }),
})

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

curl — режим v2

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/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": "Отчёт за период"
  }'

Поля ответа

Обычный режим — без format=v2:

Поле Тип Описание
success boolean Всегда true при успехе
data.fileId number ID загруженного файла. Используйте для GET /v1/chats/files/:fileId
data.name string Имя файла
data.downloadUrl string Адрес скачивания через API Вайбкод в обычном режиме, GET /v1/files/:id/download. Переход по нему требует скоуп disk или crm
data.size string Размер файла в байтах

Режим v2 — format=v2:

Поле Тип Описание
success boolean Всегда true при успехе
data.file object|null Сущность файла чата. null, если Битрикс24 не вернул файл после публикации
data.file.id number ID файла. Нужен для сохранения на Диск, расшифровки и скачивания через GET /v1/files/:fileId/download
data.file.chatId number ID чата
data.file.name string Имя файла
data.file.extension string Расширение в нижнем регистре
data.file.size number Размер в байтах
data.file.type string Тип файла: file, image, audio, video и другие
data.file.date string Дата загрузки (ISO 8601)
data.file.authorId number ID автора
data.file.urlDownload string Ссылка на файл в Битрикс24. Открывается только в сессии пользователя в Битрикс24
data.file.urlShow string Ссылка на просмотр в Битрикс24, в той же сессии
data.file.urlPreview string Ссылка на превью. Пустая строка, если превью нет
data.file.isTranscribable boolean Файл можно расшифровать
data.messageId number ID опубликованного сообщения
data.chatId number ID чата
data.dialogId string ID диалога — chatN

Кроме перечисленных, сущность файла несёт поля Битрикс24 для отображения — image, status, progress, authorName, viewerAttrs, mediaUrl, isVideoNote, isVoiceNote, duration.

Пример ответа

Обычный режим, HTTP 201:

JSON 
{
  "success": true,
  "data": {
    "fileId": 9265,
    "name": "report.pdf",
    "size": "24576"
  }
}

Пример ответа — режим v2

JSON 
{
  "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": "Иван Петров",
      "urlPreview": "",
      "urlShow": "https://YOUR_PORTAL.bitrix24.tech/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.tech/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"
  }
}

Пример ответа при ошибке

400 — не переданы обязательные поля:

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

Ошибки

HTTP Код Описание
400 INVALID_CHAT_ID chatId не является положительным целым числом — проверяется до обращения в Битрикс24
400 MISSING_PARAMS Не переданы обязательные поля filename или content
400 INVALID_PARAMS Режим v2: поле тела вне filename, content, message, параметр строки запроса вне format, filename или content отсутствует или не непустая строка, message не строка. Проверяется до обращения к Битрикс24
404 FOLDER_NOT_FOUND Папка чата на Диске не найдена
500 UPLOAD_FAILED Загрузка файла не выполнена
422 BITRIX_ERROR Ошибка Битрикс24 при загрузке. В режиме v2 код портала приходит в error.b24Code — например, FILE_INVALID_CONTENT, если content не base64
413 PAYLOAD_TOO_LARGE Тело запроса больше 40 МиБ
429 LARGE_BODY_BACKEND_BUSY Сейчас принимается слишком много больших тел — повторите через error.retryAfter секунд
403 SCOPE_DENIED Ключу не хватает скоупа im
403 WRITE_BLOCKED_READONLY_KEY Ключ только для чтения — загрузка изменяет чат
401 TOKEN_MISSING Ключ не имеет настроенных токенов Битрикс24

Полный список общих ошибок API — Ошибки.

Известные особенности

Три шага за один вызов. В обычном режиме загрузка выполняется в три шага: получение папки чата, загрузка файла на Диск, публикация в чате. При сбое на любом шаге возвращается соответствующая ошибка. Если Битрикс24 отвечает на шаге кодом HTTP 503 или отказом по лимиту частоты запросов, шаг повторяется автоматически. Если шаг загрузки или публикации завершился ошибкой, в том числе по таймауту, файл может остаться в папке чата на Диске: ответ об ошибке не содержит его fileId, а повторный вызов загрузит ещё одну копию. HTTP 201 не подтверждает, что сообщение с файлом появилось в чате: ответ шага публикации не проверяется. Перед повтором проверьте историю чата и папку чата на Диске.

Режим v2 — один вызов. С format=v2 файл загружается и публикуется одним вызовом Битрикс24, отдельных шагов и промежуточных ошибок нет. Если чат разрешает автовступление — например, чат комментариев или коллаб, — вызов делает текущего пользователя участником.

Base64 и размер тела. Кодировка base64 увеличивает размер тела запроса примерно на 33% по сравнению с исходным файлом. Тело этого метода ограничено 40 МиБ, то есть исходный файл — чуть меньше 30 МиБ.

Смотрите также