Как создать мини-приложение в MAX: шаги и требования

Мини-приложение в MAX — это обычный веб-сайт на HTML, CSS и JavaScript, который открывается внутри чат-бота. Чтобы его создать, нужно зарегистрировать профиль организации, ИП или самозанятого на платформе MAX для партнёров, создать бота, разместить приложение на хостинге с HTTPS и вставить его адрес в настройки бота. Всё это описано в документации MAX, ниже — шаги и подводные камни.

Кто может создать мини-приложение

По документации, подключение к платформе MAX для партнёров доступно юрлицам, ИП и самозанятым — резидентам РФ. Профиль проходит верификацию. Частному лицу без статуса опубликовать бота и мини-приложение не получится. Сервисы Цифрового ID и «Госключа» внутри мини-приложений доступны только юрлицам и ИП.

Создание мини-приложения: пошагово

1. Зарегистрируйтесь на платформе MAX для партнёров и пройдите верификацию профиля (инструкция).
2. Создайте чат-бота в разделе «Чат-боты» и дождитесь, пока он станет доступен (создание бота).
3. Сделайте веб-приложение и подключите библиотеку MAX Bridge: скрипт https://st.max.ru/js/max-web-app.js.
4. Разместите приложение на хостинге с HTTPS.
5. На платформе откройте «Чат-боты» → нужный бот → «⋮» → «Настройки» и вставьте адрес мини-приложения.
6. Выберите вид кнопки запуска: «Открыть», «Старт», «Играть» или без подписи. Сохраните.
7. Откройте бота в MAX и проверьте запуск на iOS, Android, в десктопе и веб-версии.

К адресу есть требования: только https, не длиннее 1024 символов, без пробелов, латиница, цифры, точка и дефис. Изменить адрес или убрать приложение можно в тех же настройках бота.

Что умеет MAX Bridge

После подключения скрипта в приложении появляется объект window.WebApp. Он передаёт данные запуска и даёт доступ к функциям мессенджера и устройства (описание Bridge).

Для интерфейса MAX рекомендует свою библиотеку React-компонентов MAX UI, но использовать её не обязательно.

Как открыть мини-приложение по ссылке

Помимо кнопки в чате, приложение открывается по прямой ссылке вида https://max.ru/имя_бота?startapp. Можно передать параметр: https://max.ru/имя_бота?startapp=promo_2026 — до 512 символов, латиница, цифры, подчёркивание и дефис. Его можно получить в приложении через initDataUnsafe.start_param и, например, сразу открыть нужный товар или акцию.

Проверка пользователя на сервере

initDataUnsafe удобно читать в интерфейсе, но доверять ему нельзя: подделать его может кто угодно. Если приложение принимает заказы, начисляет бонусы или показывает личные данные, сервер должен проверить подпись строки initData. Алгоритм описан в разделе о валидации: из строки отделяется hash, остальные пары сортируются, секретный ключ получается через HMAC-SHA256 от токена бота с ключом WebAppData, затем считается подпись и сравнивается с hash.

Токен бота хранится только на сервере, в коде фронтенда его быть не должно.

Ограничения, о которых стоит знать заранее

• Мини-приложение не существует отдельно: только внутри чат-бота.
• Часть функций не работает в веб-версии и десктопе — проверяйте на всех платформах.
• Приложение должно соответствовать правилам платформы и законам РФ.
• Если вы собираете телефон или другие данные, нужна политика обработки персональных данных и согласие по 152-ФЗ.

Свой код или конструктор

Платформа поддерживает интеграцию с партнёрами, в том числе конструкторами мини-приложений, которым передаётся токен бота. Конструктор подходит для витрины или записи по шаблону. Своя разработка нужна, когда приложение связано с вашей CRM, складом, 1С или оплатой, или когда то же приложение должно работать и в Telegram.

Какие сценарии мини-приложений окупаются, мы собрали в статье 9 сценариев для Telegram и MAX, а про перенос существующего бота — в разборе перехода с Telegram на MAX. Если нужна разработка под ключ, посмотрите разработку мини-приложений: там примеры и цена. Бюджет можно прикинуть в калькуляторе стоимости разработки.