Загрузка медиафайлов
Для корректной работы ваших чат-ботов и мини-приложений направляйте запросы на доменplatform-api2.max.ruвместоplatform-api.max.ru. Также убедитесь, что добавили сертификат Минцифры в список доверенных
POST/uploads
Метод возвращает URL для загрузки медиафайла и последующей отправки его во вложении к сообщению в чате или канале. После загрузки файлу присваивается токен, который нужно передать в запросе POST /messages или PUT /messages в параметре attachments.payload.token
По URL-ссылке, которая вернётся в ответ на запрос, можно загрузить только один файл. Если вы хотите загрузить ещё, отправьте повторно запрос POST /uploads и используйте новую URL-ссылку
После загрузки файлы хранятся до тех пор, пока не будут удалены из чата или канала, в который были отправлены
Подробные сценарии и примеры загрузки разных типов медиа смотрите в разделе «Отправка сообщений с медиафайлами»
Пример запроса для загрузки медиафайла
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:
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 для загрузки файла:
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
Если отправить сообщение с вложением сразу после загрузки, может возникнуть ошибка:
{
"code": "attachment.not.ready",
"message": "Key: errors.process.attachment.file.not.processed"
}Как избежать ошибки:
- После загрузки файла сделайте паузу перед отправкой сообщения
- Если отправка не удалась, повторите попытку через некоторое время. Увеличивайте интервал с каждой попыткой
- Загружайте часто используемые файлы заранее и переиспользуйте токен
Авторизация
Передача токена через query-параметры больше не поддерживается — используйте заголовок
Authorization: <token>
Токен для вызова HTTP-запросов присваивается при создании бота — его можно найти на платформе в разделе Чат-боты. Выберите необходимого бота и нажмите ⋮ → Настройки → значок копирования справа от поля с токеном
Если вы верифицировали профиль и создали бота в мини-приложении «MAX для бизнеса», получить токен можно там же или в боте «MAX для бизнеса» с помощью команды Получить токен
Рекомендуем не разглашать токен посторонним, чтобы они не получили доступ к управлению ботом. Токен может быть отозван за нарушение Правил платформы
Параметры
Возможные значения в 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 | Внутренняя ошибка сервера |
Подробнее о форматах ответа и кодах ошибок — на странице «Общее описание»
Результат