Отправка сообщений с медиафайлами

Для отправки сообщений в чаты и каналы в API используется метод POST /messages

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

Перед отправкой медиафайлов во вложении к сообщению — типы image, video, audio, file — предварительно их нужно загрузить с помощью метода POST /uploads. В результате загрузки вы получите token, который понадобится при отправке в сообщении через POST /messages. При этом одному токену должен соответствовать один медиафайл. Токен можно сохранить и переиспользовать в дальнейшем, когда понадобится отправить этот же медиафайл повторно

Для изображений в качестве альтернативы токену вы можете использовать url — прямую ссылку на изображение в интернете. Подробнее — в разделе «Как отправить изображение». Для аудио, видео и других файлов отправка по url недоступна

Если вам нужно отправить несколько медифайлов, для каждого нужно получить свой отдельный токен. Подробные примеры запросов смотрите в разделе «Как отправить несколько медиафайлов»

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

Вы можете выбрать способ загрузки медиафайла при вызове через POST /uploads:

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

Примеры загрузки файла разными методами:

Multipart upload

Resumable upload

Код

Скопировать

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

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

Типы медиавложений и требования к формату

При отправке вложения к сообщению нужно указать один из типов type:

Тип	Описание и ограничения
`image`	Изображения Доступные форматы: JPG, JPEG, PNG, GIF, TIFF, BMP, HEIC Максимальный размер одного изображения: до 50 МБ или не более 7680 × 7680 px — должны выполняться оба критерия. Например, отправить изображение 55 МБ и 7600 × 7600 px нельзя Обратите внимание, параметр `type=photo` больше не поддерживается. Если вы ранее использовали `type=photo` — замените его на `type=image`
`video`	Видеофайлы Доступные форматы: MP4, MOV, MKV, WEBM Максимальный размер одного видео: до 250 МБ
`audio`	Аудиофайлы Доступные форматы: MP3, WAV, M4A и другие Максимальный размер одного аудио: до 256 МБ или длительностью не более 60 мин — должны выполняться оба критерия. Например, отправить аудио размером 250 МБ и длительностью 70 минут нельзя
`file`	Другие медиафайлы Максимальный размер одного файла: до 4 ГБ Доступные форматы: TXT, DOC, PDF и другие распространённые форматы

Как отправить изображение

Вы можете отправить изображение одним из двух способов:

С помощью токена — надёжный способ. Подойдёт, если хотите периодически отправлять одно и то же изображение, а также быть уверенными в том, что отобразится у пользователя. Потребуется предваврительно загрузить изображение на сервер — после этого ему присваивается токен, с помощью которого вы можете отправлять изображение в сообщениях
По URL-ссылке — менее надёжный способ, т.к. вы указываете внешнюю ссылку на изображение. Если вы не контролируете этот источник, изображение может через какое-то время пропасть у пользователя или измениться, если URL больше не поддерживается или по нему разместили другой контент

В одном запросе можно отправить максимум 12 изображений. Можно отправить одним из двух способов — с помощью токена и по URL-ссылке — или используя оба в одном запросе. Например, одно изображение отправить с помощью токена, а второе — по URL-ссылке. Подробнее об отправке изображений в комбинации с другими типами вложений — в примерах

С помощью токена

Этап 1. Загрузите изображение на сервер

Шаг 1. Получите ссылку для загрузки изображения

Обратите внимание, параметр type=photo больше не поддерживается — используйте type=image

Формат запроса

Код

Скопировать

curl --location --request POST 'https://platform-api2.max.ru/uploads?type=image' \
  -H `Accept: application/json` \
  -H `Authorization: {access_token}`

В ответ вернётся URL-ссылка в формате https://iu.oneme.ru/uploadImage?.., которая содержит токен mediafile_token, необходимый для отправки изображения:

Формат ответа

Код

Скопировать

{
    "url": "https://iu.oneme.ru/uploadImage?apiToken={apiToken}photoIds={photoIds}",
 }

Шаг 2. Загрузите по полученной URL-ссылке изображение

Отправьте POST-запрос на URL, полученный на шаге 2, и укажите:

В data — путь к файлу в формате 'data=@"путь_к_файлу"
В Content-Type – способ загрузки, например Multipart upload. Подробнее — о способах загрузки

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

Обратите внимание на требования к изображениям:

Доступные форматы: JPG, JPEG, PNG, GIF, TIFF, BMP, HEIC
Максимальный размер одного изображения: до 50 МБ или не более 7680 × 7680 px — должны выполняться оба критерия. Например, отправить изображение 55 МБ и 7600 × 7600 px нельзя

