Мини-приложения в MAX — веб-сайты и программы, которые запускаются прямо в мессенджере: например, интернет-магазины или игры. Отдельно от чат-ботов они не существуют: мини-приложение открывается кнопкой в чате с его ботом, по ссылке вида max.ru/<имя бота>?startapp или, если это встроенное мини-приложение вроде Семейной защиты, из настроек MAX. Сделать своё может организация, ИП или самозанятый — резидент РФ: мини-приложение привязывают к боту на платформе MAX для партнёров. Ниже — как открыть мини-приложение, как подключить своё, что умеет библиотека MAX Bridge и как проверять данные запуска.

Что такое мини-приложения MAX

Справка MAX называет мессенджер приложением со встроенной платформой мини-приложений, конструкторами чат-ботов и платёжной системой. Документация для разработчиков уточняет: мини-приложения работают только внутри чат-ботов и не могут существовать автономно. Они написаны на обычных веб-технологиях — HTML, JavaScript, CSS, — их не нужно дорабатывать под разные платформы и модерировать в магазинах приложений. Бизнесу они снимают нагрузку с продаж и поддержки: заказ принимается без перехода на внешний сайт.

Два примера из самой MAX:

Семейная защита — мини-приложение, в котором взрослый задаёт близким безопасные настройки приватности (Настройки → Безопасность → Семейная защита). Подробно — в статье «MAX для детей: семейная защита».
MAX для бизнеса — мини-приложение, в котором компании проходят верификацию, создают бота и канал. О нём — в статье «MAX для партнёров: регистрация и верификация».

У официальных ботов галочка напротив названия подтверждает, что бот и мини-приложение в нём созданы представителями соответствующей организации. Что ещё встроено в мессенджер — в статье «Что такое мессенджер MAX».

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

Кнопкой в чате с ботом. Когда разработчик подключает мини-приложение, в чате с его ботом появляется заметная кнопка быстрого запуска. Надпись на ней выбирает разработчик: Открыть, Старт, Играть или без названия.
По прямой ссылке вида https://max.ru/<botName>?startapp — мини-приложение откроется внутри MAX. После ?startapp в ссылку можно добавить стартовые параметры.
Кнопкой в сообщении бота с типом open_app — она открывает мини-приложение внутри чат-бота.
Из настроек MAX. Встроенные мини-приложения открываются из интерфейса: Семейная защита — Настройки → Безопасность → Семейная защита, Цифровой ID — Настройки → Безопасность → Мини-приложения. Метод getLaunchContext() различает и другие точки входа: нижнюю панель вкладок, список чатов и экран чата.

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

Как подключить своё мини-приложение

Что нужно заранее

Верифицированный профиль организации, ИП или самозанятого на платформе MAX для партнёров и бот, который прошёл модерацию. Подключить мини-приложение без чат-бота нельзя: через бота оно работает с API. Как получить бота и его токен — в статье «API MAX для ботов».
Компьютер с Windows, macOS или Linux, мобильное устройство для регистрации профиля в MAX, редактор кода и навыки работы с командной строкой.
Хостинг для файлов .html, .css, .js и медиа — документация называет VK Cloud (там запущен хостинг мини-приложений), GitHub Pages и Yandex Cloud. Приложение должно работать по https.

Чтобы создать мини-приложение самому, нужны навыки программирования. Без разработки его собирают в конструкторах мини-приложений — это один из видов сервисов партнёров MAX. Чтобы подключить мини-приложение к боту, собранному в конструкторе, в настройках конструктора находят MAX, указывают токен бота и включают интеграцию.

Как добавить мини-приложение к боту

Откройте платформу MAX для партнёров → Чат-боты → Перейти.
Выберите бота и нажмите ⋮ → Настройки.
Вставьте URL мини-приложения в поле для ссылки.
Выберите вид кнопки открытия — Открыть, Старт, Играть или без названия — и нажмите Сохранить.

Те же шаги работают в мини-приложении «MAX для бизнеса».

