Настройка сценариев работы бота с помощью API

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

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

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

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

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

Отправка API-запросов

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

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

Код

Скопировать

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

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

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

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

Если вы пишете ботов на TypeScript, JavaScript или Golang, рекомендуем использовать нашу официальную библиотеку — она содержит разные стандартные методы и утилиты. Читайте подробнее в разделах «Библиотека JavaScript» и «Библиотека Golang» здесь или на 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-api2.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

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