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

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

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

## Что упростит разработку
- [Библиотека MAX Bridge](/docs/webapps/bridge), с которой мини-приложение сможет взаимодействовать с API MAX и API устройства пользователя
- [Библиотека React-компонентов MAX UI](/ui), с которой мини-приложение легко стилизовать под интерфейс MAX
- Гайдлайн с основными принципами устройства интерфейса, навигации и типографики, а также примерами мини-приложений — можно скачать в формате `.FIG` по [ссылке](https://github.com/max-messenger/max-ui/blob/main/MAXUI-Figma.fig)
- Мини-приложения работают на базе стандартных веб-технологий — HTML, JavaScript, CSS

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

- Загрузите файлы мини-приложения — `.html`, `.css`, `.js` и необходимые медиафайлы на хостинг, например, [VK Cloud](https://cloud.vk.com/promopage/max-mini-app/), [GitHub Pages](https://docs.github.com/ru/pages) или [Yandex Cloud](https://yandex.cloud/ru) В рамках интеграции с МАХ платформа VK Cloud запустила [хостинг мини-приложений](https://cloud.vk.com/promopage/max-mini-app/). Теперь компании могут быстро разворачивать мини-приложения благодаря готовой инфраструктуре, а их трафик будет защищён
- Убедитесь, что приложение работает по защищённому соединению — `https`

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

Помимо использования веб-версии [платформы MAX для партнёров](https://business.max.ru/self), добавить мини-приложение можно с помощью [мини-приложения «MAX для бизнеса»](https://max.ru/business_bot?startapp)

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

1. Откройте [платформу MAX для партнёров](https://business.max.ru/self), перейдите в раздел **Чат-боты** → **Перейти**
2. Выберите необходимого бота и нажмите **⋮** → **Настройки**
3. В разделе **Настройки** вставьте URL мини-приложения в поле для ссылки
4. Выберите вид кнопки открытия мини-приложения — **Открыть**, **Старт**, **Играть** или без названия — и нажмите **Сохранить**

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

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

![Запуск мини-приложения из чата с ботом](/assets/miniapp_launch_{theme}.png)
_Запуск мини-приложения из чата с ботом_

## Работа с диплинками

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

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

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

```
https://max.ru/?startapp=
```
Где:
- `` — имя бота, к которому привязано мини-приложение
- `` — необязательный параметр с дополнительными данными (до 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`](/docs/webapps/bridge), который содержит стартовые параметры

Переданные параметры доступны через:
- **`initDataUnsafe.start_param`** — объект [WebAppStartParam](/docs/webapps/bridge) с данными из URL
- **`initData`** — строка, которая содержит все стартовые параметры в текстовом формате

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

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

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

```
https://max.ru/:share?text=
```

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

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

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`](/docs-api/methods/POST/messages) — например, медиафайл или открытку
2. Мини-приложение получает идентификатор этого сообщения (`mid`)
3. Мини-приложение вызывает `shareMaxContent({ mid, chatType })`, где:
    - `mid` — идентификатор сообщения от бота
    - `chatType` — тип чата: `DIALOG` (диалог) или `CHAT` (групповой чат)
4. Пользователь выбирает, куда отправить контент — сообщение пересылается в выбранный чат

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

Подробнее о параметрах — в описании метода [`shareMaxContent()`](/docs/webapps/bridge#Шеринг%20контента)

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

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

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

1. Вы формируете диплинк вида `https://max.ru/?startapp=` для перехода в мини-приложение, передав в `payload` необходимые стартовые параметры. Убедитесь, что длина `payload` не превышает 512 символов и использованы [допустимые символы](#Payload%20в%20приложении)
2. Вы добавляете в приложение или на лендинг кнопку с диплинком
3. Пользователь переходит по диплинку и запускает мини-приложение
4. Мини-приложение через [window.WebApp.initDataUnsafe.start_param](/docs/webapps/bridge#Работа%20с%20данными%20инициализации) обрабатывает стартовые параметры запуска, такие как `payload`
5. Мини-приложение открывается и отображает пользователю информацию по заданным параметрам без запуска самого бота

Не передавайте в `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 для партнёров](https://business.max.ru/self):

1. Перейдите на [платформу](https://business.max.ru/self) в раздел **Чат-боты**
2. Выберите необходимого бота и нажмите **⋮** → **Настройки**
3. В поле с URL обновите ссылку и нажмите **Сохранить**

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

Чтобы изменить кнопку открытия, на [платформе MAX для партнёров](https://business.max.ru/self):

1. Перейдите на [платформу](https://business.max.ru/self) в раздел **Чат-боты**
2. Выберите необходимого бота и нажмите **⋮** → **Настройки**
3. Выберите нужный вид кнопки и нажмите **Сохранить**

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

Если вы хотите удалить мини-приложение:

1. Перейдите на [платформу](https://business.max.ru/self) в раздел **Чат-боты**
2. Выберите необходимого бота и нажмите **⋮** → **Настройки**
3. В поле с URL удалите ссылку на мини-приложение и нажмите **Сохранить**

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

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

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

Подробнее о стартовых параметрах читайте в разделе [`WebAppStartParam`](/docs/webapps/bridge)

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

 Если у вас возникли вопросы, [посмотрите раздел с ответами](/help)