Мини-приложения в MAX: Руководство для разработчиков

Подключение к платформе MAX для партнёров и её сервисам — чат-ботам, мини-приложениям, каналам — доступно для юрлиц и ИП, которые являются резидентами РФ

Мини-приложения работают только внутри MAX и не могут существовать автономно. Они расширяют функциональность основной платформы и позволяют разработчикам быстро запускать проекты

Что потребуется

• Устройства с операционной системой Windows, macOS или Linux
• Мобильное устройство для регистрации профиля в MAX
• Редактор кода и навыки работы с командной строкой

Что упростит разработку

• Библиотека MAX Bridge, с которой мини-приложение сможет взаимодействовать с API MAX и API устройства пользователя
• Библиотека React-компонентов MAX UI, с которой мини-приложение легко стилизовать под интерфейс MAX
• Мини-приложения работают на базе стандартных веб-технологий — HTML, JavaScript, CSS

Перед подключением

• Загрузите файлы мини-приложения на хостинг статики, например, через Vercel или GitHub Pages — .html, .css, .js и другие медиафайлы
• Проверьте, что приложение работает по защищённому соединению — https

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

1. Откройте платформу MAX для партнёров, зайдите в профиль организации → перейдите в раздел «Чат-боты».
2. Если у вас несколько ботов, в панели управления ботом нажмите на имя текущего бота и выберите нужный из списка.
3. Перейдите в раздел «Чат-бот и мини-приложение» → «Настроить».
4. Вставьте URL мини-приложения в поле для ссылки.
5. Выберите вид кнопки открытия мини-приложения («Открыть», «Старт», «Играть» или без названия) и нажмите «Сохранить».

Требования к URL мини-приложения:

• Длина: не более 1024 символов
• Протокол: только https://
• Допустимые символы: буквы (латиница), цифры, точка (.) и дефис (-)
• Пробелы не поддерживаются
• URL должен быть валидный

Настройка бота и мини-приложения

Как только вы подключите мини-приложение к платформе, в чате с его ботом появится заметная кнопка для быстрого запуска сервиса

Запуск мини-приложения из чата с ботом

Как работать с диплинками

Диплинки (deep links) — это специальные ссылки, которые позволяют открывать приложения MAX с передачей дополнительных параметров. С их помощью можно передавать контекстную информацию, отслеживать источники переходов или автоматически выполнять определённые действия при запуске

Создание диплинка приложения

Чтобы создать диплинк мини-приложения, используйте следующий формат ссылки:

Код

Скопировать

https://max.ru/<botName>?startapp=<payload>

Где:

• <botName> — имя бота, к которому привязано мини-приложение
• <payload> — необязательный параметр с дополнительными данными (до 512 символов)

Примеры

Базовая ссылка без параметров

Код

Скопировать

https://max.ru/MyShopBot?startapp

Ссылка с параметрами

Код

Скопировать

https://max.ru/MyShopBot?startapp=promo_summer2025

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

Код

Скопировать

https://max.ru/MyShopBot?startapp=ref_user123_campaign_sale

Payload в приложении

При работе с payload для мини-приложений обратите внимание на допустимые символы:

• Латинские буквы: A-Z, a-z
• Цифры: 0-9
• Специальные символы: _ (подчёркивание), - (дефис)

Если payload превышает 512 символов или содержит недопустимые символы, он будет удалён из URL-ответа

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

После подключения библиотеки MAX Bridge мини-приложение получает доступ к глобальному объекту window.WebApp, который содержит стартовые параметры

Переданные параметры доступны через:

• initDataUnsafe.start_param — объект WebAppStartParam с данными из URL
• initData — строка, которая содержит все стартовые параметры в текстовом формате

Диплинк для шеринга контента

Диплинк :share доступен на iOS, Android и в веб-версии. Поддержка диплинка на десктопе — в разработке

Диплинк :share открывает экран «Отправить в MAX» и позволяет пользователю поделиться заранее подготовленным контентом в выбранном чате или канале приложения MAX

Код

Скопировать

https://max.ru/:share?text=<текст сообщения>

Как это работает

1. При открытии диплинка отображается экран выбора чата или канала в MAX
2. Пользователь выбирает, куда отправить сообщение
3. После выбора приложение подставляет значение text в сообщение и предлагает отправить его

Применяйте URL encoding для параметра text, особенно если текст содержит пробелы, переносы строк, спецсимволы или эмодзи

Примеры

Простой текст

Код

Скопировать

https://max.ru/:share?text=Привет

Текст с пробелами (URL-encoded)

Код

Скопировать

https://max.ru/:share?text=Привет%20мир

Ссылка в тексте

Код

Скопировать

https://max.ru/:share?text=https%3A%2F%2Fexample.com

Сообщение с эмодзи (URL-encoded)

Код

Скопировать

https://max.ru/:share?text=%F0%9F%9A%80%20MAX%20%D1%80%D1%83%D0%BB%D0%B8%D1%82

Шеринг контента из мини-приложения через бота

В мини-приложении предусмотрена возможность делиться контентом — изображениями, видео, файлами и другими медиа — в диалогах и групповых чатах MAX. Для этого используйте метод shareMaxContent(). Шеринг медиа работает как пересылка сообщения, поэтому поддерживается любой тип контента

Как это работает

1. Бот отправляет контент пользователю через POST /messages — например, медиафайл или открытку
2. Мини-приложение получает идентификатор этого сообщения (mid)
3. Мини-приложение вызывает shareMaxContent({ mid, chatType }), где:
   • mid — идентификатор сообщения от бота
   • chatType — тип чата: DIALOG (диалог) или CHAT (групповой чат)
4. Пользователь выбирает, куда отправить контент — сообщение пересылается в выбранный чат

Если при шеринге медиа передать text или link, они будут проигнорированы. Передавайте либо text / link, либо mid и chatType

Подробнее о параметрах — в описании метода shareMaxContent()

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

Обновление ссылки на приложение

Если ссылка поменялась, самостоятельно обновите её на платформе MAX для партнёров: зайдите в профиль организации → перейдите в раздел Чат-боты → Чат-бот и мини-приложение → Настроить → в поле с URL обновите ссылку → нажмите Сохранить

Изменение кнопки открытия приложения

Чтобы изменить кнопку открытия, в платформе MAX для партнёров зайдите в профиль организации → перейдите в раздел Чат-боты → Чат-бот и мини-приложение → Настроить → выберите нужный вид кнопки → нажмите Сохранить

Удаление приложения

Если вы хотите удалить мини-приложение, в платформе MAX для партнёров зайдите в профиль организации → перейдите в раздел Чат-боты → Чат-бот и мини-приложение → Настроить → в поле с URL удалите ссылку на мини-приложение → нажмите Сохранить

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

Каждое мини-приложение можно открыть внутри MAX по ссылке вида: https://max.ru/<botName>?startapp

После ключа ?startapp в ссылку можно добавить стартовые параметры. Они будут переданы мини-приложению в поле start_param и в GET-параметре WebAppStartParam

Подробнее о стартовых параметрах читайте в разделе WebAppStartParam

Вернуться к выбору сервисов для интеграции

Если у вас возникли вопросы, посмотрите раздел с ответами