Мини-приложение в MAX — это обычный веб-интерфейс на HTML, CSS и JavaScript, который открывается внутри мессенджера и работает только через чат-бота: отдельно от бота оно существовать не может [MAX для разработчиков, дата проверки 08.10.2026]. Ниже — порядок действий от профиля до кнопки запуска и то, что мы проверили на своём демо-каталоге недвижимости. Все данные в демо вымышленные.
Что такое мини-приложение и чем оно отличается от бота
Бот общается кнопками и текстом, а мини-приложение показывает полноценный экран: каталог, форму, калькулятор, личный кабинет. Приложение запускается из чата с ботом, а бот остаётся его «входом» и привязан к нему в настройках.
Технически это сайт, который вы размещаете на своём хостинге. Документация MAX называет примеры хостинга (VK Cloud, GitHub Pages, Yandex Cloud) и требует защищённое соединение по https. Для связи с мессенджером подключается библиотека MAX Bridge, а интерфейс можно стилизовать компонентами MAX UI.
Для примера возьмём наш демо-каталог объектов: в нём вымышленные данные, а устройство такое же, как у любого каталога или калькулятора.
Что нужно до старта и как подготовить приложение
Подключение к платформе «MAX для партнёров» и её сервисам (чат-боты, мини-приложения, каналы) доступно юрлицам, ИП и самозанятым, которые являются резидентами РФ. Физлица и нерезиденты верификацию пока пройти не могут [dev.max.ru, подключение к платформе, 08.10.2026]. Профиль подтверждается через Госуслуги, а для организаций и ИП в веб-версии ещё и через банковские сервисы. Сам бот создаётся после подключения к платформе.
Для приложения нужно три вещи:
- Адрес по
https. Длина не больше 1024 символов, допустимы латинские буквы, цифры, точка и дефис, пробелы не поддерживаются. - Скрипт MAX Bridge:
<script src="https://st.max.ru/js/max-web-app.js"></script>. После подключения доступен глобальный объектwindow.WebAppбез отдельной инициализации. - Адаптация под телефон. В нашем случае поля ввода сделаны шрифтом 16 px, чтобы окно мессенджера и мобильные браузеры не увеличивали масштаб при фокусе на поле. Это практика нашей команды, а не требование MAX.
Что даёт библиотека MAX Bridge, когда приложение уже открыто. По документации она отдаёт данные запуска (initData, platform со значениями ios, android, desktop, web, версию клиента), размер доступной области getViewportSize() и управление кнопкой «Назад» через BackButton. Ссылку во внешнем браузере открывает openLink(url), а диплинк max.ru внутри MAX — openMaxLink(url). Оба метода срабатывают только после клика пользователя в приложении.
Скачивание файла тоже имеет условия: нужен https, клик пользователя и запуск внутри мессенджера, а не в браузере. Ссылка с атрибутом href для скачивания не поддерживается, используется метод downloadFile(url, file_name). Номер телефона приложение запрашивает методом requestContact() в окне клиента MAX: пользователь может отказаться, и в этом случае придёт код ошибки. Учитывайте это в сценарии формы.
Как подключить приложение к боту
Шаги совпадают в веб-версии платформы и в мини-приложении «MAX для бизнеса» [dev.max.ru, подключение мини-приложения, 08.10.2026]:
- Откройте платформу MAX для партнёров, перейдите в раздел «Чат-боты» и нажмите «Перейти».
- Выберите нужного бота и нажмите «⋮», затем «Настройки».
- Вставьте адрес мини-приложения в поле для ссылки.
- Выберите вид кнопки открытия (по документации это «Открыть», «Старт», «Играть» или кнопка без названия) и нажмите «Сохранить».
После сохранения в чате с ботом появляется заметная кнопка запуска приложения.
Рядом с настройками в карточке бота есть раздел «Основная информация»: он нужен для описания бота, а адрес приложения указывается именно в «Настройках».
Адрес можно менять самостоятельно: в тех же «Настройках» обновите ссылку и сохраните. Чтобы удалить приложение, очистите поле и сохраните. Внутри MAX приложение открывается и по прямой ссылке вида https://max.ru/<имя бота>?startapp. После ?startapp можно передать стартовый параметр до 512 символов (латинские буквы, цифры, _ и -): приложение получит его в initDataUnsafe.start_param. Не передавайте в нём конфиденциальные данные.
В нашем случае: модерация и кнопка запуска
В нашем случае 06.10.2026 мы отправили адрес приложения на проверку около 22:33 (статус «на модерации»), а около 23:00 приложение открылось на телефоне. Это единичное наблюдение, а не срок и не гарантия: в разделе документации о подключении мини-приложения срок проверки не указан.
Повторная проверка тоже случается. По нашему опыту, после изменений в разделе «Основная информация» бот снова проходит модерацию. В документации раздела о подключении мини-приложения мы этого правила не нашли, поэтому закладывайте время на проверку и не вносите правки в бота перед важным показом.
В боте MAX кнопка запуска создана через библиотеку maxapi. Рабочий фрагмент нашего демо-бота без токенов:
```python from maxapi.types.attachments.buttons.open_app_button import OpenAppButton
OpenAppButton(text='Перейти к демо', web_app='id<ИНН>_bot') ```
В параметр web_app мы передаём имя бота, к которому привязано приложение (в примере вместо реального имени стоит заглушка). Кнопка вставляется в клавиатуру сообщения так же, как остальные.
Одно приложение на бота — следствие устройства настроек: в них одно поле для ссылки. Как показать несколько демо? Мы сделали общий вход на отдельном адресе (хаб с шестью плитками) и передаём стартовый параметр в ссылке: ?startapp=<код демо>. Мы проверили такие ссылки для всех шести демо. Второй вариант — отдельный бот на каждое демо.
Ещё одна практическая деталь связана с кэшем. В нашем случае Telegram долго показывал старую версию страниц, потому что HTML кэшировался на час. Мы отключили кэш для HTML и стали добавлять версию в имя файлов стилей и скриптов (например, home.v3.css). Так правки видны сразу после выкладки, а не через час.
Ограничения, Telegram и что проверить
Telegram устроен иначе: там Mini App запускается из кнопки с типом web_app, из кнопки меню, из профиля бота или по прямой ссылке https://t.me/<бот>/<приложение>, а ограничения «одно приложение на бота» в описании способов запуска нет. В нашем боте кнопка Telegram открывает адрес хаба.
| Параметр | MAX | Telegram |
|---|---|---|
| Где задаётся адрес | «MAX для партнёров», настройки бота | Кнопка бота или BotFather |
| Скрипт для связи | max-web-app.js, объект window.WebApp | telegram-web-app.js, объект Telegram.WebApp |
| Прямая ссылка | max.ru/имя бота?startapp | t.me/бот?startapp или t.me/бот/приложение |
| Стартовый параметр | start_param, до 512 символов | start_param (параметр startapp) |
| Внешняя ссылка | openLink открывает внешний браузер | openLink открывает внешний браузер |
Источник: dev.max.ru, документация MAX Bridge и подключения мини-приложения; core.telegram.org/bots/webapps, дата проверки 08.10.2026.
В таблице видно: логика одна и та же, различаются места настройки и названия объектов.
Типичные ошибки, которые прямо следуют из правил документации:
- Адрес с
http://или с пробелом, подчёркиванием и другими символами вне списка «латиница, цифры, точка, дефис» не подойдёт. - Стартовый параметр длиннее 512 символов или с недопустимым символом MAX удаляет из ссылки, и приложение получит пустое значение.
- Секретные данные в
startappпопадают в ссылку в открытом виде. Передавайте короткий код или одноразовый токен. - Метод
openLinkилиdownloadFile, вызванный без клика пользователя, ничего не сделает. - Приложение без бота не существует: сначала бот, потом адрес в его настройках.
Эти пункты мы сверили с документацией 08.10.2026. Прежде чем публиковать своё приложение, пройдите их по списку.
Что проверить перед запуском:
- Адрес открывается по
httpsи подходит под правила символов. - Приложение читается на узком экране и не увеличивает масштаб при вводе в поле.
- Кнопка запуска открывает приложение внутри MAX, а не как страницу в браузере.
- Скрипт Telegram (telegram.org) может быть недоступен у части пользователей без VPN: в нашем случае он подключается только внутри Telegram.
- Служебные строки в консоли Telegram чаще всего штатный вывод, а не ошибка.
Что дальше
Чтобы убедиться, что всё работает, пройдите короткий тест на телефоне. Откройте чат с ботом, нажмите кнопку запуска и проверьте, что приложение открылось внутри MAX, а не в браузере. Затем перейдите по прямой ссылке с ?startapp и убедитесь, что стартовый параметр дошёл до приложения. В конце нажмите «Назад» и проверьте, что возврат в чат работает так, как вы задумали.
Если нужен каталог, калькулятор или запись в мессенджере для агентства, откройте демо и посмотрите, как это работает на вымышленных данных: Открыть демо каталога. Пилот можно обсудить на странице: Обсудить пилот для агентства.