Подготовка и настройка бота

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

Уровень сложности: продвинутый

С навыками разработки вы можете создавать чат-ботов с неограниченным потенциалом и возможностью размещать мини-приложения в MAX

Подготовка

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

Для одной организации доступно создание 5 ботов

Пользователи могут получить доступ к боту после его успешной модерации. Статус модерации отображается рядом с названием бота

Настройки бота

У бота в MAX есть следующие поля или настройки:

Имя, которое отображается в MAX в чате с вашим ботом, — задаётся при создании бота в поле Название
Аватар (фото профиля) — загружается в виде логотипа при создании бота
Ник, который отображается в публичной ссылке, например для max.ru/idИНН_bot ником является idИНН_bot. Он генерируется автоматически при создании бота по шаблону idИНН_bot
Описание для пользователя, где указано, какие задачи решает бот: что умеет, чем полезен, как связаться с его владельцем или поддержкой. Всё это указывается при создании бота в поле Описание

Настройки бота можно изменить только на платформе MAX для партнёров — отредактировать их в мессенджере MAX не получится

Вы можете изменить имя, аватар и описание. Отредактировать ник пока нельзя. При изменении настроек обратите внимание на требования к полям

Также в настройках бота на платформе вы можете запретить или разрешить добавление бота в групповой чат. По умолчанию установлен запрет

Профиль бота

Токен бота

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

При необходимости токен можно обновить. Также вы можете добавить ссылку на мини-приложение, которое хотите подключить к чат-боту

Пример токена

AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw

Токен — это прямой доступ к боту. Не рекомендуем хранить его в открытых источниках или передавать посторонним — они смогут завладеть ботом и управлять им от вашего имени. Если вы опасаетесь, что токен скомпрометирован, обновите его

Собрать сценарий для бота можно без кода, для этого есть конструкторы с набором готовых решений. Подробнее в разделе «Бот без разработки»

Отправляем API-запросы

API — это сервис, который позволяет взаимодействовать с платформой от имени бота. Бот отправляет запросы с токеном к API MAX и получает обновления с сервера в формате JSON

Передача токена через query-параметры больше не поддерживается — используйте заголовок Authorization: <token>

Вот так выглядит базовый запрос к API MAX.

Код

Скопировать

https://platform-api.max.ru/me?
Authorization: <token>

В ответ вернётся информация о боте — его имя, токен или ник

Для стабильной работы ботов убедитесь, что максимальное количество запросов в секунду на platform-api.max.ru — 30 rps

Подробнее о работе с сервером, методах и параметрах запросов читайте в разделе «API»

Если вы пишете ботов на TypeScript или JavaScript, рекомендуем использовать нашу официальную библиотеку — она содержит разные стандартные методы и утилиты. Читайте подробнее в разделе «Библиотека MAX Bot API» здесь или на GitHub

Перейти в репозиторий библиотеки на Typescript

Перейти в репозиторий библиотеки на GO

Настраиваем уведомления

API MAX поддерживает два типа уведомлений о действиях пользователей с ботом — через Webhook и Long Polling. Использовать одновременно их нельзя — выберите один из типов. Long Polling можно использовать для разработки и тестирования, для production-окружения — только Webhook

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

Чтобы подключить уведомления, отправьте к API POST-запрос /subscriptions. В запросе укажите URL, на который должна приходить информация о новых событиях с ботом

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

Обратите внимание: для отправки вебхуков поддерживается только протокол HTTPS, включая самоподписанные сертификаты. HTTP не поддерживается

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

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

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

Создание диплинка бота

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

Код

Скопировать

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 в боте

Для получения обновлений с payload бот должен использовать Webhook или Long Polling

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

Когда пользователь переходит по диплинку, бот получает обновление типа 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 чата

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

Для получения несколько параметров в payload их нужно закодировать в одну строку, например:

Код

Скопировать

?start=param1_value1_param2_value2

Управляем ботом в MAX

Как изменить настройки бота

Изменить можно все настройки, кроме ника

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

Изменение настроек бота

Как разрешить или запретить добавление бота в групповой чат

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

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

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

Где посмотреть токен бота

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

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

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

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

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

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

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

Добавляем приложение в MAX

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

Подробнее – в документации мини-приложений

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