Формат POST-запроса

Код

Скопировать

curl --location 'https://iu.oneme.ru/uploadImage?apiToken={apiToken}photoIds={photoIds}' \
    --header  `Authorization: {access_token}` \
    --header 'Content-Type: multipart/form-data' \
    --form 'data=@"путь_к_файлу"'

Дождитесь окончания загрузки. В случае успеха вам вернётся HTTP-код 200 с телом:

Код

Скопировать

{
    "photos": {
        "photoIds": {
            "token": "mediafile_token"
        }
    }
}

Готово! Запишите токен изображения, который получили в ответе в поле token, — он понадобится при отправке сообщения на этапе 2. Вы можете использовать токен несколько раз для повторной отправки изображения

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

Этап 2. Отправьте сообщение с изображением

Отправьте POST-запрос с токеном, полученным на шаге 2:

JSON

Скопировать

curl --location 'https://platform-api2.max.ru/messages?chat_id={chat_id}' \
--header 'Authorization: {access_token}' \
--data '{
    "attachments": [
        {   
            "text": "Изображение",
            "type": "image",
            "payload": {
                "token": "{mediafile_token}"
            }
        }
    ]
}'

Готово! В ответ вернётся объект Message, а в чат или канал, который вы указали в запросе, придёт изображение

По URL-ссылке

Отправьте запрос, в котором укажите ссылку на изображение:

Формат запроса

Код

Скопировать

curl --location 'https://platform-api2.max.ru/messages?chat_id={chat_id}' \
--header 'Authorization: {access_token}' \
--data '{
  "text": "Изображение, загруженное по URL-ссылке",
  "attachments": [
            {
      "type": "image",
      "payload": {
        // внешняя ссылка на изображение
              "url": "https://example.png" 
      }
    } 
  ]
 }'

Готово! В ответ вернётся объект Message, а в чат или канал, который вы указали в запросе, придёт изображение

Как отправить аудио

Этап 1. Загрузите аудио на сервер

Шаг 1. Получите ссылку для загрузки аудио

Формат запроса

Код

Скопировать

curl --location --request POST 'https://platform-api2.max.ru/uploads?type=audio' \
  -H `Accept: application/json` \
  -H `Authorization: {access_token}`

В ответ вернётся URL-ссылка в формате https://omu.okcdn.ru/upload.do?..:

Формат ответа

Код

Скопировать

{
    "url": "https://omu.okcdn.ru/upload.do?sig={sig}8&expires={expires}&clientType={clientType}&saveOriginal={saveOriginal}&appId=api&id={id}&userId={userId}&cid={cid}",
    "token": "{mediafile_token}"
 }

Запишите токен аудиофайла, который получили в ответе в поле token, — он понадобится при отправке сообщения на этапе 2. Вы можете использовать токен повторно для отправки аудио в нескольких сообщениях

Шаг 2. Загрузите по полученной URL-ссылке аудиофайл

Отправьте POST-запрос на URL, полученный на шаге 2, и укажите:

В data — путь к файлу в формате 'data=@"путь_к_файлу"
В Content-Type – способ загрузки, например Multipart upload. Подробнее — о способах загрузки

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

Обратите внимание на требования к аудио:

Доступные форматы: MP3, WAV, M4A и другие
Максимальный размер одного аудио: до 256 МБ или длительностью не более 60 мин — должны выполняться оба критерия. Например, отправить аудио размером 250 МБ и длительностью 70 минут нельзя

Формат POST-запроса

Код

Скопировать

curl --location 'https://omu.okcdn.ru/upload.do?sig={sig}8&expires={expires}&clientType={clientType}&saveOriginal={saveOriginal}&appId=api&id={id}&userId={userId}&cid={cid}' \
    --header 'Content-Type: multipart/form-data' \
    --form 'data=@"путь_к_файлу"'

Дождитесь окончания загрузки. В случае успеха вам вернётся HTTP-код 200 с телом:

Код

Скопировать

<retval>1</retval>

Готово! Теперь вы может отправить сообщение с аудиофайлом. После успешной загрузки сервер обрабатывает файл. Файлы от нескольких мегабайт обрабатываются дольше. Если отправить сообщение с вложением сразу после загрузки, может возникнуть ошибка. Подробнее — Возможные ошибки

Этап 2. Отправьте сообщение с аудиофайлом

Отправьте POST-запрос с токеном, полученным на шаге 1:

JSON

Скопировать