Требование к URL	Значение
Длина	не более 1024 символов
Протокол	только `https://`
Символы	латинские буквы, цифры, точка и дефис
Пробелы	не поддерживаются
Формат	URL должен быть валидным

Как обновить, сменить кнопку или удалить

Если адрес мини-приложения статичный, обновления выкатываются без платформы: после деплоя пользователи запустят новую версию. Если адрес поменялся, откройте Чат-боты → бот → ⋮ → Настройки, укажите новую ссылку и нажмите Сохранить. Там же меняют вид кнопки открытия. Чтобы удалить мини-приложение, удалите URL из поля для ссылки и нажмите Сохранить.

MAX Bridge: что умеет библиотека

Чтобы мини-приложение обменивалось данными с MAX, подключите библиотеку MAX Bridge через CDN:

<script src="https://st.max.ru/js/max-web-app.js"></script>

После этого доступен глобальный объект window.WebApp — он создаётся при каждом запуске и не требует отдельной инициализации. Данные запуска лежат в двух полях:

window.WebApp.initData — строка в URL-кодировке для проверки на сервере;
window.WebApp.initDataUnsafe — те же данные объектом: user (id, имя, фамилия, никнейм, язык, фото), chat (id и тип — DIALOG, CHAT или CHANNEL), start_param, auth_date, hash. Для проверки подлинности этот объект использовать нельзя.

window.WebApp.platform сообщает, откуда запущено приложение: ios, android, desktop или web. Это важно, потому что часть методов работает не везде:

Метод или объект	Что делает	Ограничения по документации
`requestContact()`	запрашивает номер телефона в окне клиента MAX	не указаны
`openLink(url)`	открывает ссылку во внешнем браузере	не указаны
`openMaxLink(url)`	открывает ссылку `https://max.ru/…` внутри MAX	не указаны
`downloadFile(url, file_name)`	скачивает файл по `https`	в браузере вне MAX
`shareContent(params)`	нативный экран «Поделиться» на iOS и Android	в веб-версии
`shareMaxContent(params)`	экран «Поделиться» внутри MAX	не указаны
`openCodeReader()`	сканирует QR-код камерой или из файла	не указаны
`BackButton`	управляет кнопкой Назад в шапке	не указаны
`DeviceStorage`	хранит данные на устройстве	в веб-версии
`SecureStorage`	зашифрованное хранилище, до 10 ключей на пользователя у бота	в веб-версии
`BiometricManager`	биометрическая аутентификация	на десктопе и в веб-версии
`HapticFeedback`	тактильные отклики	на десктопе и в веб-версии
`NfcManager`	работа с NFC	везде, кроме Android

Перед openLink, downloadFile и shareMaxContent MAX Bridge проверяет, что пользователь кликнул в мини-приложении: без клика действие не выполнится. Скачивание через href не поддерживается. Номер телефона, полученный через requestContact(), можно использовать только для работы с текущим мини-приложением — например, для программы лояльности или статуса заказа. Метод getLaunchContext() сообщает, откуда запущено приложение — из нижней панели вкладок, списка чатов, экрана чата или настроек; он работает на Android с версии 26.19.2 и на iOS с 26.20.0. Как пользоваться десктопной и веб-версией мессенджера — в статье «MAX на компьютере».

Для интерфейса есть библиотека React-компонентов MAX UI и гайдлайн в формате .FIG с принципами навигации, типографики и примерами мини-приложений.

Диплинки и стартовые параметры

Диплинк мини-приложения — https://max.ru/<botName>?startapp=<payload>. Параметр payload — до 512 символов: латинские буквы, цифры, подчёркивание и дефис. Если он длиннее или содержит другие символы, его удалят. Внутри приложения значение доступно в window.WebApp.initDataUnsafe.start_param.

Так пользователя ведут с сайта или из рассылки сразу в нужный экран: QR-код на чеке открывает форму отзыва о ресторане, ссылка в рассылке — промокод, ссылка на сайте — статус заказа по его номеру, а разные ссылки на внешних площадках показывают, откуда пришёл человек. Конфиденциальные данные в payload открытым текстом не передают — только одноразовые токены или закодированные идентификаторы сессии.

