Как создать бота в MAX

С чего началось

Бот автоброни поставок для Ozon и Wildberries сначала работал только в Telegram, а клиенты всё чаще спрашивали про MAX. Хотелось, чтобы тот же бот работал в обоих мессенджерах с общими кабинетами и балансом, а не превращался в два разных продукта. Позже понадобилось ещё публиковать посты в свой канал в MAX: при ручной вставке текста жирный шрифт и ссылки терялись, и выделять каждый пост руками было долго.

Коротко

Создать бота в MAX может только ИП, юрлицо или самозанятый из России: бот регистрируется на платформе MAX для партнёров, проходит модерацию до 48 рабочих часов и только после этого получает токен. Дальше всё похоже на Telegram: HTTP API, сообщения с кнопками, обновления через long polling или webhook. Отличаются детали, которые ломают перенос готового кода: формат кнопок и обновлений, вёрстка сообщений и новый адрес API с сертификатом Минцифры.

Когда пригодится

• Нужно запустить бота для клиентов, которые сидят в MAX, а не в Telegram.
• Уже есть бот в Telegram, и его нужно повторить в MAX с той же логикой.
• Нужно публиковать посты в канал MAX с форматированием, а не вставлять руками.

Что нужно заранее: статус ИП, юрлица или самозанятого и аккаунт в MAX, логотип 500×500 и описание бота до 200 символов.

Кто может создать бота в MAX

Создать бота может только организация: юрлицо, ИП или самозанятый, резидент России. Обычный пользователь без статуса бота не зарегистрирует. Аналога BotFather, где бот появляется за минуту, в MAX нет: профиль организации проходит верификацию, а сам бот модерацию.

Шаг 1. Профиль на платформе для партнёров

Профиль создаётся на платформе MAX для партнёров: в веб-версии business.max.ru или в мини-приложении «MAX для бизнеса». Заполняются данные ИП, юрлица или самозанятого, после чего профиль проходит верификацию. Пока её нет, создать бота нельзя.

Шаг 2. Создать бота и пройти модерацию

В профиле раздел Чат-боты → Создать. Нужны:

• логотип: 500×500, JPG или PNG, до 5 МБ;
• название: до 59 символов, без эмодзи;
• описание: до 200 символов, что делает бот.

Никнейм выбрать нельзя: он создаётся сам, для ИП и компаний в виде idИНН_bot. Поэтому в рекламе и на сайте удобнее давать ссылку на бота, а не просить искать его по имени.

Модерация занимает до 48 рабочих часов, статус приходит сообщением от бота «MAX для бизнеса». Пока бот на модерации, его настройки менять нельзя.

Шаг 3. Взять токен и проверить его

Токен появляется после модерации: Чат-боты → ⋮ → Настройки. Он передаётся в заголовке Authorization как есть, без слова Bearer. Передавать токен в адресе запроса больше нельзя.

Проверить токен:

curl -s https://platform-api.max.ru/me -H "Authorization: ТОКЕН_БОТА"

В ответ придут имя и никнейм бота. Если токен не передан или неверный, сервер ответит 401:

Шаг 4. Отправить сообщение с кнопками

Сообщение отправляется методом POST /messages. Кому писать, задаётся параметром: user_id для личного диалога, chat_id для группы или канала. Разметка включается полем format: html или markdown.

import json, urllib.request

def send(token, user_id, text, buttons=None):
    body = {"text": text, "format": "html"}
    if buttons:   # кнопки: вложение типа inline_keyboard, список рядов
        body["attachments"] = [{"type": "inline_keyboard", "payload": {"buttons": buttons}}]
    req = urllib.request.Request(
        f"https://platform-api.max.ru/messages?user_id={user_id}",
        data=json.dumps(body).encode(), method="POST",
        headers={"Authorization": token, "Content-Type": "application/json"})
    return json.loads(urllib.request.urlopen(req).read())

