Показать в MD-формате

Отправка сообщений

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

POST/messages

Отправляет сообщение в диалог, групповой чат или канал

Кроме текста сообщения или посты могут содержать следующие типы вложений:

Ограничения

Можно отправлять не более двух сообщений в секунду в один диалог, групповой чат или канал. При превышении этого лимита сообщения следует ставить в очередь или делать задержку перед отправкой

Пример запроса с одной кнопкой-ссылкой

Больше примеров запросов с кнопками — в разделе «Клавиатура»

BASH
curl -X POST "https://platform-api2.max.ru/messages?user_id={user_id}" \
  -H "Authorization: {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "Это сообщение с кнопкой-ссылкой",
  "attachments": [
    {
      "type": "inline_keyboard",
      "payload": {
        "buttons": [
          [
            {
              "type": "link",
              "text": "Откройте сайт",
              "url": "https://example.com"
            }
          ]
        ]
      }
    }
  ]
 }'

Авторизация

access_token
apiKey

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

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

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

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

Параметры

user_id
integer <int64>optional
Если вы хотите отправить сообщение пользователю, укажите ID этого пользователя

chat_id
integer <int64>optional
Если сообщение отправляется в чат или канал, укажите ID этого чата или канала. Как получить ID — на странице «Получение ID чата или канала»

disable_link_preview
booleanoptional
Если true, сервер не будет генерировать превью для ссылок в тексте сообщения или поста

Тело запроса

text
string Nullable
до 4000 символов

attachments
AttachmentRequest[] Nullable
Вложения сообщения. Если поле пустое или равно null, изменений не произойдет. Если массив пуст, все вложения будут удалены

type
string

payload
object PhotoAttachmentRequestPayload
Данные для прикрепления изображения (все поля являются взаимоисключающими). Вместе с изображениями можно прикрепить видеофайлы (type: video) и одно вложение с кнопками (type: inline_keyboard). Общее количество вложений не должно превышать общее ограничение — 12. Подробнее — в примерах

url
string Nullableoptional

от 1 символа

Любой внешний URL изображения, которое вы хотите прикрепить

token
string Nullableoptional
Токен существующего вложения

photos
object Nullableoptional
Токены, полученные после загрузки изображений

link
object NewMessageLink Nullable
Ссылка на сообщение в чате или пост в канале. Ссылки на комментарии к постам в каналах не поддержаны

type
enum MessageLinkType

Возможные значения в enum: "forward" "reply"

Тип связанного сообщения:

  • "reply" — ответ на сообщение или комментарий в чате или канале
  • "forward" — пересланное сообщение в чате или канале

Для комментариев поддерживается только тип reply

mid
string
ID исходного сообщения

notify
booleanoptional

По умолчанию: true

Для каналов всегда отправляйте запрос с notify = true или без этого поля. Отключить push-уведомления в каналах нельзя

В групповых чатах и диалогах, если notify = true или поле отсутствует, уведомление отобразится пользователю

При notify = false отображение push-уведомлений зависит от платформы:

  • Десктоп-клиент и веб-приложение на iOS. В диалогах и групповых чатах при notify = false уведомления не отображаются
  • Приложение на Android. В диалогах при notify = false уведомления не отображаются. В групповых чатах при notify = false уведомление не отображаются, только если приложение МАХ свёрнуто или закрыто. Если приложение открыто, пользователь увидит уведомление
  • Веб-приложение. Управление отображением уведомлений с помощью параметра notify не поддержано

format
enum TextFormat Nullableoptional

Возможные значения в enum: "markdown" "html"

Разметка текста сообщения. Подробнее — в разделе Форматирование

Результат

message
object Message

Содержит общую информацию о сообщении в чате или посте в канале: данные об отправителе и получателе, время создания сообщения, содержимое (текст и вложения), контекст связи с другими сообщениями (ответ или пересылка), а также публичную ссылку и статистику для постов в каналах

Возвращается в ответ на вызовы методов группы /messages и /chats/{chatId}/pin

sender
object Useroptional

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

Обратите внимание:

  • Все параметры в объекте относятся к отправителю сообщения
  • Объект отсутствует, если сообщение отправлено в канал

user_id
integer <int64>
Идентификатор пользователя или бота

first_name
string
Отображаемое имя пользователя или бота

last_name
string Nullableoptional
Отображаемая фамилия пользователя. Для ботов это поле не возвращается

username
string Nullable
Никнейм бота или уникальное публичное имя пользователя. В случае с пользователем может быть null, если тот недоступен или имя не задано

is_bot
boolean
true, если это бот

last_activity_time
integer <int64>
Время последней активности пользователя или бота в MAX (Unix timestamp в миллисекундах). Если пользователь отключил в настройках профиля мессенджера MAX возможность видеть, что он в сети онлайн, поле может не возвращаться

name
string Nullable
Устаревшее поле, скоро будет удалено

recipient
object Recipient

Получатель сообщения: пользователь или бот (для диалога), канал или чат

Обратите внимание: все параметры в объекте относятся к получателю сообщения

chat_id
integer <int64> Nullable
ID чата или канала — в зависимости от ограничений метода и от того, с чем вы работаете. Как получить ID — на странице «Получение ID чата или канала»

