Файлы и медиа в MAX Bot API: как загружать и отправлять без путаницы

Как устроен upload-flow

В MAX Bot API файл не прикладывается к сообщению “одним магическим запросом”. Сначала вы вызываетеPOST /uploads, получаете URL для загрузки, загружаете файл, а уже потом используете результат загрузки в сообщении.

Документация MAX подтверждает две модели загрузки: простой multipart upload и resumable upload для более надёжной работы с большими файлами. Для большинства первых сценариев хватает multipart.

Если ваша команда интегрируется через Relaya API, всё равно полезно понимать этот поток: даже когда саму отправку вы делаете через SDK, ограничения и модель хранения файла определяются базовым каналом.

Типы файлов и нюансы

В документации для POST /uploads поддерживаются типы image, video,audio и file. Старый тип photo больше не поддерживается.

• Максимальный размер файла для multipart upload: до 4 ГБ.
• Для видео и аудио токен приходит уже на этапе получения upload URL.
• Для image и file итоговый payload вы получаете после самой загрузки.

Рабочий пример

const uploadMeta = await fetch("https://platform-api.max.ru/uploads?type=file", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_MAX_BOT_TOKEN",
  },
}).then((res) => res.json());

const formData = new FormData();
formData.append("data", fileInput.files[0]);

const uploaded = await fetch(uploadMeta.url, {
  method: "POST",
  body: formData,
}).then((res) => res.json());

await fetch("https://platform-api.max.ru/messages?chat_id=1234567890", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_MAX_BOT_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    text: "Отправляю файл",
    attachments: [
      {
        type: "file",
        payload: uploaded,
      },
    ],
  }),
});

Где чаще всего ошибаются

• Пытаются отправить файл сразу в POST /messages, минуя upload flow.
• Используют старый тип photo вместо image.
• Не переиспользуют токен или payload для часто отправляемых файлов.
• Не учитывают, что большие файлы лучше грузить resumable-способом.

Если вам пока нужен только текст и кнопки, не усложняйте старт. Сначала добейтесь стабильной отправки сообщений, а потом уже наращивайте медиа.

Для продуктового quickstart поверх профиля MAX пригодятся и готовые пакеты Relaya: Node.js SDK, Python SDK и PHP SDK.