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

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

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

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

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

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

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

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

Загрузите файлы мини-приложения — .html, .css, .js и необходимые медиафайлы на хостинг, например, VK Cloud, GitHub Pages или Yandex Cloud
В рамках интеграции с МАХ платформа VK Cloud запустила хостинг мини-приложений. Теперь компании могут быстро разворачивать мини-приложения благодаря готовой инфраструктуре, а их трафик будет защищён
Убедитесь, что приложение работает по защищённому соединению — https

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

Помимо использования веб-версии платформы MAX для партнёров, добавить мини-приложение можно с помощью мини-приложения «MAX для бизнеса»

Шаги добавления мини-приложения в веб-версии и с помощью мини-приложения «MAX для бизнеса» совпадают

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

Требования к 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=<текст сообщения>

Параметр	Тип	Обязательность	Описание
`text`	string	Да	Текст, который пользователь отправит в выбранный чат. Может содержать ссылки и любые символы

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

При открытии диплинка отображается экран выбора чата или канала в MAX
Пользователь выбирает, куда отправить сообщение
После выбора приложение подставляет значение 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(). Шеринг медиа работает как пересылка сообщения, поэтому поддерживается любой тип контента

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

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

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

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

Запуск мини-приложения через диплинк из внешнего приложения

Вы можете перенаправить пользователя из вашего приложения или лендинга прямо в мини-приложение MAX, передав через диплинк необходимый контекст: идентификатор пользователя, номер заказа, промокод и так далее

Как происходит перенаправление пользователя в мини-приложение по диплинку:

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

Не передавайте в payload конфиденциальные данные в открытом виде — используйте одноразовые токены или закодированные идентификаторы сессии

Примеры диплинков для перехода в мини-приложение

Сценарий	Пример диплинка	Пример использования
Обратная связь о посещении ресторана	`https://max.ru/MyBot?startapp=feedback_rest123`	Вы размещаете QR-код на чеке или на столике. Пользователь сканирует QR-код, переходит в мини-приложение ресторана по диплинку. Мини-приложение отображает окно с предложением оценить обслуживание или оставить отзыв о блюдах
Получение промокода на скидку	`https://max.ru/MyBot?startapp=promo123`	Вы добавляете ссылку для перехода в мини-приложение. Пользователь переходит в мини-приложение MAX и видит окно с приветствием и промокодом на скидку
Отслеживание источника переходов в мини-приложение	`https://max.ru/MyBot?startapp=your_site`	Вы размещаете ссылки для перехода в мини-приложение на внешних сайтах и отслеживаете статистику переходов с каждого ресурса
Отслеживание статуса заказа	`https://max.ru/MyBot?startapp=order_12345`	Вы размещаете ссылку для отслеживания заказа на сайте своего ресторана. Пользователь переходит в мини-приложение MAX по диплинку с номером заказа. Мини-приложение получает идентификатор заказа и сразу показывает актуальный статус и дополнительную информацию по доставке

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

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

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

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

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

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

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

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

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

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

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

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

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