Отдельный диплинк https://max.ru/:share?text=<текст> открывает экран «Отправить в MAX»: пользователь выбирает чат или канал, и текст подставляется в сообщение. Он работает на iOS, Android и в веб-версии, на десктопе поддержка в разработке; параметр text нужно URL-кодировать. Файлы, фото и видео мини-приложение пересылает иначе: бот отправляет их сообщением, а приложение вызывает shareMaxContent({ mid, chatType }) с идентификатором этого сообщения. Как отправляют файлы сами пользователи — в статье «Как отправить файл в MAX».

Как проверить данные запуска

MAX передаёт мини-приложению стартовые параметры при каждом запуске. Чтобы убедиться, что данные принадлежат реальному пользователю и не изменены, их проверяют на сервере:

Возьмите параметр WebAppData из фрагмента URL после # и раскодируйте его один раз: в URL он закодирован целиком, & внутри записан как %26. Проще всего так: new URLSearchParams(location.hash.slice(1)).get('WebAppData'). Те же данные доступны в window.WebApp.initData.
Разбейте его по & на пары key=value, сохраните значение hash и исключите его.
URL-декодируйте значения, отсортируйте пары по ключам от a до z и соедините через перевод строки — получится launch_params.
Вычислите secret_key = HMAC_SHA256("WebAppData", токен бота) — строка WebAppData служит ключом.
Вычислите hex(HMAC_SHA256(secret_key, launch_params)) и сравните с hash: совпали — данные подлинные, нет — изменены.

auth_date приходит в Unix-времени в секундах; документация рекомендует считать данные устаревшими через 1 час. Примеры проверки на странице документации даны на TypeScript, Python, Go и Java. Идентификатор чата мини-приложение получает на клиенте из initData или через подписку бота на события.

Правила для мини-приложений

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

сообщать пользователям юридически обязательную информацию — о правообладателе, операторе, контактах, возрастной классификации, политику обработки персональных данных и условия использования;
поддерживать пользователей по всем вопросам работы приложения;
защищать данные и запросы от подмены, дублирования и накрутки, а приложение — от вредоносного кода;
корректно обрабатывать ошибки и отказ пользователя дать разрешение.

Частые вопросы

Можно ли подключить мини-приложение без бота? Нет, мини-приложения запускаются и работают только через чат-бота.

Можно ли открыть два мини-приложения сразу? Нет: при открытии нового текущее закрывается.

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

Как скачать файл, если MAX Bridge недоступен? Документация даёт запасной способ: загрузить файл через fetch, превратить в Blob и скачать через временную ссылку — это работает, если у файла открыт CORS.

Данные о каналах MAX для вашего мини-приложения

Если мини-приложению или его боту нужны данные о каналах MAX — поиск, категории, тренды роста, — у каталога gosmax.ru есть открытые JSON-эндпоинты без ключей и датасет-экспорт; на сайте те же данные — в разделе категорий. Ряд подписчиков по нашему замеру max.ru отдаёт GET /api/v1/history с ключом X-Api-Key на тарифе Business (тарифы); CORS не настроен, поэтому данные забирает ваш сервер, а не браузер пользователя. Описание — на странице API каталога, тестовый ключ — через форму «Тестовый ключ к API».

Источники

Страницы документации для разработчиков MAX и справки MAX, по которым собрана статья:

Как мы это проверили

Документацию dev.max.ru — разделы /docs, /docs-api и FAQ, 93 страницы — мы выгрузили 26 сентября 2026 года, справку help.max.ru — 24 сентября, и сверили с ними каждый шаг и каждое ограничение. Общего каталога мини-приложений в MAX документация не описывает, поэтому в статье его нет. Как устроен наш каталог, описано в методологии и на странице о проекте.

Мини-приложения в MAX: как открыть и как подключить своё