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

Для корректной работы ваших чат-ботов и мини-приложений направляйте запросы на домен 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 для загрузки медиафайла — загрузить можно одним из двух способов:

Resumable upload — надёжный способ, если заголовок Content-Type не равен multipart/form-data. Этот способ позволяет загружать файл частями и возобновлять загрузку с последней успешно загруженной части в случае ошибок

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

BASH

Скопировать

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

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

Multipart upload — более простой, но менее надёжный способ. В этом случае используется заголовок Content-Type: multipart/form-data. Файл отправляется целиком одним запросом. Если загрузка прервётся, невозможно её возобновить — придётся начать заново

Пример использования 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: <access_token>

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

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

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

Параметры

type
enum UploadType

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

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

image — изображение (JPG, JPEG, PNG, GIF, TIFF, BMP, HEIC)
Максимальный размер одного изображения: до 50 МБ или не более 7680 x 7680 px — должны выполняться оба критерия. Например, отправить изображение 55 МБ и 7600 x 7600 px нельзя
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

Результат

url
string

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

token
string optional

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

Коды ответов

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