API мессенджера MAX: документация и создание бота

API мессенджера MAX открывает разработчикам доступ к платформе: отправка сообщений, управление чатами, загрузка файлов и создание мини-приложений. Мессенджер MAX предоставляет REST API на домене platform-api.max.ru с лимитом 30 запросов в секунду.

С августа 2025 года публикация ботов доступна только верифицированным юрлицам РФ. API также используется для автоматического переноса каналов в MAX из Telegram. Ниже — полное руководство: от получения токена до прохождения модерации.

• Получите токен через @MasterBot в мессенджере
• Пройдите верификацию юрлица на dev.max.ru
• Подключите Webhook или Long Polling для получения обновлений
• Используйте SDK на Python, JavaScript или Go
• Отправьте бота на модерацию (до 48 часов)

Что такое API MAX и как он устроен

API MAX — это REST-интерфейс для программного взаимодействия с мессенджером. Разработан VK как часть платформы MAX. Все запросы отправляются по HTTPS на домен platform-api.max.ru и возвращают ответы в формате JSON.

Базовый домен и авторизация

Актуальный домен API — platform-api.max.ru. Ранее использовался botapi.max.ru, но он устарел. Авторизация выполняется через HTTP-заголовок:

Authorization: <ваш_токен>

Передача токена через query-параметры больше не поддерживается. Максимальная частота запросов — 30 в секунду.

HTTP-методы

API поддерживает стандартные HTTP-методы:

Метод	Назначение	Пример
GET	Получить данные	GET /messages/{messageId}
POST	Создать ресурс	POST /messages
PUT	Редактировать	PUT /messages
DELETE	Удалить	DELETE /messages
PATCH	Частично изменить	PATCH /chats/{chatId}

Пример запроса GET /me для проверки бота:

{
  "user_id": 1,
  "name": "My Bot",
  "username": "my_bot",
  "is_bot": true,
  "last_activity_time": 1737500130100
}

Коды ответов

Код	Значение
200	Успешная операция
400	Недействительный запрос
401	Ошибка аутентификации
404	Ресурс не найден
405	Метод не допускается
429	Превышен лимит запросов
503	Сервис недоступен

Как получить токен бота

Токен — уникальный идентификатор для управления ботом через API. Без него ни один запрос к platform-api.max.ru не будет принят.

Создание бота через MasterBot

1. Откройте мессенджер MAX и найдите @MasterBot в поиске
2. Отправьте команду /create
3. Придумайте ник — от 11 до 60 символов, должен заканчиваться на _bot или bot
4. Укажите отображаемое имя — до 16 символов
5. Получите токен

Токен нельзя публиковать в открытом коде. Храните его в переменных окружения или файле .env.

Верификация юрлица — обязательный шаг

С августа 2025 года создавать и публиковать ботов могут только российские юридические лица. ИП, самозанятые и физлица не допускаются.

Процедура верификации:

1. Зайдите на dev.max.ru с корпоративной почтой
2. Создайте профиль организации и укажите ИНН
3. Выберите способ верификации: Госуслуги, Alfa ID, Т-Business ID или СберБизнес ID
4. Подтвердите SMS-кодом (процедуру проходит владелец или лицо с правом первой подписи)

Срок верификации — от нескольких минут до 48 часов в рабочие дни. В 2025-2026 годах бизнес-аккаунт и все функции API бесплатны.

Webhook и Long Polling: как получать обновления

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

Long Polling — для разработки

Бот периодически отправляет запрос на сервер MAX. Сервер держит соединение открытым, пока не появятся новые события, и возвращает их в ответе.

Преимущества: не нужен внешний IP, не требуется SSL-сертификат, работает за NAT и файрволом. Подходит для локальной разработки и тестирования.

Webhook — для продакшена

MAX отправляет HTTPS-запросы на указанный URL бота при каждом событии. Поддерживаются самоподписанные сертификаты.

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

Сравнение

Критерий	Long Polling	Webhook
Настройка	Минимальная	Нужен HTTPS-сервер
Задержка	Небольшая	Мгновенная
Внешний IP	Не нужен	Обязателен
SSL-сертификат	Не нужен	Обязателен (HTTPS)
Рекомендация	Разработка	Продакшен

Библиотеки и SDK для разработки

Работать с MAX API можно на любом языке через HTTP-запросы. Для популярных языков есть готовые SDK.

Python

Три основные библиотеки:

Библиотека	Описание	Установка
maxapi	Асинхронная, архитектура aiogram	pip install maxapi
maxgram	Альтернативный фреймворк	pip install maxgram
aiomax	Лёгкий клиент	pip install aiomax

maxapi — самая популярная. Использует asyncio, Dispatcher и декораторы для обработки событий, что знакомо разработчикам Telegram-ботов на aiogram.

JavaScript

Официальная библиотека от VK — @maxhub/max-bot-api. Устанавливается через npm:

npm install @maxhub/max-bot-api

Поддерживает Node.js, работу с событиями и все методы API.

Go и другие языки

Для Go доступен клиент max-bot-api-client-go на GitHub. PHP-клиент разработан сообществом (BushlanovDev/max-bot-api-client-php). Для остальных языков используйте прямые HTTP-запросы к REST API.

Создание бота на Python — пошаговый пример

Пример echo-бота на maxapi, который повторяет сообщения пользователя.

Установка и импорт

pip install maxapi

import asyncio
from maxapi import Bot, Dispatcher, F
from maxapi.types import MessageCreated

Инициализация и обработчик

bot = Bot("ваш_токен")
dp = Dispatcher()

@dp.message_created(F.message.body.text)
async def echo(event: MessageCreated):
    await event.message.answer(
        f"Повторяю: {event.message.body.text}"
    )