curl --location 'https://platform-api2.max.ru/messages?chat_id={chat_id}' \
--header 'Authorization: {access_token}' \
--data '{
    "attachments": [
        {   
            "text": "Аудиофайл",
            "type": "audio",
            "payload": {
                "token": "{mediafile_token}"
            }
        }
    ]
}'

Готово! В ответ вернётся объект Message, а в чат или канал, который вы указали в запросе, придёт аудиосообщение

Как отправить видео

В одном запросе можно отправить максимум 12 видеофайлов — для каждого нужно получить свой токен. Подробнее об отправке видео в комбинации с другими типами вложений — в примерах

Этап 1. Загрузите видео на сервер

Шаг 1. Получите ссылку для загрузки видео

Формат запроса

Код

Скопировать

curl --location --request POST 'https://platform-api2.max.ru/uploads?type=video' \
  -H `Accept: application/json` \
  -H `Authorization: {access_token}`

В ответ вернётся URL-ссылка в формате https://omub.okcdn.ru/upload.do?..:

Формат ответа

Код

Скопировать

{
    "url": "https://omub.okcdn.ru/upload.do?sig={sig}8&expires={expires}&clientType={clientType}&saveOriginal={saveOriginal}&appId=api&id={id}&userId={userId}&cid={cid}",
    "token": "{mediafile_token}"
 }

Запишите токен видеофайла, который получили в ответе в поле token, — он понадобится при отправке сообщения на этапе 2. Вы можете использовать токен повторно для отправки видео в нескольких сообщениях

Шаг 2. Загрузите по полученной URL-ссылке видеофайл

Отправьте POST-запрос на URL, полученный на шаге 2, и укажите:

В data — путь к файлу в формате 'data=@"путь_к_файлу"
В Content-Type – способ загрузки, например Multipart upload. Подробнее — о способах загрузки

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

Обратите внимание на требования к видео:

Доступные форматы: MP4, MOV, MKV, WEBM
Максимальный размер одного видео: до 250 МБ

Формат POST-запроса

Код

Скопировать

curl --location 'https://omub.okcdn.ru/upload.do?sig={sig}8&expires={expires}&clientType={clientType}&saveOriginal={saveOriginal}&appId=api&id={id}&userId={userId}&cid={cid}' \
    --header 'Content-Type: multipart/form-data' \
    --form 'data=@"путь_к_файлу"'

Дождитесь окончания загрузки. В случае успеха вам вернётся HTTP-код 200 с телом:

Код

Скопировать

<retval>1</retval>

Готово! Теперь вы можете отправить сообщение с видеофайлом. После успешной загрузки сервер обрабатывает файл. Файлы от нескольких мегабайт обрабатываются дольше. Если отправить сообщение с вложением сразу после загрузки, может возникнуть ошибка. Подробнее — Возможные ошибки

Этап 2. Отправьте сообщение с видеофайлом

Отправьте POST-запрос с токеном, полученным на шаге 1:

JSON

Скопировать

curl --location 'https://platform-api2.max.ru/messages?chat_id={chat_id}' \
--header 'Authorization: {access_token}' \
--data '{
    "attachments": [
        {   
            "text": "Видеофайл",
            "type": "video",
            "payload": {
                "token": "{mediafile_token}"
            }
        }
    ]
}'

Готово! В ответ вернётся объект Message, а в чат или канал, который вы указали в запросе, придёт видеосообщение

Как отправить файл

Подраздел содержит описание отправки файлов TXT, DOC, PDF и других распространённых форматов. В одном запросе можно отправить только один файл. Дополнительно к нему можно прикрепить одно вложение с кнопками — отправка совместно с изображением или видео не поддерживается. Подробнее об отправке файлов в комбинации с другими типами вложений — в примерах

Этап 1. Загрузите файл на сервер

Шаг 1. Получите ссылку для загрузки файла

Формат запроса

Код

Скопировать

curl --location --request POST 'https://platform-api2.max.ru/uploads?type=file' \
  -H `Accept: application/json` \
  -H `Authorization: {access_token}`

В ответ вернётся URL-ссылка в формате https://fu.oneme.ru/api/upload.do?..:

Формат ответа

Код

Скопировать

{
    "url": "https://fu.oneme.ru/api/upload.do?sig={sig}8&expires={expires}&clientType={clientType}&id={id}&userId={userId}",
 }

Шаг 2. Загрузите по полученной URL-ссылке файл

Отправьте POST-запрос на URL, полученный на шаге 2, и укажите:

В data — путь к файлу в формате 'data=@"путь_к_файлу"
В Content-Type – способ загрузки, например Multipart upload. Подробнее — о способах загрузки

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

Обратите внимание на требования к файлам:

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

Формат POST-запроса

Код

