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

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

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

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

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

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

Как создать и настроить бота: пошаговая инструкция

Подготовка. Создайте бота на платформе MAX для партнёров и получите токен бота — он понадобится во всех API-запросах
Настройка уведомлений. Подпишитесь на события через Webhook, чтобы узнавать о действиях пользователя с ботом. Для разработки и тестирования также доступен Long Polling
(Опционально) Работа с диплинками. Если нужно передавать контекст при запуске бота, например направить пользователя с сайта в бот для отслеживания статуса заказа, настройте диплинки
Отправка сообщений и кнопок. Отправляйте сообщения в чат через POST /messages и организуйте работу с кнопками — они помогают выстраивать сценарии без текстового ввода
Загрузка медиафайлов. Загружайте файлы через POST /uploads и прикрепляйте их к сообщениям
Управление сообщениями. Редактируйте и удаляйте отправленные сообщения — это позволяет обновлять интерфейс бота без отправки новых сообщений
Управление ботом. Настраивайте работу с ботом и редактируйте информацию о нём
(Опционально) Добавление мини-приложения. Если возможностей бота не хватает, подключите мини-приложение

Перед началом работы ознакомьтесь с ограничениями API MAX и требованиями к вебхукам, а также с примерами создания ботов

Официальные библиотеки: JavaScript и Golang

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

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

Базовый URL

Код

Скопировать

https://platform-api2.max.ru/

Пример запроса:

Код

Скопировать

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

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

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

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

Для работы с API MAX вы можете скачать спецификацию OpenAPI в формате .YAML в репозитории на GitHub

С помощью файла спецификации и генератора кода вы можете получить готовый интерфейс (модели данных и функции для вызова эндпоинтов API) на целевом языке разработки вашего приложения, например: Python, C#, PHP, Java, Swift или Kotlin. Это упрощает проверку типов передаваемых данных, сокращает время на ручной перенос моделей, парсинг и сериализацию JSON-данных и позволяет сосредоточиться на бизнес-логике вашего приложения

Обратите внимание, спецификация содержит краткое описание параметров и эндпоинтов. Подробнее читайте в разделе про API и описании конкретных методов

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

Также вы можете воспользоваться Golang-фреймворком, чтобы с его помощью настраивать бота, обрабатывать сообщения, команды, callback-запросы и события

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

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

Перейти в репозиторий спецификации OpenAPI

Перейти в репозиторий Golang-фреймворка

Добавление бота в чаты и каналы

Вы можете добавить бота в групповой чат или канал:

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

Добавить бота в личный диалог нельзя

Настройка приватности бота

Изменить настройки приватности можно только для бота, который прошёл модерацию

По умолчанию добавление бота в групповые чаты запрещено. Чтобы это изменить:

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

Подробнее о том, как создать групповой чат, добавить бота в чат и назначить бота администратором — в FAQ чат-ботов

Права доступа бота в чате и канале

Чтобы бот мог выполнять действия в групповом чате или канале (отправлять сообщения, закреплять их, управлять участниками), ему нужны права администратора

Права можно настроить двумя способами: через интерфейс мессенджера или через API. Назначить администратором можно только бота, который уже является участником чата или подписчиком канала

Через интерфейс мессенджера

Откройте групповой чат или канал
Нажмите на название и выберите:
- Для группового чата: Участники → Добавить участников
- Для канала: Подписчики → Добавить подписчиков
Найдите бота, назначьте его администратором и настройте права

Через API

Важно! Первого бота-администратора можно назначить только через интерфейс мессенджера. После этого он сможет делать администраторами других ботов через API

Чтобы назначить бота администратором группового чата или канала, используйте метод POST /chats/{chatId}/members/admins. Запрос должен выполняться от имени другого бота, который уже является администратором с правом add_admins

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

Минимальный набор прав для работы бота — read_all_messages и write. Без read_all_messages бот не будет получать обновления через Webhook — без write не сможет отвечать в чате

Права доступа

Доступные права администратора	Что позволяет делать	Где применяется
`read_all_messages`	Читать все сообщения в чате или посты в канале	Чат и канал
`write`	Редактировать и удалять сообщения в чатах, публиковать посты и комментарии в каналах	Чат и канал
`edit`	Редактировать посты и комментарии в каналах	Канал
`delete`	Удалять посты и комментарии в каналах	Канал
`pin_message`	Закреплять сообщения	Чат и канал
`change_chat_info`	Изменять информацию о чате или канале	Чат и канал
`add_remove_members`	Добавлять и удалять участников чата или подписчиков канала	Для ботов доступно только в чатах, для пользователей — в чатах и каналах
`add_admins`	Добавлять и удалять администраторов	Чат и канал
`edit_link`	Изменять ссылку на групповой чат	Чат
`can_call`	Звонить в групповом чате. Назначается автоматически при выдаче прав администратора	Чат
`view_stats`	Просматривать статистику канала. По умолчанию доступно только владельцам каналов	Канал

Подробнее о правах доступа — в разделе «Доступные права администратора»

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

В целях повышения безопасности с 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

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

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

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

Вы формируете диплинк для перехода в бота, передав в payload необходимые параметры. Убедитесь, что длина payload не превышает 128 символов
Вы добавляете в приложение или на лендинг кнопку с диплинком
Пользователь переходит по диплинку и запускает бота в MAX
Бот получает событие bot_started и извлекает payload
Бот обрабатывает payload и отображает информацию в соответствии с переданными параметрами

Не передавайте в payload конфиденциальные данные в открытом виде — используйте одноразовые токены или закодированные идентификаторы сессии

Примеры диплинков для перехода в бот

Сценарий	Пример диплинка	Пример использования
Обратная связь о посещении ресторана	`https://max.ru/MyBot?start=feedback_rest123`	Вы размещаете QR-код на чеке или на столике. Пользователь сканирует QR-код, переходит в бота MAX по диплинку. Бот отображает диалоговое окно с предложением оценить обслуживание или оставить отзыв о блюдах
Получение промокода на скидку	`https://max.ru/MyBot?start=promo123`	Вы добавляете ссылку для перехода в бот в рассылку. Пользователь переходит в бота MAX и видит диалоговое окно с приветствием и промокодом на скидку
Отслеживание источника переходов в бот	`https://max.ru/MyBot?start=your_site`	Вы размещаете ссылки для перехода в бот на внешних сайтах и отслеживаете статистику переходов с каждого ресурса
Отслеживание статуса заказа	`https://max.ru/MyBot?start=order_12345`	Вы размещаете ссылку для отслеживания заказа на сайте своего ресторана. Пользователь переходит в бота MAX по диплинку с номером заказа. Бот получает идентификатор заказа и сразу показывает актуальный статус и дополнительную информацию по доставке

Важно! Диплинки нужны для запуска чат-бота и передачи контекста. Их использование не должно противоречить требованиям к содержанию и функциональности приложений. Например, отправлять авторизационные сообщения через диплинки запрещено

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