Что такое MAX Bot API

Если убрать маркетинговую шелуху, MAX Bot API это официальный HTTP API для чат-ботов в MAX. Через него можно отправлять сообщения, получать события, отвечать на нажатия кнопок и работать с файлами. Документация и описание методов лежат в официальном разделе MAX для разработчиков.

Это важно проговорить отдельно: MAX Bot API и личный номер в Релае это не одно и то же. Бот работает через официальную модель платформы MAX. Личный номер в Релае это отдельный сценарий подключения реальной сессии пользователя. Если вам нужен именно бот, ориентируйтесь на официальную документацию MAX. Если нужен быстрый self-serve запуск живого диалога, чаще полезнее сравнить бот и личный номер до начала интеграции.

Ещё одно полезное разделение: официальный MAX Bot API почти всегда начинается с raw HTTP-примеров, а у Релая уже есть готовые пакеты для Node.js, Python и PHP. Если ваша команда идёт через Релая API, не обязательно начинать с ручного клиента.

Что нужно до первого запроса

Самая частая ошибка в статьях про MAX в том, что они создают ощущение: достаточно придумать токен и сразу начинать слать сообщения. На практике у официального Bot API есть подготовительный контур.

Нужен подтверждённый профиль организации или ИП в платформе для разработчиков MAX.
В документации MAX указано, что на одну организацию можно создать до пяти ботов.
У бота есть карточка, токен и процесс модерации. Пока бот не одобрен, не стоит обещать бизнесу мгновенный прод-запуск.

Перед стартом полезно пройти короткий чек-лист запуска MAX-бота, а не прыгать сразу в код. Так вы быстрее поймёте, где у вас инфраструктурная задача, а где организационная.

Какие методы реально нужны на старте

На первом этапе большинству команд не нужен весь API. Хватает пяти вещей:

POST /messages — отправить текст, кнопки или вложения.
POST /subscriptions — подключить webhook.
GET /updates — временно получать события long polling, если вы ещё не готовы к webhook.
POST /uploads — загрузить файл до отправки.
POST /answers — ответить на callback после нажатия кнопки.

Полный список методов есть в официальной документации. Но в реальном продукте первый полезный цикл почти всегда выглядит так: создали бота → получили токен → отправили сообщение → подключили события.

Первое сообщение

В официальной документации MAX для отправки используется домен https://platform-api.max.ru и заголовок Authorization: Bearer .... Это лучше сразу зафиксировать в коде и во внутренних заметках команды, чтобы не таскать по проекту старые примеры с query-параметром токена.

curl -X POST "https://platform-api.max.ru/messages?chat_id=1234567890" \
  -H "Authorization: Bearer YOUR_MAX_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Привет! Это первое тестовое сообщение из MAX Bot API."
  }'

Если вам нужен не чистый бот, а быстрый запуск через личный номер и единый API поверх нескольких каналов, тогда логичнее идти через MAX в Релае. Но для официального Bot API стартовать стоит именно с этого базового запроса.

Для пути через Релая тот же сценарий можно собрать быстрее через официальные SDK, а raw HTTP оставить как запасной низкоуровневый слой.

Webhook или long polling

У MAX есть два способа получать события от бота. Для отладки и первых экспериментов можно использоватьGET /updates. Для реального продукта почти всегда нужен webhook через POST /subscriptions.

Подход	Когда подходит	Что помнить
Long polling	Локальная разработка, дебаг, быстрый прототип	Проще начать, но хуже для постоянной серверной обработки
Webhook	Продакшен, интеграция с CRM, операторские сценарии	Нужен HTTPS endpoint и аккуратная обработка дублей

Подробный разбор событий и настроек есть в статье про webhook в MAX Bot API, а отдельное сравнение двух подходов вынесено в материал Webhook или long polling в MAX.

Что известно по лимитам

Здесь лучше быть аккуратным. Вокруг MAX уже успело появиться много статей с придуманными цифрами. Из того, что официальная документация подтверждает прямо:

До 30 запросов в секунду на platform-api.max.ru.
До 4000 символов в текстовом сообщении.
До 210 кнопок в inline-клавиатуре, не более 30 рядов и обычно не более 7 кнопок в одном ряду.
До 4 ГБ для загрузки файла через POST /uploads.
Для webhook важен ответ сервера не дольше 30 секунд.

Для старта этого уже достаточно. Всё остальное лучше считать не “официальным лимитом”, а вашей собственной инженерной политикой. Например, многие команды сознательно начинают ниже верхней границы по RPS, чтобы не словить 429 при первом пике.

Бот или личный номер

Если вам нужен официальный сценарий с модерацией, карточкой бота и стандартным Bot API, выбирайте бот. Если бизнесу важнее быстро проверить живой диалог, личный номер через QR и понятный self-serve запуск, иногда быстрее идти через личный MAX-профиль в Релае.

Бот лучше подходит для кнопок, автоматизации, deep links и предсказуемой bot-first модели.
Личный номер чаще выигрывает там, где нужен “живой” чат и быстрый тест без отдельного bot setup.

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

MAX Bot API уже даёт нормальный фундамент для ботов и сервисных сценариев. Но лучший старт это не “прочитать все методы”, а быстро собрать один рабочий цикл: токен, сообщение, событие, обработка ответа.

MAX Bot API: что это такое и с чего реально начать