MAX Bot API API

Отрасль: Связь и уведомления. Актуально на 2026-10-24.

HTTP API для ботов мессенджера MAX: информация о боте, отправка, редактирование, удаление и получение сообщений, ответы на нажатия кнопок, загрузка файлов, управление чатами и участниками. Получать события можно через Webhook-подписку (рекомендуется для production) или long polling (GET /updates, для разработки и тестов). Ответы — JSON.

Сценарии

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

Уведомления из своего сервиса в мессенджер MAX: заказ оформлен, запись подтверждена, новая заявка.

Получи токен бота и передавай его в заголовке Authorization без префикса. Передача токена в параметре access_token больше не работает. Проверь токен: GET /me вернёт данные бота.
Отправь сообщение: POST /messages с user_id (личное сообщение) или chat_id (чат или канал) в строке запроса и text в теле — до 4000 символов. Для форматирования передай format = html или markdown.
В ответе — объект message с ID сообщения: сохрани его, если сообщение потом нужно будет изменить через PUT /messages или удалить через DELETE /messages.
Не отправляй больше 2 сообщений в секунду в один диалог или чат и больше 30 запросов в секунду всего — иначе придёт 429. Ответ 403 значит, что пользователь остановил бота.

curl -X POST "https://platform-api2.max.ru/messages?user_id=<user_id>" \
  -H "Authorization: $MAX_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"text": "<b>Заказ №1042 оформлен</b>\nСумма: 15 000 ₽", "format": "html"}'

Принимать сообщения через вебхук

Бот на сервере: MAX присылает каждое событие на твой адрес — рекомендуемый способ для боевого режима.

Подпишись: POST /subscriptions с url (только HTTPS на порту 443, порт в адресе не указывается), update_types (например, message_created и bot_started) и secret — строкой от 5 до 256 символов.
Сертификат сервера должен быть от доверенного центра или Минцифры, с полной цепочкой. Самоподписанные не принимаются.
В каждом запросе MAX передаёт заголовок X-Max-Bot-Api-Secret — сверяй его со своим secret и отбрасывай чужие запросы.
Отвечай пользователю отдельным вызовом POST /messages с chat_id или user_id из события.
Метод возвращает HTTP 200 и при неудаче — проверяй поле success в ответе.

curl -X POST https://platform-api2.max.ru/subscriptions \
  -H "Authorization: $MAX_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://example.ru/max/webhook", "update_types": ["message_created", "message_callback", "bot_started"], "secret": "s3cr3t_Random_42"}'

Бот без сервера: long polling для разработки

Получать события в цикле — удобно для отладки и ботов без публичного HTTPS-адреса.

В цикле вызывай GET /updates с timeout (до 90 секунд ожидания) и types — нужными типами событий.
В ответе updates и marker. В следующий запрос передай этот marker: всё до него считается прочитанным. Без marker вернётся только последнее обновление.
На каждое сообщение отвечай через POST /messages.
Для событий из групповых чатов и каналов бот должен быть администратором.

import requests

API = "https://platform-api2.max.ru"
H = {"Authorization": "<токен бота>"}
marker = None
while True:
    params = {"timeout": 30, "types": "message_created"}
    if marker:
        params["marker"] = marker
    r = requests.get(f"{API}/updates", headers=H, params=params, timeout=40).json()
    marker = r.get("marker", marker)
    for upd in r.get("updates", []):
        msg = upd.get("message", {})
        chat_id = msg.get("recipient", {}).get("chat_id")
        text = msg.get("body", {}).get("text")
        if chat_id and text:
            requests.post(f"{API}/messages", headers=H, params={"chat_id": chat_id}, json={"text": f"Вы написали: {text}"})

Кнопки под сообщением и ответ на нажатие

Подтвердить или отменить заказ одной кнопкой, без ввода текста.

Отправь сообщение с кнопками: POST /messages с attachments, где type = inline_keyboard и payload.buttons — строки кнопок. Кнопка type = callback несёт payload — по нему поймёшь, что нажали; кнопка type = link открывает ссылку.
Нажатие приходит событием message_callback (через вебхук или GET /updates) с callback_id и payload.
Ответь на нажатие: POST /answers с callback_id в строке запроса. В теле можно передать message — новое содержимое сообщения, например без кнопок и с итогом.
Сообщения с inline_keyboard можно редактировать без ограничения срока через PUT /messages с message_id.