Декоратор @dp.message_created регистрирует функцию как обработчик входящих сообщений. Фильтр F.message.body.text пропускает только текстовые сообщения.

Запуск

async def main():
    await dp.start_polling(bot)

if __name__ == "__main__":
    asyncio.run(main())

start_polling запускает Long Polling. Для продакшена замените на Webhook.

Форматирование сообщений

MAX API поддерживает два формата разметки текста: Markdown и HTML. Формат указывается в свойстве format объекта NewMessageBody.

Markdown

Установите format: «markdown» и используйте синтаксис:

Элемент	Синтаксис
Жирный	текст
Курсив	текст
Зачёркнутый	~~текст~~
Подчёркнутый	++текст++
Код	текст
Ссылка	[текст](url)

HTML

Установите format: «html». Поддерживаемые теги: <b>, <i>, <del>, <ins>, <code>, <a href="url">.

Упоминания пользователей

Для упоминания конкретного пользователя используйте специальный формат ссылки:

• Markdown: [Имя Фамилия](max://user/user_id)
• HTML: <a href="max://user/user_id">Имя Фамилия</a>

Кнопки и inline-клавиатура

Кнопки позволяют пользователям взаимодействовать с ботом без ввода текста. MAX API поддерживает inline-клавиатуру: до 210 кнопок в 30 рядах (до 7 кнопок в ряду).

Типы кнопок

Тип	Действие
callback	Отправляет событие message_callback на сервер
link	Открывает URL в браузере
request_contact	Запрашивает контакт пользователя
request_geo_location	Запрашивает местоположение
open_app	Открывает мини-приложение
message	Отправляет текстовое сообщение

Для типов link, open_app и request_geo_location — до 3 кнопок в ряду. Максимальная длина ссылки для link — 2048 символов.

Пример inline-клавиатуры

{
  "text": "Выберите действие:",
  "attachments": [
    {
      "type": "inline_keyboard",
      "payload": {
        "buttons": [
          [
            {
              "type": "callback",
              "text": "Подписаться",
              "payload": "subscribe"
            },
            {
              "type": "link",
              "text": "Сайт",
              "url": "https://example.com"
            }
          ]
        ]
      }
    }
  ]
}

Мини-приложения

Мини-приложения — веб-приложения, работающие внутри мессенджера MAX. Аналог Mini Apps в Telegram. Открываются через кнопку типа open_app.

Требования

• HTTPS-URL (HTTP не допускается)
• Обязательная HMAC-SHA256 валидация initData — без неё приложение не пройдёт модерацию
• Подключение через мини-приложение в верифицированной организации на dev.max.ru

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

Модерация и требования к карточке бота

Перед публикацией бот проходит модерацию на платформе MAX. Срок — до 48 часов.

Требования к карточке

Параметр	Требование
Название	1-59 символов, без эмодзи
Ник	11-60 символов, окончание на _bot или bot
Сайт	HTTPS, обязателен, до 1024 символов
Логотип	500×500 px, JPG/PNG, до 5 МБ
Описание	До 200 символов

Юридические страницы

В интерфейсе бота обязательно должны быть:

• Пользовательское соглашение
• Политика конфиденциальности
• Сведения о правообладателе
• Контакты поддержки

Без этих страниц бот не пройдёт модерацию. Подробнее — в документации MAX для бизнеса.

Частые причины отказа

• Ник короче 11 символов или без окончания _bot/bot
• Эмодзи в названии
• Нет HTTPS-сайта организации
• Отсутствуют юридические страницы
• Использование старого домена botapi.max.ru вместо platform-api.max.ru

Ограничения API

Технические лимиты

• Rate limit: 30 запросов в секунду
• Медиафайлы: до 4 ГБ
• Одновременно один тип уведомлений (Webhook или Long Polling)
• При превышении лимита — код 429, при недоступности сервиса — код 503

Правовые требования

Все данные хранятся на серверах в России в соответствии с 152-ФЗ «О персональных данных». Размещение ботов — только по лицензионному договору. Запрещён контент с насилием, вредоносным кодом и запрещёнными товарами.

Поддержка разработчиков: partner@max.ru и business_support@max.ru.

FAQ

Что такое API мессенджера MAX?

REST-интерфейс для программного взаимодействия с платформой MAX. Через API боты отправляют сообщения, получают обновления, управляют чатами и загружают файлы. Запросы идут на platform-api.max.ru.

Как создать бота в MAX?

Найдите @MasterBot в мессенджере, отправьте /create, задайте ник (11-60 символов, окончание _bot) и получите токен. Для публикации нужна верификация юрлица на dev.max.ru.

Какие языки поддерживает MAX API?

Официальная SDK — на JavaScript (@maxhub/max-bot-api). Для Python: maxapi, maxgram, aiomax. Для Go: max-bot-api-client-go. Для остальных языков — прямые HTTP-запросы.

Нужна ли верификация юрлица для бота?

Да. С августа 2025 года публикация ботов доступна только юрлицам РФ. ИП, самозанятые и физлица не допускаются. Верификация через Госуслуги или банковские сервисы.

Чем API MAX отличается от Telegram Bot API?

Домен platform-api.max.ru вместо api.telegram.org. Авторизация через заголовок Authorization вместо URL-пути. Обязательная верификация юрлица. Библиотека maxapi повторяет архитектуру aiogram.

Сколько стоит создание бота в MAX?

В 2025-2026 годах бесплатно: бизнес-аккаунт, верификация, API без ограничений. VK предоставляет бесплатный доступ до введения платных тарифов.

Что выбрать — Webhook или Long Polling?

Long Polling — для разработки (не нужен внешний IP и SSL). Webhook — для продакшена (мгновенная доставка, требует HTTPS). Одновременно работает только один тип.