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

Для отправки сообщений в чаты и каналы в 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

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

BASH

curl -i -X POST "%UPLOAD_URL%" \
          -H "Content-Type: multipart/form-data" \
          -F "data=@movie.mp4" 
//  `%UPLOAD_URL%` — это значение поля `url`, которое вернулось в ответе на запрос `POST /uploads`

BASH

 curl -X POST "%UPLOAD_URL%" \
          -H "Authorization: {access_token}" \
          -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, 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?..

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

URL в ответе могут отличаться по параметрам, используйте именно тот URL, который возвращает метод

JSON

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

JSON

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

Шаг 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:

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, 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:

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:

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:

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, а в чат или канал, который вы указали в запросе, придёт файл

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

Ошибка с кодом attachment.not.ready

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

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

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

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

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

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

Неподдерживаемый формат вложения

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

HTTP Status 415 – Unsupported Media Type

Чтобы избежать ошибки убедитесь, что формат соответствует требованиям к типам вложений

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

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

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

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

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

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

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

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

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

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 нажата"
              }
            ]
          ]
        }
      }
    }
  ]
 }

JSON

{
  "text": "Это сообщение с двумя изображениями, одно из которых передаётся с помощью token, полученного при загрузке через POST /uploads, а второе — с помощью прямой URL-ссылки",
  "attachments": [
  // одно изображение передаётся с помощью token, полученного при загрузке через POST /uploads
        {
      "type": "image",
      "payload": {
  //токен, который вернулся в при загрузке изображения 1 по ссылке, полученной через POST /uploads
         "token": "nJB5ncI22cjv91bDOH6vooWy3VWVhxyyD" 
      }
    },
  // второе изображение передаётся с помощью с помощью прямой URL-ссылки
        {
      "type": "image",
      "payload": {
  // ссылка на изображение в интернете
              "url": "https://domen.ru/example" 
      }
    } 
  ]
 }

JSON

{ 
  "text": "Это сообщение с двумя видео",
  "attachments": [
     {
            
      "type": "video",
      "payload": {
//токен, который вернулся в ответ на запрос POST /uploads
              "token": "nJB5ncI22cjv91bDOH6vooWy3VWVhxyyD" 
      }
    },
     {
            
      "type": "video",
      "payload": {
//токен, который вернулся в ответ на запрос POST /uploads
              "token": "pM5ctOE1bUNLCi4RnD-6cjsJdcxSQKnJ"
      }
    }
  ]
 }

JSON

{
  "text": "Это сообщение с файлом и кнопками",
  "attachments": [
     {
// к сообщению можно прикрепить только одно вложение с файлом типа `file`
            
      "type": "file",
      "payload": {
//токен, который вернулся в ответ на запрос POST /uploads
              "token": "B5ny3VWVcIv91bDy3VWVnJB5ncIOH"
      }
    },
// в сообщении с файлом можно передать только одно вложение с кнопками 
{
        "type": "inline_keyboard",
        "payload": {
          "buttons": [
            [
              {
                "type": "callback",
                "text": "Кнопка 1",
                "payload": "Кнопка 1 нажата"
              },
              {
                "type": "callback",
                "text": "Кнопка 2",
                "payload": "Кнопка 2 нажата"
              },
              {
                "type": "callback",
                "text": "Кнопка 3",
                "payload": "Кнопка 3 нажата"
              }
            ]
          ]
        }
      }
  ]
 }

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