curl -X POST "https://platform-api2.max.ru/messages?user_id=<user_id>" \
  -H "Authorization: $MAX_TOKEN" -H 'Content-Type: application/json' \
  -d '{
        "text": "Заказ №1042 на 15 000 ₽. Подтвердить?",
        "attachments": [{"type": "inline_keyboard", "payload": {"buttons": [[
          {"type": "callback", "text": "Подтвердить", "payload": "order:1042:ok"},
          {"type": "callback", "text": "Отменить", "payload": "order:1042:cancel"}
        ]]}}]
      }'

curl -X POST "https://platform-api2.max.ru/answers?callback_id=<callback_id>" \
  -H "Authorization: $MAX_TOKEN" -H 'Content-Type: application/json' \
  -d '{"message": {"text": "Заказ №1042 подтверждён"}}'

Отправить файл или картинку

Прислать счёт, договор или фото товара вложением.

Получи адрес загрузки: POST /uploads с type — image, video, audio или file (photo больше не поддерживается). На один url загружается один файл.
Загрузи файл на полученный url multipart-формой. Токен вложения приходит в ответе /uploads (для части типов) или в ответе на загрузку.
Отправь сообщение: POST /messages с attachments = [{type, payload: {token}}].
Сразу после загрузки файл может быть ещё не обработан — придёт ошибка attachment.not.ready. Повторяй отправку с растущим интервалом.
Ограничения: картинка — до 50 МБ, видео — до 250 МБ, файл — до 4 ГБ.

UPLOAD_URL=$(curl -s -X POST "https://platform-api2.max.ru/uploads?type=file" -H "Authorization: $MAX_TOKEN" | jq -r .url)
TOKEN=$(curl -s -F "data=@invoice-1042.pdf" "$UPLOAD_URL" | jq -r .token)

curl -X POST "https://platform-api2.max.ru/messages?user_id=<user_id>" \
  -H "Authorization: $MAX_TOKEN" -H 'Content-Type: application/json' \
  -d "{\"text\": \"Счёт по заказу №1042\", \"attachments\": [{\"type\": \"file\", \"payload\": {\"token\": \"$TOKEN\"}}]}"

Базовые URL

Боевой: https://platform-api2.max.ru
Документация просит отправлять запросы на вместо старого .: platform-api2.max.ru

Авторизация

Тип: API-ключ

Токен бота передаётся в заголовке Authorization: <access_token> (без префикса). Передача токена в query-параметре access_token больше не поддерживается.

curl -X GET "https://platform-api2.max.ru/me" \
  -H "Authorization: {access_token}"

Методы

GET /me — Информация о боте

Возвращает объект User (BotInfo): user_id, first_name, username, is_bot, last_activity_time, description, avatar_url, commands.

POST /messages — Отправка сообщения

Адресат задаётся user_id или chat_id. В ответе — объект message созданного сообщения или поста.

Параметр	Где	Тип	Обяз.	Описание
`user_id`	query	integer	нет	ID пользователя-получателя
`chat_id`	query	integer	нет	ID чата или канала
`disable_link_preview`	query	boolean	нет	Не генерировать превью ссылок
`text`	body	string	нет	Текст, до 4000 символов
`attachments`	body	array	нет	Вложения: файлы (payload.token из /uploads), inline_keyboard и др.
`link`	body	object	нет	Ссылка на сообщение в чате или пост в канале (ответ или пересылка)
`notify`	body	boolean	нет	Push-уведомления участникам, по умолчанию true
`format`	body	string	нет	Форматирование текста: markdown или html

Пример запроса:

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"
            }
          ]
        ]
      }
    }
  ]
}'

PUT /messages — Редактирование сообщения

Сообщения с inline_keyboard и любые сообщения в групповых чатах и каналах редактируются без ограничения срока; остальные сообщения в диалогах с ботом — если отправлены меньше 7 суток назад. Ответ: success, message.

Параметр	Где	Тип	Обяз.	Описание
`message_id`	query	string	да	ID редактируемого сообщения
`text`	body	string	нет	Новый текст, до 4000 символов
`attachments`	body	array	нет	null или отсутствие — без изменений; пустой массив удаляет все вложения
`link`	body	object	нет	Ссылка на сообщение или пост
`notify`	body	boolean	нет	Push-уведомления, по умолчанию true
`format`	body	string	нет	markdown или html

