Файлы

Загружайте файлы в чат, сохраняйте их на свой Диск, расшифровывайте аудио, получайте метаданные файла и папку чата на Диске.

Скоуп: im | Базовый URL: https://vibecode.bitrix24.tech/v1 | Авторизация: X-Api-Key

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

POST /v1/chats/:chatId/files

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

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

Параметры

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

Режим 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.

Текст message ограничен 20 000 кодовых точек Unicode. Считается готовая строка вместе с разметкой, URL и упоминаниями, без обрезки и удаления пробелов. Например, 😀 — одна кодовая точка, а составной эмодзи может занимать несколько. Отказ приходит до любого обращения к Битрикс24.

Без format=v2 принимаются совпадающие текстовые варианты message, MESSAGE, Message и fields.message, включая другие варианты регистра. Их значения должны совпадать. Конфликт даёт 400 INVALID_PARAMS. Объект не преобразуется в текст. В режиме v2 остаётся плоское тело из разрешённых полей: варианты регистра и fields не принимаются.

Примеры

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

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-приложение

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 — личный ключ

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-приложение

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

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:

Режим v2 — format=v2:

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

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

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

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

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

{
  "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 — не переданы обязательные поля:

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

Ошибки

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

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

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

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

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

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

• Файлы чатов
• Метаданные файла
• Сохранить файлы на Диск
• Папка чата на Диске
• Отправить сообщение