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

FAQ

Если у вас возникли вопросы, посмотрите раздел с ответами — мы постарались собрать здесь максимум информации

Общее

Кто может подключиться к платформе MAX для партнёров?

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

Чтобы подключиться, ваша организации должна быть зарегистрирована в РФ и оформлена как юрлицо или ИП. Самозанятые, физические лица и нерезиденты пока не смогут авторизоваться или зарегистрироваться на платформе

Как изменить способ подтверждения профиля бизнеса (организации)?

Откройте личный кабинет профиля бизнеса
В разделе Способы подтверждения наведите курсор на подключённый способ
Нажмите Отключить
После отключения выберите новый способ подтверждения и нажмите Подключить

Что делать, если при подтверждении профиля бизнеса через банк или Госуслуги появляется ошибка «Не удалось подключиться...»

Такая ошибка может возникнуть, если:

В браузере запрещены всплывающие окна — откройте настройки браузера и снимите запрет
Вы подтверждаете профиль бизнеса через мобильное приложение — попробуйте подтвердить в браузере

Чат-боты

Как создать бота?
Чат-бот создаётся при подключении к платформе MAX для партнёров. Для одной организации доступно создание 5 ботов. После успешной модерации бот становится доступным для ваших пользователей, а вы можете доработать его под свой сценарий

Без разработки
Доработайте бота по шаблонам конструкторов — подробнее об этом в разделе «Бот без разработки» — или воспользуйтесь услугами наших партнёров. Они соберут бота для проекта любой сложности и помогут подключить его к приложению
С разработкой
Доработайте бота самостоятельно — подробнее об этом в разделе «Бот с разработкой»

Если планируете разработку на TypeScript или JavaScript, воспользуйтесь разделами «Библиотека JavaScript», «Библиотека Golang»

Как управлять ботом в MAX?
После успешной проверки чат-бота в разделе Чат-бот и мини-приложение появится токен — уникальный идентификатор бота, с помощью которого он будет взаимодействовать с API ботов. Наличие токена означает, что бот зарегистрирован на платформе MAX для партнёров

Как изменить имя, аватар, описание и другие настройки бота?
Изменить пока можно только название, аватар и описание бота:

Перейдите на платформу MAX для партнёров
Если у вас несколько ботов, в левом верхнем углу выберите нужный
Справа нажмите на значок настроек
Внесите изменения и нажмите Сохранить — бот будет отправлен на повторную модерацию

Есть ли ограничения для ника и имени бота?
Ник генерируется автоматически по шаблону idИНН_bot. Выбрать или изменить его пока нельзя. Когда такая возможность появится, обратите внимание на требования к нику:

Должен начинаться с маленькой буквы, без @
Должен заканчиваться на «_bot» или «bot». Если не указать, к введённому вами имени бота автоматически будет добавлено «_bot»
Длина: 11 — 60 символов, включая «_bot» / «bot»
Допустимые символы: латиница, цифры и _

Как посмотреть токен бота?

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

Как обновить токен бота

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

Как удалить бота?

После удаления ваши клиенты не смогут пользоваться ботом. Удалённого бота нельзя восстановить

Чтобы удалить:

Перейдите на платформу MAX для партнёров
Если у вас несколько ботов, в левом верхнем углу выберите нужный
Справа нажмите на значок настроек
Нажмите Удалить бота и подтвердите удаление

Можно ли поменять владельца бота?
Поменять владельца или передать права на управление ботом пока нельзя

Где я могу найти примеры кода?
Ищите примеры кода в разделе «Библиотека MAX Bot API» или в репозитории на GitHub. Используйте нашу официальную библиотеку, если пишете ботов на TypeScript или JavaScript

Можно ли сделать непубличного бота?
В настоящее время пользователи могут найти любого бота в MAX по ссылке или по нику через поиск приложения

Есть ли у чат-ботов в MAX команды по умолчанию, предзаданные платформой?
Нет, разработчики могут самостоятельно задавать любые команды ботов

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

Можно ли форматировать текст в сообщениях бота?
Можно. Платформа поддерживает два типа форматирования — Markdown и HTML. Чтобы выделить информацию в сообщениях бота, например, жирным шрифтом или курсивом, отправьте параметр запроса format (enum TextFormat Nullable) — текст будет отформатирован в соответствии с указанной разметкой

События