DELETE /messages — Удаление сообщения

Удаляет сообщение или пост.

GET /messages — Получение сообщений

Нужен chat_id или message_ids. Сообщения по chat_id возвращаются от новых к старым; бот должен быть администратором чата.

Параметр	Где	Тип	Обяз.	Описание
`chat_id`	query	integer	нет	ID чата или канала
`message_ids`	query	array	нет	ID сообщений через запятую
`from`	query	integer	нет	Граница времени, Unix-время в миллисекундах
`to`	query	integer	нет	Граница времени, Unix-время в миллисекундах
`count`	query	integer	нет	1–100, по умолчанию 50

POST /answers — Ответ на нажатие кнопки

Ответ: success, message.

Параметр	Где	Тип	Обяз.	Описание
`callback_id`	query	string	да	ID нажатой кнопки
`disable_link_preview`	query	boolean	нет	Не генерировать превью ссылок
`message`	body	object	нет	Новое содержимое текущего сообщения, если его нужно изменить

GET /updates — Получение событий (long polling)

Для событий из групповых чатов и каналов бот должен быть администратором.

В ответе: updates[] и marker — указатель на следующую страницу; всё до него считается прочитанным.

Параметр	Где	Тип	Обяз.	Описание
`limit`	query	integer	нет	1–1000, по умолчанию 100
`timeout`	query	integer	нет	Ожидание в секундах, 0–90, по умолчанию 30
`marker`	query	integer	нет	marker из предыдущего ответа; без него вернётся только последнее обновление
`types`	query	array	нет	Типы событий, например message_created,message_callback

POST /subscriptions — Подписка на Webhook

Ответ: success, message.

Также есть GET /subscriptions (список подписок) и DELETE /subscriptions (отписка).

Параметр	Где	Тип	Обяз.	Описание
`url`	body	string	да	HTTPS-адрес, только порт 443 (порт в URL не указывается)
`update_types`	body	array	нет	Типы событий, например ["message_created", "bot_started"]
`secret`	body	string	нет	5–256 символов; приходит в заголовке X-Max-Bot-Api-Secret каждого вебхука

POST /uploads — Получение URL для загрузки файла

Возвращает url для загрузки и (для части типов) token для вложения. По одному url загружается один файл.

Параметр	Где	Тип	Обяз.	Описание
`type`	query	string	да	image, video, audio или file (photo больше не поддерживается)

Нюансы

Загрузка файла: POST /uploads?type=... → загрузить файл на url (multipart целиком или resumable частями) → передать токен в attachments[].payload.token в POST /messages или PUT /messages.
Сразу после загрузки файл может быть не обработан — ошибка attachment.not.ready; повторяйте отправку с растущим интервалом.
Вебхук: только HTTPS на порту 443, сертификат доверенного центра или Минцифры, полная цепочка сертификатов; самоподписанные сертификаты не поддерживаются. Проверяйте заголовок X-Max-Bot-Api-Secret.
GET /chats не поддерживается с июня 2026; POST /chats/{chatId}/members удалён с 30 сентября 2026.
Методы PUT/POST /subscriptions/POST /answers возвращают HTTP 200 и при неуспехе — проверяйте поле success.

Ошибки

Код	Описание
`400`	Некорректный запрос
`401`	Ошибка авторизации: токен неверен или недействителен
`403`	Бот приостановлен пользователем или нет доступа к чату
`404`	Ресурс не найден
`405`	Метод не разрешён
`429`	Превышено количество запросов
`503`	Сервис недоступен

Ограничения

Не больше 30 запросов в секунду на platform-api2.max.ru.
Не больше 2 отправленных или отредактированных сообщений в секунду в один диалог, чат или канал.
Размер файлов: image — до 50 МБ и 7680×7680 px; video — до 250 МБ; audio — до 256 МБ и 60 минут; file — до 4 ГБ.

Источники

Если этого недостаточно — официальная документация: https://dev.max.ru/docs-api JSON: https://mcp-everything.ru/api/integrations/max-bot-api. MCP: https://mcp-everything.ru/mcp