Скопировать

curl --location 'https://omu.okcdn.ru/upload.do?sig={sig}8&expires={expires}&clientType={clientType}&saveOriginal={saveOriginal}&appId=api&id={id}&userId={userId}&cid={cid}' \
    --header 'Content-Type: multipart/form-data' \
    --form 'data=@"путь_к_файлу"'

Дождитесь окончания загрузки. В случае успеха вам вернётся HTTP-код 200 с идентификатором файла и токеном для отправки в сообщении

Формат ответа

Код

Скопировать

{
    "fileId": {fileId},
    "token": "{mediafile_token}"
 }

Готово! Теперь вы можете отправить сообщение с файлом — используйте полученный токен. После успешной загрузки сервер обрабатывает файл. Файлы от нескольких мегабайт обрабатываются дольше. Если отправить сообщение с вложением сразу после загрузки, может возникнуть ошибка. Подробнее — Возможные ошибки

Этап 2. Отправьте сообщение с файлом

Отправьте POST-запрос с токеном, полученным на шаге 2:

JSON

Скопировать

curl --location 'https://platform-api2.max.ru/messages?chat_id={chat_id}' \
--header 'Authorization: {access_token}' \
--data '{
    "attachments": [
        {   
            "text": "Файл",
            "type": "file",
            "payload": {
                "token": "{mediafile_token}"
            }
        }
    ]
}'

Готово! В ответ вернётся объект Message, а в чат или канал, который вы указали в запросе, придёт файл

Возможные ошибки при отправке вложения в сообщении

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

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

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

Код

Скопировать

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

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

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

Как отправить несколько медиафайлов

Видео и изображения можно отправить в комбинации друг с другом и одной кнопкой. Общее количество вложений при этом должно быть не более 12

Вы можете отправить изображение одним из двух способов:

С помощью токена — надёжный способ. Подойдёт, если хотите периодически отправлять одно и то же изображение, а также быть уверенными в том, что отобразится у пользователя. Потребуется предваврительно загрузить изображение на сервер — после этого ему присваивается токен, с помощью которого вы можете отправлять изображение в сообщениях
По URL-ссылке — менее надёжный способ, т.к. вы указываете внешнюю ссылку на изображение. Если вы не контролируете этот источник, изображение может через какое-то время пропасть у пользователя или измениться, если URL больше не поддерживается или по нему разместили другой контент

Изображения можно отправить одним из двух способов — с помощью токена и по URL-ссылке - или используя оба в одном запросе. Например, 1 изображение отправить с помощью токена, а второе — по URL-ссылке

Файл можно отправить только в комбинации с вложением с кнопками — отправка совместно с изображением или видео не поддерживается. При этом к сообщению можно прикрепить только один файл и одно вложение с кнопками. Подробнее о клавиатуре и её кнопках — в разделе «Клавиатура для чат-бота»

Примеры комбинаций вложений с видео, изображением и кнопкой:

6 видео, 5 изображений, 1 вложение с кнопками
12 видео
12 изображений
11 видео, 1 вложение с кнопками
11 изображений, 1 вложение с кнопками
6 видео, 6 изображений
1 файл, 1 вложение с кнопками

Примеры запроса при отправке разных типов медиавложений и их комбинаций

Видео, изображение, кнопки

2 изображения разными способами

Два видео

Файл, кнопки

JSON

Скопировать

{
"text": "Это сообщение с видео, изображением и кнопками",
"attachments": [
  {
//вложение с видео
      {
    "type": "video",
    "payload": {
//токен, который вернулся в ответ на запрос POST /uploads
            "token": "nJB5ncI22cjv91bDOH6vooWy3VWVhxyyD" 
    }
//вложение с изображением
  },
      {
    "type": "image",
    "payload": {
      //токен, который вернулся в при загрузке изображения по ссылке, полученной через POST /uploads
            "token": "4mtwu/jlqwJwSz5uYMcpHMCcn/5fqR0="  
    }
  },
// в сообщении с видео или изображением можно передать только одно вложение с кнопками 
   {
      "type": "inline_keyboard",
      "payload": {
        "buttons": [
          [
            {
              "type": "callback",
              "text": "Кнопка 1",
              "payload": "Кнопка 1 нажата"
            },
            {
              "type": "callback",
              "text": "Кнопка 2",
              "payload": "Кнопка 2 нажата"
            },
            {
              "type": "callback",
              "text": "Кнопка 3",
              "payload": "Кнопка 3 нажата"
            }
          ]
        ]
      }
    }
  }
]
}

Если у вас возникли вопросы, посмотрите раздел с ответами