Мини-приложения в MAX: как устроены и чем отличаются от Telegram Mini Apps
Мини-приложение в MAX — обычная веб-страница на HTTPS, которую открывает бот. Ниже — как его подключить, чем MAX Bridge отличается от Telegram.WebApp и что можно переиспользовать, если уже есть Mini App в Telegram. Факты сверены с документацией на 6 ноября 2026 года.
Содержание
В Telegram Mini App уже привычный инструмент: каталог, запись, калькулятор — всё внутри чата. В MAX схема похожая, но не копия. Приложение живёт только вместе с ботом, подключается через платформу для партнёров, а клиентский объект называется window.WebApp, а не window.Telegram.WebApp.
Я опираюсь на документацию MAX по мини-приложениям, MAX Bridge, валидацию данных и Telegram Mini Apps. Отдельно — на демо «Зерно и Пар»: Telegram Mini App кофейни лежит на tsemeneev.ru/coffee-app, бэкенд общий, и тот же интерфейс можно открыть в браузере.
Что такое мини-приложение в MAX
Это HTML, CSS и JavaScript на вашем хостинге. Пользователь нажимает кнопку в чате с ботом — и страница открывается внутри клиента MAX. Отдельного магазина приложений нет: URL вы сами указываете в настройках бота.
По FAQ MAX мини-приложение без чат-бота подключить нельзя. Через бота оно ходит в Bot API, получает пользователя и шлёт уведомления. Автономного «просто веб-приложения в MAX» нет.
Подключение доступно юрлицам, ИП и самозанятым — резидентам РФ. Это то же ограничение, что и для ботов на платформе партнёров. Подробности про регистрацию и модерацию — в статье «Бот в MAX для бизнеса».
Как подключить
- Выложите файлы на хостинг с HTTPS. В документации упоминают VK Cloud, GitHub Pages, Yandex Cloud; для продакшена подойдёт любой нормальный хост с сертификатом.
- Откройте платформу MAX для партнёров → Чат-боты → нужный бот → «Настройки».
- Вставьте URL мини-приложения и выберите подпись кнопки: «Открыть», «Старт», «Играть» или без названия.
- Сохраните. В чате с ботом появится кнопка запуска.
Требования к URL из документации:
- длина не больше 1024 символов;
- только
https://; - допустимы латиница, цифры, точка и дефис;
- пробелы запрещены.
Обновить приложение можно двумя способами. Если URL тот же — достаточно задеплоить новую версию на хост, пользователи получат её при следующем открытии. Если адрес сменился — поправьте ссылку в настройках бота.
Одновременно два мини-приложения открыть нельзя: новое закрывает текущее. В FAQ MAX написано, что поддержку нескольких окон сразу ещё делают.
Как открыть: кнопка настроек, open_app и диплинк
Постоянная кнопка в чате с ботом появляется после сохранения URL в настройках. Это основной вход для пользователя, который уже пишет боту.
Вторую точку входа даёт кнопка типа open_app в inline_keyboard. Её кладут под сообщением — например, «Открыть каталог» в приветствии. В справке по клавиатуре у open_app лимит как у ссылок: не больше трёх таких кнопок в одном ряду. В поле web_app передают HTTPS-адрес мини-приложения.
Третий способ — диплинк:
https://max.ru/<имя_бота>?startapp=<payload>
payload опционален, до 512 символов. Разрешены только A–Z, a–z, 0–9, _ и -. Если превысить лимит или вставить недопустимый символ, платформа вырежет payload из ответа. Значение приходит в initDataUnsafe.start_param и в сырой строке initData.
Типичные сценарии из документации MAX: QR на столике с startapp=feedback_rest123, промокод promo123, метка источника your_site, номер заказа order_12345. В payload не кладут телефон и пароль открытым текстом — только одноразовый токен или закодированный идентификатор сессии.
Для сравнения: в Telegram точек входа больше. Там есть кнопка меню, inline-кнопка, главное мини-приложение в профиле бота, прямая ссылка https://t.me/бот/приложение, inline-режим и меню вложений. В MAX набор короче: настройки бота, open_app и ?startapp=.
MAX Bridge: объект window.WebApp
Скрипт подключают с CDN:
<script src="https://st.max.ru/js/max-web-app.js"></script>
После загрузки доступен window.WebApp. Отдельный ready() в духе Telegram документация не требует: объект создаётся при запуске, данные уже предзагружены.
Что есть из коробки (по описанию Bridge):
initData— сырая строка для проверки на сервере;initDataUnsafe— тот же набор уже разобранный в JSON (для UI, не для доверия);platform—ios,android,desktop,web;versionиdeviceName;BackButton— кнопка «Назад» в шапке;HapticFeedback— вибрация (impactOccurred,notificationOccurred,selectionChanged);requestContact()— запрос номера с отдельной проверкой HMAC;enableClosingConfirmation/disableClosingConfirmation;openLink(внешний браузер) иopenMaxLink(диплинк внутри MAX);downloadFile(url, file_name)— скачивание только по HTTPS и только после клика пользователя; обычный<a href>в Bridge не используют;shareContent/shareMaxContent— шеринг наружу или внутрь MAX;openCodeReader— QR с камеры или из файла;DeviceStorageиSecureStorage(во втором — до 10 ключей на пользователя; в вебе эти хранилища не работают);BiometricManager— отпечаток или лицо (не на десктопе и не в вебе);PermissionsManager— камера и микрофон (на момент документации — Android и веб, с оговоркой следить за обновлениями);NfcManager— только Android.
Для визуальной части MAX отдаёт библиотеку React-компонентов MAX UI и гайдлайн в .fig. Это не обязательный стек: подойдёт и чистый JS, и Vue, и Svelte. UI-кит просто быстрее приводит интерфейс к привычному виду клиента MAX.
Чего в Bridge нет в том виде, к которому привыкли в Telegram: отдельной MainButton / SecondaryButton внизу экрана, CloudStorage на 1024 ключа, openInvoice и оплаты Stars, shareToStory, акселерометра и гироскопа. Если ваш Telegram Mini App завязан на нижнюю кнопку «Оформить» и счёт через openInvoice, в MAX эти куски придётся заменить своим UI и ссылкой на платёжную страницу провайдера. Про отсутствие платежей в MAX Bot API я уже писал в статье про перенос бота.
Проверка initData на сервере
Правило то же, что в Telegram: браузеру нельзя доверять. Пользователь может подменить user.id в DevTools. Сервер обязан проверить подпись строки initData (или параметра WebAppData из URL-фрагмента).
Алгоритм из документации MAX:
- Разобрать пары
key=value, сохранитьhash, остальные поля URL-декодировать. - Отсортировать ключи по алфавиту и склеить через перевод строки:
key1=value1\nkey2=value2. - Получить секрет:
HMAC-SHA256от токена бота с ключомWebAppData. - Подписать строку этим секретом, сравнить hex с пришедшим
hash. - Отбросить данные старше часа по
auth_date— такой интервал рекомендует сама документация.
На Python проверка почти один в один совпадает с Telegram:
import hmac, hashlib, time
from urllib.parse import parse_qsl
from operator import itemgetter
def check_max_init_data(init_data: str, bot_token: str, max_age: int = 3600) -> dict | None:
params = list(dict(parse_qsl(init_data, keep_blank_values=True)).items())
received = next((v for k, v in params if k == "hash"), None)
if not received:
return None
to_sign = sorted([(k, v) for k, v in params if k != "hash"], key=itemgetter(0))
data_check = "\n".join(f"{k}={v}" for k, v in to_sign)
secret = hmac.new(b"WebAppData", bot_token.encode(), hashlib.sha256).digest()
calc = hmac.new(secret, data_check.encode(), hashlib.sha256).hexdigest()
if not hmac.compare_digest(calc, received):
return None
fields = dict(to_sign)
if time.time() - int(fields.get("auth_date", 0)) > max_age:
return None
return fields
initDataUnsafe для этой проверки не годится — только сырая строка. Цену заказа, как и в Telegram-версии, считает сервер по своему прайсу: фронт присылает состав корзины, а не сумму.
Чем MAX отличается от Telegram Mini Apps
| Тема | MAX | Telegram |
|---|---|---|
| Кто может подключить | Юрлицо, ИП, самозанятый (РФ), бот на платформе партнёров | Любой аккаунт через BotFather |
| Где живёт приложение | Только внутри бота | Бот, главное Mini App, прямые ссылки, inline, меню вложений |
| Клиентский объект | window.WebApp из max-web-app.js |
window.Telegram.WebApp из telegram-web-app.js |
| Диплинк | https://max.ru/<бот>?startapp= , payload до 512 символов |
t.me/<бот>?startapp= или t.me/<бот>/<app> |
| Проверка данных | HMAC-SHA256, ключ WebAppData |
Тот же алгоритм |
| Нижние нативные кнопки | Нет аналога MainButton/SecondaryButton в Bridge | MainButton и SecondaryButton |
| Оплата из мини-приложения | Методов оплаты в Bot API нет; ссылка на провайдера | Провайдеры + Stars, openInvoice |
| Облачное хранилище | DeviceStorage / SecureStorage на устройстве | CloudStorage до 1024 ключей + DeviceStorage / SecureStorage |
| Несколько окон | Новое закрывает текущее | Обычное поведение вкладок/шторки клиента |
Меню, корзина, слоты самовывоза, админка и база заказов могут быть общими для обеих платформ. Меняются оболочка (скрипт клиента), проверка токена конкретного бота и способ открытия.
Что переносится, если Mini App уже есть в Telegram
Фронтенд режут на три слоя:
- Бизнес-экран — каталог, форма, корзина. Его трогать почти не нужно.
- Адаптер платформы — тонкая обёртка: где взять
initData, как показать «Назад», как вибрануть, как открыть внешнюю ссылку. В Telegram это вызовыTelegram.WebApp.*, в MAX —WebApp.*с другими именами. - Бэкенд — один. Два токена ботов, две проверки подписи (алгоритм один, секреты разные), общие заказы и статусы.
На практике для «Зерно и Пар» меню из 16 позиций, настройка напитка и слоты самовывоза живут в одной вёрстке. Telegram-ветка подключает telegram-web-app.js и нативные кнопки; браузерная открывает ту же страницу без мессенджера. Ветку для MAX делают так же: другой скрипт, другая кнопка запуска, тот же API заказов. Как устроен сам Telegram Mini App для кафе, разобрано отдельно: «Telegram Mini App для кафе и магазина».
Перенос ботовой части (сообщения, вебхук, кнопки) — другая задача. Её я расписал в «Как перенести Telegram-бота в MAX».
Для каких задач это подходит
Каталог с фильтрами и фото, запись на услугу с календарём, программа лояльности, статус заказа по номеру из диплинка, внутренний кабинет сотрудника. Всё, где чат с кнопками неудобен, а ставить нативное приложение рано.
Не стоит ждать от MAX Mini App того, чего нет в API. Если нужна оплата внутри шторки одним тапом — пока только редирект на ЮKassa или другого провайдера, а бот меняет статус после вебхука оплаты. Если нужна витрина в глобальном каталоге приложений Telegram — в MAX такого магазина в документации нет.
Ориентир по срокам и деньгам зависит от объёма экранов и интеграций. Простая витрина с корзиной и уведомлением в чат обычно ближе к срокам обычного лендинга плюс бот; каталог на сотни позиций с личным кабинетом и синхронизацией остатков — уже полноценный веб-проект. Из чего складывается бюджет бота и приложений вокруг него — в статье «Сколько стоит разработать чат-бота для MAX».
С чего начать
- Зарегистрируйте организацию и бота на платформе партнёров заранее: модерация идёт параллельно с вёрсткой.
- Выложите черновик страницы на HTTPS и пропишите URL в настройках бота — так сразу проверяется кнопка запуска на телефоне.
- Подключите
max-web-app.js, выведитеplatformиinitDataUnsafe.userна экран отладки. - Сразу напишите проверку
initDataна бэкенде и гоняйте её автотестом: без этого любой следующий экран бессмысленен. - Если уже есть Telegram Mini App — вынесите вызовы
Telegram.WebAppв адаптер, прежде чем копировать экраны.
Документация MAX за 2026 год уже несколько раз меняла адреса API и детали платформы. Перед стартом откройте dev.max.ru/docs/webapps/introduction в день работ и сверьте лимиты startapp и список методов Bridge.
Если нужно мини-приложение в MAX под каталог, запись или кабинет — напишите, что должно происходить за первый экран. Посмотрю объём и скажу, что переедет из Telegram-версии без переписывания, а что придётся сделать отдельно.
Посмотреть вживую
Мои демо-проекты по теме статьи. Они работают, их можно открыть и потрогать. Это демонстрации, а не работы для клиентов.