для разработчиковdev

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Код
Скопировать
https://max.ru/<botName>?startapp=<payload>

Где:

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

Код
Скопировать
https://max.ru/MyShopBot?startapp

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

Код
Скопировать
https://max.ru/MyShopBot?startapp=promo_summer2025

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

Код
Скопировать
https://max.ru/MyShopBot?startapp=ref_user123_campaign_sale

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

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

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

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

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

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

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

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

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

Код
Скопировать
https://max.ru/:share?text=<текст сообщения>
ПараметрТипОбязательностьОписание
textstringДаТекст, который пользователь отправит в выбранный чат. Может содержать ссылки и любые символы

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

  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

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

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