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

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

POST /v1/bots/:botId/files

Загружает файл в чат от имени бота. Содержимое передаётся в base64 внутри тела запроса, поэтому размер ограничивает тело: 40 МиБ, то есть чуть меньше 30 МиБ исходного файла. Битрикс24 на своей стороне может принимать больше — этот потолок наш.

Параметры

Параметр Тип Обяз. Описание
ПараметрbotId (path) Типnumber Обяз.да ОписаниеID бота. Список: GET /v1/bots

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

Поле Тип Обяз. Описание
ПолеdialogId Типstring Обяз.да ОписаниеID диалога. Для группового чата — chatXXX, приходит в поле data.chat.dialogId ответа POST /v1/bots/:botId/chats и в поле chat.dialogId событий бота. Число означает личный диалог с пользователем с таким ID
Полеfile.name Типstring Обяз.да ОписаниеИмя файла с расширением
Полеfile.content Типstring Обяз.да ОписаниеСодержимое файла в base64
Полеmessage Типstring Обяз.нет ОписаниеТекст сообщения, прикреплённый к файлу

Примеры

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

Terminal
curl -X POST https://vibecode.bitrix24.tech/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": "Вот запрошенный отчёт"
  }'

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

Terminal
curl -X POST https://vibecode.bitrix24.tech/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": "Вот запрошенный отчёт"
  }'

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

javascript
import { readFileSync } from 'fs'

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

const res = await fetch('https://vibecode.bitrix24.tech/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: 'Вот запрошенный отчёт',
  }),
})

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

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

javascript
import { readFileSync } from 'fs'

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

const res = await fetch('https://vibecode.bitrix24.tech/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: 'Вот запрошенный отчёт',
  }),
})

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

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean ОписаниеВсегда true при успехе
Полеdata Типobject ОписаниеРезультат загрузки
Полеdata.file Типobject ОписаниеДанные загруженного файла
Полеdata.file.id Типnumber ОписаниеID загруженного файла. Передайте его в GET /v1/bots/:botId/files/:fileId, чтобы скачать файл
Полеdata.file.chatId Типnumber ОписаниеЧисловой ID чата
Полеdata.file.name Типstring ОписаниеИмя файла
Полеdata.file.extension Типstring ОписаниеРасширение файла
Полеdata.file.size Типnumber ОписаниеРазмер файла в байтах
Полеdata.messageId Типnumber ОписаниеID созданного сообщения с файлом
Полеdata.chatId Типnumber ОписаниеЧисловой ID чата
Полеdata.dialogId Типstring ОписаниеID диалога

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

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

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

422 — ошибка Битрикс24:

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

Ошибки

HTTP Код Описание
HTTP400 КодINVALID_BOT_ID ОписаниеbotId не является числом
HTTP400 КодMISSING_PARAMS ОписаниеdialogId не передан или пустой
HTTP400 КодMISSING_PARAMS ОписаниеНе передано имя файла file.name или его содержимое file.content. В тексте ошибки названы недостающие поля и нераспознанные поля тела
HTTP413 КодPAYLOAD_TOO_LARGE ОписаниеТело запроса больше 40 МиБ
HTTP404 КодBOT_NOT_FOUND ОписаниеБот с таким ID не найден
HTTP403 КодBOT_ACCESS_DENIED ОписаниеБот принадлежит другому API-ключу
HTTP422 КодBITRIX_ERROR ОписаниеОшибка Битрикс24 при загрузке
HTTP403 КодSCOPE_DENIED ОписаниеAPI-ключ не имеет скоупа imbot
HTTP403 КодWRITE_BLOCKED_READONLY_KEY ОписаниеКлюч только для чтения — см. права доступа
HTTP410 КодBOT_DISABLED ОписаниеБот отключён и не обрабатывает вызовы API. Как вернуть бота — Бот отключён
HTTP401 КодTOKEN_MISSING ОписаниеAPI-ключ не имеет настроенных токенов

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

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