Как получать события?
MAX поддерживает два метода получения обновлений о действиях в чат-боте — через Webhook и Long Polling. Использовать одновременно их нельзя — выберите один из типов
Входящие уведомления могут храниться на сервере до 8 часов
Чтобы подключить уведомления, отправьте к API POST-запрос /subscriptions с URL, на который хотите получать уведомления

Чтобы получать события одним из методов, используйтн GET-запросы /updates для Long polling или /subscriptions для Webhook-подписок

Чем Long Polling отличается от Webhook-подписок, и какой метод выбрать?
Long polling и Webhook отличаются способом взаимодействия с сервером и продолжительностью отклика. Webhook после новых действий в чат-боте сам отправляет запрос на сервер, а Long Polling делает периодические запросы без триггера в боте

Выбор метода зависит от масштабов проекта. Webhook может обеспечить более эффективную обработку сообщений при высокой нагрузке, когда важна мгновенная реакция на события. Long polling — проще в настройке и подойдёт для небольших задач, в которых нет повышенных требований ко времени ответа на запрос

Какие преимущества и недостатки у метода Long Polling?
Long Polling не требует внешнего сервера с защищённым соединением https и статичного IP. Бот будет самостоятельно отправлять запросы на сервер и ждать ответа о новых сообщениях

Метод малоэффективен при высокой интенсивности обновлений. Задержка ответов из-за ожиданий и таймаутов может привести к накоплению очереди открытых соединений, которые будут создавать дополнительную нагрузку на сервер MAX и требовать дополнительных настроек

Какие преимущества и недостатки у Webhook-подписок?
Webhook-подписки позволяют мгновенно получать уведомления о действиях в боте, не нагружая сервер MAX периодическими опросами — обновления приходят автоматически с появлением новых данных

Чтобы работать с Webhook, необходимо настроить публичный сервер с защищённым соединением https и статичным IP-адресом. Метод эффективен при высокой интенсивности обновлений, но полностью зависит от доступности сервера и потребует защиты данных

Почему не приходят уведомления Webhook?
Webhook не может присылать уведомления, если не работает сервер бота или есть проблемы с сетью

Мини-приложения

Можно ли добавить мини-приложение в MAX без чат-бота?
Нет, подключить дополнительные сервисы к MAX, управлять ими и запускать можно только с помощью чат-бота. Через него мини-приложения взаимодействуют с API ботов

Как подключить мини-приложение к MAX?

Перейдите в личный кабинет организации на платформе MAX для партнёров
Перейдите в раздел Чат-бот и мини-приложение
В поле Мини-приложение вставьте URL и нажмите Сохранить

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

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

Подробнее об интеграции мини-приложений — в разделе «Как добавить мини-приложение в MAX»

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

Есть ли ограничения на контент для мини-приложений?
Ограничения есть. Внимательно изучите Правила платформы перед размещением мини-приложения в MAX и убедитесь, что оно безопасно для пользователей и соответствует требованиям к содержанию и функциональности

Можно ли открыть несколько мини-приложений одновременно?
Нет, при открытии нового мини-приложения текущее закроется. Мы работаем над поддержкой одновременной работы нескольких мини-приложений

В чём разница между функциями openLink и openMaxLink?
openLink откроет любую ссылку во внешнем браузере. openMaxLink откроет только ссылку на мини-приложение вида https://max.ru/<botName>?startapp внутри приложения MAX — в новой шторке, без перехода во внешний браузер

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