send(TOKEN, 123456, "<b>Выберите кабинет</b> для создания автобронирования:",
     [[{"type": "callback", "text": "Кабинет 1", "payload": "cab_1"}],
      [{"type": "link", "text": "Сайт", "url": "https://example.ru"}]])

Кнопка callback присылает боту payload, кнопка link открывает ссылку. На нажатие callback-кнопки бот отвечает методом POST /answers/callback с callback_id, при желании с коротким уведомлением для пользователя. Отредактировать уже отправленное сообщение можно через PUT /messages?message_id=….

Шаг 5. Получать сообщения: long polling или webhook

Long polling проще для начала: бот сам спрашивает новые события и передаёт marker, чтобы не получать одно и то же дважды.

GET /updates?timeout=25&types=message_created,message_callback,bot_started&marker=<marker из прошлого ответа>

Webhook удобнее на сервере: MAX сам присылает события на ваш адрес. Подписка POST /subscriptions с полями url и update_types, список подписок GET /subscriptions, удаление DELETE /subscriptions?url=…. Повторная подписка на тот же адрес дубль не создаёт.

Основные типы событий: message_created (новое сообщение), message_callback (нажатие кнопки), bot_started (пользователь запустил бота).

Ссылки с параметром: рефералы и приглашения

Как и в Telegram, в бота можно передать параметр через ссылку:

https://max.ru/<никнейм_бота>?start=ref_12345

Бот получит событие bot_started с полем payload = ref_12345. Так в боте автоброни работают реферальная программа и приглашения сотрудников в кабинет.

Публикация в канал

Бота добавляют в канал администратором, после чего метод GET /chats покажет канал и его chat_id (у каналов он отрицательный). Пост отправляется тем же POST /messages, только с chat_id.

Картинка загружается в два шага: POST /uploads?type=image выдаёт адрес загрузки, файл отправляется туда, а из ответа получается вложение для сообщения. Если отправить пост сразу, API может ответить attachment.not.ready: картинке нужно несколько секунд на обработку, поэтому отправку стоит повторить через 2–3 секунды.

Грабли: узкий пузырёк и слова по буквам

Главное отличие от Telegram, которое не описано в документации. В MAX ширина пузырька сообщения равна длине самой длинной строки. Если текст состоит из коротких строк, пузырёк сужается, и слова переносятся по буквам: «Актив / ные / автоб / рон / ирова / ния». В Telegram тот же текст выглядит нормально.

Что помогло:

• первая строка не короче 35 символов, она задаёт ширину пузырька;
• короткий заголовок не отрывать от текста пустой строкой, а склеивать с первой фразой через двоеточие;
• элементы списка писать одной длинной строкой с разделителями • или |;
• длинные ссылки и ID не оборачивать в моноширинный шрифт, он сужает пузырёк ещё сильнее.

В коде бота автоброни перед отправкой в MAX текст проходит через небольшую функцию, которая убирает пустые строки и склеивает короткую первую строку со следующей. Тексты для Telegram при этом остаются как были.

Грабли: новый адрес API и сертификат Минцифры

В документации MAX теперь указан адрес https://platform-api2.max.ru вместо platform-api.max.ru. Новый адрес работает на сертификате Минцифры, которого нет в стандартных хранилищах macOS и Linux, поэтому без его установки запросы падают ещё до ответа сервера:

Старый адрес на момент записи продолжает отвечать. Чтобы переехать на новый, нужно добавить корневой сертификат Минцифры в доверенные на сервере, где работает бот, или указать его в настройках HTTP-клиента.

Грабли: user_id и chat_id

Отправка по user_id работает для личного диалога с пользователем, а для группы или канала нужен chat_id. В боте автоброни сделан простой запасной вариант: если отправка по user_id вернула 404, сообщение уходит повторно с тем же числом как chat_id.

Отличия бота в MAX от Telegram

Частые вопросы