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

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

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

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

Подготовка

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

Тип профиля	Количество ботов, которое можно создать для одного профиля
Организация или ИП	5 ботов
Самозанятый	2 бота

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

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

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

Имя, которое отображается в MAX в чате с вашим ботом, — задаётся при создании бота в поле Название
Аватар (фото профиля) — загружается в виде логотипа при создании бота
Ник, который отображается в публичной ссылке. Например, для https://max.ru/idИНН_bot ником является idИНН_bot
Ник генерируется автоматически при создании бота по шаблону: idИНН_bot — для ИП и юрлиц, se(orgid)_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

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

В целях повышения безопасности с 25 мая прекращается поддержка получения вебхуков по HTTP, а также самоподписных сертификатов. Рекомендуем заранее перейти на HTTPS и сертификаты от доверенных центров. Чтобы обновить подписку на события, используйте POST /subscriptions

Получение обновлений с помощью Long Polling ограничено по скорости и сроку хранения событий — этот способ не подходит для production-окружения. Рекомендуем на всех этапах работы использовать Webhook

API поддерживает два типа уведомлений о действиях пользователей с ботом — выбор зависит от этапа работы:

Для production-окружения — только Webhook
Для разработки и тестирования — Webhook или Long Polling

Использовать одновременно оба типа нельзя — выберите один из них

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

Webhook

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

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

Для повышения безопасности с 25 мая прекращается поддержка получения вебхуков по HTTP, а также самоподписных сертификатов. Используйте HTTPS и сертификаты, выданные доверенным центром сертификации. Подробнее о требованиях безопасности при подключении вебхуков — в описании POST /subscriptions

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

Long Polling

Получение обновлений с помощью Long Polling ограничено по скорости и сроку хранения событий — этот способ не подходит для production-окружения. Рекомендуем на всех этапах работы использовать Webhook

Чтобы получить обновления через 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_site

Payload в боте

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

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

Получение обновлений с помощью Long Polling ограничено по скорости и сроку хранения событий — этот способ не подходит для production-окружения. Рекомендуем на всех этапах работы использовать Webhook

При настройке Webhook убедитесь, что в параметре update_types включён тип bot_started. Подробнее о событиях в боте — в описании объекта Update

Когда пользователь переходит по диплинку, бот получает обновление типа bot_started через Webhook или Long Polling в объекте Update:

Код

Скопировать

{
    "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

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

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