Загрузка медиафайлов

Для корректной работы ваших чат-ботов и мини-приложений направляйте запросы на домен platform-api2.max.ru вместо platform-api.max.ru. Также убедитесь, что добавили сертификат Минцифры в список доверенных

POST/uploads

Метод возвращает URL для загрузки медиафайла и последующей отправки его во вложении к сообщению в чате или канале. После загрузки файлу присваивается токен, который нужно передать в запросе POST /messages или PUT /messages в параметре attachments.payload.token

По URL-ссылке, которая вернётся в ответ на запрос, можно загрузить только один файл. Если вы хотите загрузить ещё, отправьте повторно запрос POST /uploads и используйте новую URL-ссылку

После загрузки файлы хранятся до тех пор, пока не будут удалены из чата или канала, в который были отправлены

Подробные сценарии и примеры загрузки разных типов медиа смотрите в разделе «Отправка сообщений с медиафайлами»

Пример запроса для загрузки медиафайла

BASH
curl -X POST "https://platform-api2.max.ru/uploads?type={type}" \
  -H "Authorization: {access_token}"

Способы загрузки медиафайлов

В ответ на текущий запрос POST /uploads в поле url вернётся URL для загрузки медиафайла — загрузить можно одним из двух способов:

Пример загрузки файла по URL:

BASH
curl -X POST "%UPLOAD_URL%" \
  -H "Authorization: {access_token}" \
  -F "data=@example.mp4"

где %UPLOAD_URL% — это значение поля url, которое вернулось в ответе на запрос POST /uploads

Пример использования cURL для загрузки файла:

SHELL
curl -i -X POST \
  -H "Content-Type: multipart/form-data" \
  -F "data=@movie.pdf" "%UPLOAD_URL%"

где %UPLOAD_URL% — это значение поля url, которое вернулось в ответе на запрос POST /uploads

Обработка медиафайлов

После успешной загрузки сервер обрабатывает файл. Файлы от нескольких мегабайт обрабатываются дольше

Для стабильной работы сервисов MAX убедитесь, что максимальное количество запросов в секунду на platform-api2.max.ru — 30 rps

Если отправить сообщение с вложением сразу после загрузки, может возникнуть ошибка:

JSON
{
  "code": "attachment.not.ready",
  "message": "Key: errors.process.attachment.file.not.processed"
}

Как избежать ошибки:

Авторизация

access_token
apiKey

Передача токена через query-параметры больше не поддерживается — используйте заголовок Authorization: <token>

Токен для вызова HTTP-запросов присваивается при создании бота — его можно найти на платформе в разделе Чат-боты. Выберите необходимого бота и нажмите ⋮ → Настройки → значок копирования справа от поля с токеном

Если вы верифицировали профиль и создали бота в мини-приложении «MAX для бизнеса», получить токен можно там же или в боте «MAX для бизнеса» с помощью команды Получить токен

Рекомендуем не разглашать токен посторонним, чтобы они не получили доступ к управлению ботом. Токен может быть отозван за нарушение Правил платформы

Параметры

type
enum UploadType

Возможные значения в enum: "image" "video" "audio" "file"

Тип загружаемого медиафайла. Возможные значения и поддерживаемые форматы:

  • image — изображение (JPG, JPEG, PNG, GIF, TIFF, BMP, HEIC) Максимальный размер одного изображения: до 50 МБ или не более 7680x7680 — должны выполняться оба критерия. Например, отправить изображение 55 МБ и 7600x7600 нельзя
  • video — видеофайл (MP4, MOV, MKV, WEBM) Максимальный размер одного видео: до 250 МБ
  • audio — аудиофайл (MP3, M4A и другие) Максимальный размер одного аудио: до 256 МБ или длительностью не более 60 мин — должны выполняться оба критерия. Например, отправить аудио размером 250 МБ и длительностью 70 минут нельзя
  • file — файл, поддерживаются распространённые форматы (например, TXT, DOC и другие) Максимальный размер одного файла: до 4 ГБ

При передаче неподдерживаемого типа файла вернётся ошибка File extension is forbidden

Значение photo больше не поддерживается. Если вы использовали type=photo в ранее созданных интеграциях — замените его на type=image

HTTP-коды ответов

КодОписание
200Возвращает URL для загрузки вложения и токен для загрузки медиафайла
401Ошибка авторизации. Токен access_token указан некорректно или недействителен
500Внутренняя ошибка сервера

Подробнее о форматах ответа и кодах ошибок — на странице «Общее описание»

Результат

url
string
URL для загрузки медиафайла. Срок жизни ссылки не ограничен

token
stringoptional
Токен для отправки медиафайла во вложении к сообщению с помощью POST /messages или PUT /messages