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

Метод возвращает URL для загрузки медиафайла и токен для передачи загруженного файла во вложении к сообщению в чате или канале. После загрузки файла токен передаётся в запросе [POST /messages](/docs-api/methods/POST/messages) или [PUT /messages](/docs-api/methods/PUT/messages) в параметре `attachments.payload.token` 

 Для изображений вместо токена и текущего метода вы также можете использовать внешний URL для загрузки по прямой ссылке — подробнее смотрите параметры объекта `attachments.payload.url` в [POST /messages](/docs-api/methods/POST/messages). Для отправки остальных медиафайлов, потребуется получить токен: загрузить их через `/uploads`

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

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

### Типы медиафайлов и ограничения
 Медиафайлы, которые можно загрузить через `POST /uploads`, должны быть одного из типов `type`:

• `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, WAV, M4A и другие 
 **Максимальный размер** одного аудио: до 256 МБ или длительностью не более 60 мин — должны выполняться оба критерия. Например, отправить аудио размером 250 МБ и длительностью 70 минут нельзя

• `file` — другие файлы 
 **Максимальный размер** одного файла: до 4 ГБ
 **Доступные форматы**: TXT, DOC, PDF и другие распространённые форматы 

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

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

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

В ответ на текущий запрос `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`, которое вернулось [в ответе](/docs-api/methods/POST/uploads#Результат) на запрос `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`, которое вернулось [в ответе](/docs-api/methods/POST/uploads#Результат) на запрос `POST /uploads`

### Особенности загрузки разных типов медиафайлов

**Видео и аудио:**

- Когда получаем ссылку на загрузку видео или аудио (`POST /uploads` с `type` = `video` или `type` = `audio`), вместе с `url` в ответе приходит `token`, который нужно использовать в сообщении (когда формируете `body` с `attachments`) в [`POST /messages`](/docs-api/methods/POST/messages) 

- После загрузки видео или аудио (по `url` из шага выше) сервер возвращает `retval`

- C этого момента можно использовать `token`, чтобы прикреплять вложение в сообщение бота

**Изображения и файлы:**

- Для`type` = `file`: `token` возвращается в ответе на загрузку файла

- Для`type` = `image`: 
    - `token` возвращается в ответе на загрузку файла 
    - `token` содержится в URL, возвращаемом в методе для загрузки файла  

## Прикрепление медиафайлов
Процесс прикрепления медиафайлов к сообщениям состоит из трёх шагов:

#### 1. Получение URL для загрузки медиафайлов

Отправьте запрос:

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

где `{type}` — тип загружаемого файла:

- `file` — произвольный файл

- `image` — изображение

- `video` — видео

- `audio` — аудио

Ответ:

{
    "url": "https:///upload.do?..."
}

 > Обратите внимание:  домен в `url` зависит от типа файла. Это ожидаемое поведение:
`file` → `https://fu.oneme.ru`
`image` → `https://iu.oneme.ru`
`video` → `https://omub.okcdn.ru` 
 `audio` → `https://omu.okcdn.ru`

#### 2. Загрузка медиафайла

Используйте полученный `url` без изменений:

curl -X POST \
  -H "Content-Type: multipart/form-data" \
  -F "data=@movie.mp4" \
  "{url}"

Ответ:

{
    "token": "_3Rarhcf1PtlMXy8jpgie8Ai_KARnVFYNQTtmIRWNh4"
}

#### 3. Создание вложения 
 
 После успешной загрузки получите JSON-объект в ответе. Используйте этот объект для создания вложения. Структура вложения:
- `type`: тип медиа, например `"video"`
- `payload`: JSON-объект, который вы получили.

Отправьте сообщение с вложением:

{
    "text": "Message with video",
    "attachments": [
        {
            "type": "video",
            "payload": {
                "token": "_3Rarhcf1PtlMXy8jpgie8Ai_KARnVFYNQTtmIRWNh4"
            }
        }
    ]
}

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

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

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

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

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

**Как избежать ошибки:**
- После загрузки файла сделайте паузу перед отправкой сообщения
- Если отправка не удалась, повторите попытку через некоторое время. Увеличивайте интервал с каждой попыткой
- Загружайте часто используемые файлы заранее и переиспользуйте токен

## Авторизация

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

Токен для вызова HTTP-запросов присваивается при создании бота — его можно найти на [платформе](https://business.max.ru/self) в разделе **Чат-боты**. Выберите необходимого бота и нажмите **⋮** → **Настройки** → значок копирования справа от поля с токеном

Если вы верифицировали профиль и создали бота в [мини-приложении «MAX для бизнеса»](https://max.ru/business_bot?startapp), получить токен можно там же или в [боте «MAX для бизнеса»](https://max.ru/business_bot) с помощью команды **Получить токен**

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

## Параметры

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

Тип загружаемого файла. Возможные значения: `"image"`, `"video"`, `"audio"`, `"file"`

## Результат

URL для загрузки медиафайла. Срок жизни ссылки не ограничен
Токен для отправки медиафайла во вложении к сообщению с помощью [POST /messages](/docs-api/methods/POST/messages) или [PUT /messages](/docs-api/methods/PUT/messages)

## Коды ответов

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