Что такое диплинки в MAX?
Диплинки (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 для мини-приложений?
Допустимые символы:

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

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

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

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

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

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

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

Подробнее о структуре данных см. в разделе WebAppData и WebAppStartParam документации MAX Bridge

Диплинки для чат-бота

Как создать диплинк для чат-бота?

Используйте следующий формат ссылки:

Код

Скопировать

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

Где:

<botName> — ник бота
<payload> — дополнительные данные (до 128 символов)

Если payload превышает 128 символов, он не будет передан боту

Примеры:
Базовая ссылка:

Код

Скопировать

https://max.ru/SupportBot?start=123

Реферальная ссылка:

Код

Скопировать

https://max.ru/MyBot?start=ref_user456789

Отслеживание источника:

Код

Скопировать

https://max.ru/NewsBot?start=source_instagram

Payload в чат-боте

Как получить payload в чат-боте?

Когда пользователь переходит по диплинку, бот получает обновление типа bot_started через webhook или long polling:

Код

Скопировать

{
    "update_type": "bot_started",
    "timestamp": 1573226679188,
    "chat_id": 1234567890,
    "user": {
        "user_id": 1234567890,
        "name": "Иван",
        "username": "ivan_petrov"
    },
    "payload": "promo_summer2025"
}

Ключевые поля в update:

update_type — всегда "bot_started" при запуске бота через диплинк
payload — переданное значение из URL (может быть null, если параметр не указан)
user — информация о пользователе, который запустил бота
chat_id — ID чата

Требования к поддержке диплинков

Какие версии клиентов MAX поддерживают диплинки?

Механизм диплинков поддерживается в следующих версиях клиентов MAX:

iOS: версия 2.7.0 и выше
Android: версия 2.9.0 и выше

Что нужно настроить в боте для получения payload?

Для получения обновлений с payload бот должен использовать один из следующих вариантов:

WebHook — настроить подписку через метод POST /subscriptions
Long Polling — получать обновления через метод GET /updates

При настройке WebHook убедитесь, что в параметре update_types включён тип "bot_started"

Можно ли передать несколько параметров в payload?

Да, но их нужно закодировать в одну строку. Например:

Код

Скопировать

?start=param1_value1_param2_value2

Каналы

Как создать канал

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

Дополнительно, если у вас есть ресурс с меткой А+ в одном из сервисов — ВКонтакте, Дзен, Одноклассники или Telegram, — вы можете создать в MAX каналы с такими же названиями и никами через бота Каналы в МАХ. Ограничений на количество таких каналов нет

Перед созданием канала через платформу потребуется зарегистрироваться на платформе и верифицировать организацию. Обратите внимание, что профиль в MAX должен быть создан на тот же номер телефона, что вы использовали при регистрации на платформе

Чтобы создать канал через платформу:

Откройте платформу
Перейдите в Каналы → Создать канал
Отсканируйте QR-код или нажмите кнопку — вы перейдёте в бота для создания каналов Каналы в MAX для бизнеса
Нажмите Начать, затем выберите Создать канал
Поделитесь номером телефона
Дождитесь обработки заявки — вам придёт уведомление
Введите название канала
Получите название и автогенерированный ник idИНН_biz
Нажмите Создать канал. Готово!

Как создать канал, если уже есть ресурсы с меткой А+ на других платформах
Обратите внимание, что профиль в MAX должен быть создан на тот же номер телефона, что вы использовали для регистрации ресурса с меткой А+ в Роскомнадзоре

Перейдите в чат-бот Каналы в MAX: @channel_bot → Начать
Нажмите Создать канал
Выберите платформу, где у вас есть метка А+. От этого зависят дальнейшие шаги:
- Для ВКонтакте, Одноклассники, Дзен
  1. Поделитесь номером телефона
  2. Отправьте ссылку на ваш ресурс с меткой А+
  3. Отправьте ссылку на регистрацию ресурса с меткой А+ в Роскомнадзоре. После проверки бот пришлёт вам соответствующее уведомление
  4. Нажмите Создать канал. Готово!
- Для Telegram
  1. Отправьте ссылку на регистрацию канала с меткой А+ в Роскомнадзоре — бот пришлёт вам хештег
  2. Добавьте хештег в описание канала в Telegram — после создания канала его можно будет удалить
  3. Перейдите в бот Каналы в МАХ и нажмите Проверить. После проверки бот пришлёт вам соответствующее уведомление
  4. Нажмите Создать канал. Готово!

Как изменить название, описание и аватар

Перейдите в МАХ и выберите нужный канал в списке чатов
Нажмите на название канала — так вы перейдёте в Профиль канала
Чтобы открыть настройки канала, в правом верхнем углу нажмите на значок редактирования (иконка карандаша)
Внесите необходимые изменения и сохраните их

Как удалить канал

Перейдите в МАХ и выберите нужный канал в списке чатов
Нажмите на название канала — так вы перейдёте в Профиль канала
В выпадающем списке выберите Удалить канал и подтвердите удаление

Почему заблокирован канал?
Канал может быть заблокирован, если нарушены права на товарный знак или поступили жалобы на канал, например на его публикации, тематику, название, описание

Канал заблокирован, что делать?
Обратитесь в техподдержку