chat_type
enum ChatType

Возможные значения в enum: "chat" "channel" "dialog"

Тип чата:

  • chat — групповой чат
  • channel — канал или комментарий к посту (для вызовов методов группы /comments)
  • dialog — диалог

user_id
integer <int64> Nullable
ID получателя сообщения в диалоге (пользователя или бота). Если сообщение отправлено в групповой чат или канал, то параметр отсутствует

post_id
string Nullable
Идентификатор поста в канале, к которому оставлен комментарий

timestamp
integer <int64>
Время создания сообщения в формате Unix timestamp в миллисекундах

link
object LinkedMessage Nullableoptional
Пересланное или ответное сообщение

type
enum MessageLinkType

Возможные значения в enum: "forward" "reply"

Тип связанного сообщения:

  • "reply" — ответ на сообщение в чате
  • "forward" — пересланное сообщение в чате

sender
object Useroptional
Пользователь или бот, отправивший сообщение

user_id
integer <int64>
Идентификатор пользователя или бота

first_name
string
Отображаемое имя пользователя или бота

last_name
string Nullableoptional
Отображаемая фамилия пользователя. Для ботов это поле не возвращается

username
string Nullable
Никнейм бота или уникальное публичное имя пользователя. В случае с пользователем может быть null, если тот недоступен или имя не задано

is_bot
boolean
true, если это бот

last_activity_time
integer <int64>
Время последней активности пользователя или бота в MAX (Unix timestamp в миллисекундах). Если пользователь отключил в настройках профиля мессенджера MAX возможность видеть, что он в сети онлайн, поле может не возвращаться

name
string Nullable
Устаревшее поле, скоро будет удалено

chat_id
integer <int64>optional
Чат или канал, в котором сообщение было изначально опубликовано. Только для пересланных сообщений с type = forward. Как получить ID — на странице «Получение ID чата или канала»

message
object MessageBody
Информация о сообщении

mid
string
Уникальный ID сообщения

seq
integer <int64>
ID расположения сообщения в чате по порядку

text
string Nullable
Текст сообщения

attachments
Attachment[] Nullable
Вложения сообщения. Могут быть одним из типов attachment, описанных в схеме ниже Если поле пустое или равно null, изменений не произойдет. Если массив пуст, все вложения будут удалены

type
string

payload
object PhotoAttachmentPayload
Данные, использованные для отправки изображения

photo_id
integer <int64>
Уникальный ID этого изображения

token
string
Токен вложения — уникальный ID загруженного медиа: изображения, аудио, видео или файла. Возвращается в ответ на вызов POST /uploads

url
string
URL изображения. Время жизни ссылки ограниченно. Срок истечения указан в параметре expires — если он истёк, ссылку необходимо запросить повторно. Доступно в веб-клиентe и на Android

markup
MarkupElement[] Nullableoptional
Разметка текста сообщения. Подробнее — в разделе Форматирование

type
string

Тип элемента разметки. Может быть жирный, курсив, ~зачеркнутый~, подчеркнутый, моноширинный, выделенный, цитата, заголовок, ссылка или упоминание пользователя

Обратите внимание: в тексте комментариев не поддерживаются гиперссылки и упоминание пользователей

from
integer <int32>
Индекс начала элемента разметки в тексте. Нумерация с нуля

length
integer <int32>
Длина элемента разметки в символах

body
object MessageBody
Содержимое сообщения. Текст + вложения. Может быть null, если сообщение содержит только пересланное сообщение

mid
string
Уникальный ID сообщения

seq
integer <int64>
ID расположения сообщения в чате по порядку

text
string Nullable
Текст сообщения

attachments
Attachment[] Nullable
Вложения сообщения. Могут быть одним из типов attachment, описанных в схеме ниже Если поле пустое или равно null, изменений не произойдет. Если массив пуст, все вложения будут удалены

type
string

payload
object PhotoAttachmentPayload
Данные, использованные для отправки изображения

photo_id
integer <int64>
Уникальный ID этого изображения

token
string
Токен вложения — уникальный ID загруженного медиа: изображения, аудио, видео или файла. Возвращается в ответ на вызов POST /uploads

url
string
URL изображения. Время жизни ссылки ограниченно. Срок истечения указан в параметре expires — если он истёк, ссылку необходимо запросить повторно. Доступно в веб-клиентe и на Android

markup
MarkupElement[] Nullableoptional
Разметка текста сообщения. Подробнее — в разделе Форматирование

type
string

Тип элемента разметки. Может быть жирный, курсив, ~зачеркнутый~, подчеркнутый, моноширинный, выделенный, цитата, заголовок, ссылка или упоминание пользователя

Обратите внимание: в тексте комментариев не поддерживаются гиперссылки и упоминание пользователей

from
integer <int32>
Индекс начала элемента разметки в тексте. Нумерация с нуля

length
integer <int32>
Длина элемента разметки в символах

stat
object MessageStat Nullableoptional
Статистика просмотров постов и репостов — возвращается только для каналов

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

url
string Nullableoptional
Публичная ссылка на пост в канале. Отсутствует для диалогов и групповых чатов

Коды ответов

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