Коротко
- Токен появляется только после модерации бота — до 48 часов по рабочим дням, и до этого ни одного запроса к API не отправить.
- В продакшене поддерживается только вебхук: HTTPS на 443 порту, сертификат доверенного УЦ, ответ 200 за 30 секунд.
- Технические лимиты известны заранее: 30 запросов в секунду на домен API, два сообщения в секунду в один диалог, до 4000 символов в тексте.
- Главное ограничение не техническое: правила запрещают отправлять через API авторизационные, транзакционные, сервисные и массовые сообщения вне отдельного договора с компанией.
Честно про ссылки
Часть ссылок на сервисы в статье может быть партнёрской: если перейти по такой ссылке и оплатить, vakas.ru получит часть платежа. На отбор сервисов и на оценки в тексте это не влияет: сервисы попали в статью потому, что заявляют поддержку MAX, а не потому, что у них есть партнёрская программа.
Bot API у MAX устроен узнаваемо: HTTP-запросы, JSON, вебхуки, inline-клавиатура. Разработчик, писавший ботов под другие мессенджеры, узнает знакомую механику. Сложность проекта задают при этом не методы, а рамка из верификации, модерации и правил платформы.
Токен выдают не всем и не сразу
Бот заводится в кабинете платформы «MAX для Партнеров»: сначала нужно подключиться к ней и верифицировать профиль организации, ИП или самозанятого — доступ есть только у резидентов России, физлицам и нерезидентам верификация закрыта. Как устроена платформа, разобрано в обзоре MAX для бизнеса, пошаговое создание бота — в инструкции по чат-боту в MAX.
Дальше модерация: до 48 часов по рабочим дням. Токен формируется только после успешной проверки, вместе с расширенными настройками. Тот же срок держите в уме и после запуска: правка карточки уже одобренного бота отправляет его на проверку заново, хотя для пользователей он всё это время работает в прежнем виде.
Ботов на профиль немного: пять у организации и ИП, два у самозанятого. Ник тоже не выбирают — он генерируется автоматически: из ИНН у компаний и ИП, из идентификатора профиля у самозанятых. Авторизация — только заголовком Authorization: передача токена в query-параметрах больше не поддерживается, так что код, написанный под старую схему, придётся править.
Из чего состоит API
Методы делятся на шесть групп: bots, chats, subscriptions, upload, messages и comments — от данных о самом боте и работы с участниками чата до отправки сообщений и комментариев к постам в каналах. Текст — до 4000 символов, разметка через Markdown или HTML.
Inline-клавиатура щедрая: до 210 кнопок в 30 рядах, до 7 в ряду и всего 3, если это ссылка, запуск мини-приложения, запрос контакта или геопозиции. Деталь, которую легко пропустить: пересланное в другой чат сообщение теряет кнопки.
| Ограничение | Значение |
|---|---|
| Запросов в секунду на домен API | 30 |
| Сообщений в секунду в один диалог, чат или канал | 2 |
| Длина текста сообщения | 4000 символов |
| Вложений в одном сообщении | не более 12 |
| Изображение | до 50 МБ и не более 7680×7680 px |
| Видео | до 250 МБ |
| Аудио | до 256 МБ и не более 60 минут |
| Файл | до 4 ГБ |
При превышении темпа документация предписывает ставить сообщения в очередь или добавлять задержку — быстрее лимита отправлять не разрешено. Файлы грузятся отдельным методом, в ответ приходит токен вложения. Отправить файл при этом можно только вместе с вложением-клавиатурой, но не с картинкой или видео.
В продакшене только вебхук
Документация категорична: боевое окружение — Webhook, разработка и тестирование — Webhook или Long Polling. Разница в том, кто кого спрашивает: при вебхуке платформа сама отправляет события на ваш URL, при long polling бот периодически запрашивает обновления сам. Одновременно два способа не работают: при активной подписке на вебхук long polling отключается, а причина названа прямо — он ограничен по скорости и по сроку хранения событий.
Требования к точке приёма строгие: HTTPS на 443 порту, сертификат от доверенного удостоверяющего центра или Минцифры с полной цепочкой, совпадение домена из URL с CN или SAN, ответ HTTP 200 в течение 30 секунд. Самоподписанные сертификаты и вебхуки по обычному HTTP отключены с 25 мая 2026 года.
Почему таймаут важен, объясняет механика повторов. При неудаче платформа делает до 10 повторных попыток с растущим интервалом: первая через минуту, вторая через 150 секунд, третья через 375. Если за 8 часов не приходит ни одного успешного ответа HTTP 200, бот автоматически отписывается от событий.
Отсюда устройство обработчика: отвечать сразу, тяжёлую логику уводить в очередь, а состояние подписки на события держать под мониторингом.
Подлинность запроса проверяется параметром secret на 5–256 символов: платформа передаёт его в заголовке X-Max-Bot-Api-Secret. Формально параметр необязательный, но других документированных способов убедиться, что запрос пришёл от MAX, в справочнике нет.
Правила ограничивают сильнее лимитов
Самый важный для оценки проекта абзац лежит не в справочнике, а в требованиях к приложениям разработчиков. Пункт 1.5 запрещает использовать API или иную техническую интеграцию для отправки авторизационных, транзакционных и сервисных сообщений, а также рекламных, маркетинговых и любых иных массовых рассылок — кроме случаев, прямо предусмотренных договором с компанией. И отдельная оговорка: вне зависимости от наличия технической возможности.
Перечитайте, если планировали слать одноразовые коды, уведомления о списаниях или статусы заказов: все три категории названы в правилах поимённо, а сервисным вдобавок запрещено содержать рекламу. Что можно в массовых сообщениях — в материале про рассылки в MAX.
Общие условия лицензии добавляют рамку: сообщения через бот отправляются только его подписчикам и должны быть обусловлены их взаимодействием с приложением. Рекламное содержание запрещено, а признаки рекламы определяются исключительно усмотрением лицензиара. Отдельный пункт разрешает компании без объяснения причин приостановить или прекратить доступ к вашему приложению.
И про деньги: создание, размещение и эксплуатация бота отдельного вознаграждения не требуют, но отдельные функции могут предоставляться платно. Вознаграждение считается по количеству активных пользователей за отчётный период и (или) иным метрикам в соответствии с тарифами, причём каждый бот — самостоятельная единица тарификации. Публичного прайса нет, перечень тарифов показывают внутри кабинета — посчитать бюджет снаружи не выйдет.
Мини-приложения: обычный веб внутри бота
Мини-приложение не существует отдельно, оно работает только внутри чат-бота. Это обычный фронтенд на HTML, CSS и JavaScript на вашем хостинге, отдаваемый по https, а его URL подключается в расширенных настройках бота.
Две библиотеки снимают часть работы. MAX Bridge открывает возможности мессенджера и устройства: чтение кодов камерой, защищённое хранилище, биометрию, NFC. Номер телефона свободно не отдаётся — метод requestContact() запрашивает его у пользователя в модальном окне нативного клиента, а использовать полученные данные документация разрешает только для взаимодействия с этим же мини-приложением. MAX UI даёт React-компоненты под интерфейс MAX.
Часть объектов не работает в веб-клиенте, биометрия — ещё и в десктопном, деградацию интерфейса надо предусматривать.
Запуск с параметром идёт диплинком вида https://max.ru/<botName>?startapp=<payload>, payload — до 512 символов. Стартовые параметры подписаны, и валидировать их обязательно: платформа отдаёт хеш, который проверяется через HMAC-SHA256 с токеном бота в основе ключа.
А вот документированного способа принять оплату внутри мини-приложения нет: ни в MAX Bridge, ни в Bot API методов оплаты или выставления счетов не описано. Встроенная платёжная система в справке MAX упомянута, но одной фразой — без условий, комиссий и технических подробностей, так что единственный документированный путь к оплате остаётся прежним: кнопка со ссылкой на внешний платёж.
SDK, обёртки и темп изменений
Официальных библиотек две: JavaScript/TypeScript и Go. Для Python, PHP и остального — либо обычные HTTP-запросы, либо сторонние обёртки без официальной поддержки. Темп изменений закладывайте в сопровождение: в июне 2026 перестал поддерживаться метод получения списка чатов и появились лимиты на размеры вложений, в июле добавилось управление командами бота, в августе — группа методов для комментариев к постам; вебхуки по обычному HTTP отключили ещё в мае.
Если писать код не хочется
Не каждой задаче нужен свой сервис на вебхуках. Готовые конструкторы подключаются по тому же токену бота и дают собрать сценарий без разработки — шесть таких платформ сравниваются в обзоре конструкторов ботов для MAX.
Промежуточный вариант — шлюзы с собственным HTTP-API поверх нескольких мессенджеров сразу: Wappi и Green API, оба заявляют поддержку MAX. Смысл в них появляется, когда каналов несколько.
Способ подключения уточняйте до оплаты. Сервисы-партнёры подключаются к боту его токеном с платформы, но часть агрегаторов работает через привязку личного аккаунта по QR-коду, а это сторонняя сессия устройства и риск блокировки. Связка с CRM разобрана в материале про мессенджеры в CRM через MAX.
Кому браться за API
Решение начинается не с методов, а с типа сообщений. Выпишите всё, что бот будет отправлять, и сверьте с правилами: авторизационные (одноразовые коды и ссылки для входа), транзакционные (движение денег по счетам и картам), сервисные (статусы и события ваших услуг) и массовые рекламные сообщения через API запрещены вне случаев, прямо предусмотренных договором с компанией. Если ваш сценарий попал в эти четыре категории, первым шагом идёт договорное основание, а не разработка: техническая возможность отправить сообщение правил не отменяет.
Если же продукт живёт внутри диалога, который пользователь начал сам, и опирается на мини-приложение внутри бота, техническая часть предсказуема: состав методов, лимиты и требования к вебхуку известны заранее. И отдельный фильтр на входе: без российского юрлица, ИП или самозанятости доступа к платформе не будет вовсе.
Где теряют время и деньги
- Ставят релиз без запаса на модерацию. Токена нет до её окончания, а это до 48 часов по рабочим дням, и любая правка карточки бота отправляет его на проверку заново.
- Отвечают на вебхук после обработки. Не уложились в 30 секунд — платформа уходит в повторы, а если за 8 часов не будет ни одного успешного ответа HTTP 200, бот отпишется от событий сам.
- Проектируют на API уведомления и рассылки. Пункт 1.5 требований запрещает их вне случаев, прямо предусмотренных договором с компанией, — договорное основание выясняют до проектирования, а не после.
- Закладывают оплату внутри мини-приложения. Документированных платёжных методов нет ни в Bot API, ни в MAX Bridge, остаётся кнопка со ссылкой на внешнюю оплату.
Частые вопросы
Можно ли получить токен без юрлица?
Без статуса нет: подключение доступно юрлицам, ИП и самозанятым, которые являются резидентами России, а для физлиц и нерезидентов верификация закрыта. Самозанятый подойдёт, но с лимитом в два бота против пяти у организации и ИП.
Может ли бот написать пользователю первым?
Метод отправки принимает идентификатор пользователя, но условия лицензии разрешают писать только подписчикам бота и в связи с их взаимодействием с приложением, а массовые рассылки через API запрещены вне договора. Прямого ответа документация не даёт, поэтому строить сценарий на инициативных сообщениях рискованно.
Сколько стоит бот на платформе?
Создание и размещение отдельного вознаграждения не требуют, но отдельные функции могут предоставляться платно: расчёт идёт по количеству активных пользователей за отчётный период и (или) иным метрикам в соответствии с тарифами, и каждый бот считается самостоятельной единицей тарификации. Публичного прайс-листа нет, перечень действующих тарифов доступен в кабинете.
Порядок работы над ботом в MAX разумно перевернуть по сравнению с привычным. Сначала классификация: какие типы сообщений бот будет отправлять и попадают ли они в авторизационные, транзакционные, сервисные или массовые. Если попадают — подтверждайте договорное основание с компанией. И только потом техническое задание, лимиты и код: требования к приложениям разработчиков и общие условия лицензии стоит прочитать раньше, чем откроете редактор.
