Как создать своего бота в MAX: регистрация, API и примеры использования

У MAX уже есть API для чат-ботов, поэтому мессенджер можно использовать не только для обычной переписки. Бота можно связать со своим сайтом, сервером, системой мониторинга или внутренними сервисами и автоматизировать довольно много рутинных вещей.

Я сам использую такую связку на этом сайте: после появления новой публикации сервер передаёт информацию боту, а тот публикует уведомление в моём канале MAX.

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

Разберём весь путь от регистрации до первого запроса к API, а в конце запустим небольшой пример на Python, который можно оставить работать на обычном Ubuntu-сервере или одноплатнике.

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

На момент написания статьи платформа MAX для партнёров доступна:

• юридическим лицам;
• индивидуальным предпринимателям;
• самозанятым.

При этом профиль должен принадлежать резиденту РФ.

Обычное физическое лицо без соответствующего статуса пройти верификацию платформы разработчика сейчас не может.

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

Для одного профиля действуют ограничения по количеству ботов:

Актуальные требования лучше проверять непосредственно в официальной документации MAX, поскольку платформа активно развивается и условия со временем могут измениться.

Где регистрируется бот

Начинать нужно с платформы MAX для партнёров.

Сначала создаётся и верифицируется профиль организации, ИП или самозанятого.

Последовательность примерно такая:

1. Войти в платформу MAX для партнёров.
2. Создать профиль.
3. Пройти его верификацию.
4. Открыть раздел Чат-боты.
5. Нажать Создать.
6. Заполнить карточку будущего бота.
7. Отправить его на модерацию.

У бота потребуется указать название, описание и логотип.

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

После создания бот отправляется на модерацию.

Только после успешного прохождения проверки становятся доступны расширенные настройки и токен для работы с API.

Где взять токен

После прохождения модерации открываем:

Чат-боты → нужный бот → Расширенные настройки → Настроить

Там появится токен.

Токен фактически является ключом управления ботом, поэтому относиться к нему нужно примерно как к паролю.

Не стоит:

• публиковать его на GitHub;
• вставлять в статью или скриншоты;
• отправлять посторонним;
• хранить в публично доступном каталоге сайта.

Если токен случайно утёк, его лучше сразу перевыпустить через настройки бота.

Кстати, в актуальной версии API токен передаётся через HTTP-заголовок:

Authorization: ВАШ_ТОКЕН

Старые примеры с передачей токена непосредственно в URL лучше не использовать.

Что вообще можно сделать с ботом

Сам бот — это скорее точка входа между MAX и вашей программой.

Логика может работать где угодно:

MAX
 │
 │ API
 ▼
Python-приложение
 │
 ├── сайт
 ├── база данных
 ├── система мониторинга
 ├── Home Assistant
 ├── сервер
 └── другие сервисы

Отсюда появляется довольно много нормальных практических сценариев.

Например, бот может уведомлять администратора о состоянии сервера, принимать заявки, сообщать о завершении фоновой задачи, отправлять уведомления интернет-магазина или работать как интерфейс к собственной системе автоматизации.

Пример с этим сайтом

На v3trov.pro у меня реализован достаточно простой мост:

Новая статья на v3trov.pro
          │
          ▼
       сервер
          │
          ▼
       MAX Bot
          │
          ▼
     канал в MAX

Когда на сайте появляется новая публикация, бот отправляет уведомление в канал.

Сам канал можно посмотреть здесь:

Канал v3trov.pro в MAX

То есть мне не нужно после каждой публикации отдельно открывать мессенджер, копировать заголовок, ссылку и вручную делать ещё один пост.

Именно такие небольшие автоматизации, на мой взгляд, и являются одним из наиболее полезных применений Bot API.

Где запускать своего бота

Для постоянно работающего бота совершенно необязательно арендовать мощный сервер.

Подойдёт практически любая Linux-машина:

• VPS;
• Raspberry Pi;
• Orange Pi;
• Rock Pi;
• домашний мини-ПК;
• обычный сервер с Ubuntu или Debian.

У меня вообще есть отдельный материал про установку Armbian на Rock Pi 4B и подключение по SSH без монитора.

Такого одноплатника для небольшого Python-бота хватит с огромным запасом.

Если с одноплатниками пока не работали, можно также посмотреть Armbian: установка и первоначальная настройка.

Проверяем токен через Python

Сделаем самый простой и безопасный тест — запросим у MAX информацию о нашем боте.

Предположим, что используется Ubuntu, Debian или Armbian.

Устанавливаем Python и requests:

sudo apt update
sudo apt install -y python3 python3-pip python3-venv

Создадим каталог:

mkdir -p ~/maxbot
cd ~/maxbot

Создадим виртуальное окружение:

python3 -m venv venv
source venv/bin/activate

Установим библиотеку:

pip install requests

Теперь создадим файл:

nano bot.py

Код:

import os
import requests

API_URL = "https://platform-api2.max.ru"

TOKEN = os.getenv("MAX_BOT_TOKEN")

if not TOKEN:
    raise RuntimeError(
        "Не задан MAX_BOT_TOKEN. "
        "Сначала добавьте токен в переменную окружения."
    )


def get_bot_info():
    headers = {
        "Authorization": TOKEN
    }

    response = requests.get(
        f"{API_URL}/me",
        headers=headers,
        timeout=15
    )

    response.raise_for_status()

    return response.json()


if __name__ == "__main__":
    try:
        bot = get_bot_info()

        print("Соединение с MAX API работает.")
        print()
        print(bot)

    except requests.RequestException as error:
        print(f"Ошибка обращения к MAX API: {error}")

Сохраняем файл.

Теперь задаём токен:

export MAX_BOT_TOKEN='ВАШ_ТОКЕН'

И запускаем:

python bot.py

Если токен действующий и сервер нормально обращается к API MAX, в ответ придёт информация о зарегистрированном боте.

Таким образом мы заодно проверили сразу несколько вещей:

Linux
  ↓
Python
  ↓
HTTPS
  ↓
MAX API
  ↓
наш бот

Пример полезной автоматизации

Теперь немного интереснее.

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

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

Пример проверки:

import shutil


def get_disk_usage():
    total, used, free = shutil.disk_usage("/")

    total_gb = total / 1024**3
    used_gb = used / 1024**3
    free_gb = free / 1024**3

    percent = used / total * 100

    return {
        "total": total_gb,
        "used": used_gb,
        "free": free_gb,
        "percent": percent,
    }


disk = get_disk_usage()

print(
    f"Использовано: {disk['percent']:.1f}%n"
    f"Свободно: {disk['free']:.1f} ГБ"
)

А дальше результат можно связать с методом отправки сообщений MAX.

Например:

import os
import shutil
import requests

API_URL = "https://platform-api2.max.ru"

TOKEN = os.getenv("MAX_BOT_TOKEN")
USER_ID = os.getenv("MAX_USER_ID")

LIMIT = 90


def send_message(text):
    if not TOKEN:
        raise RuntimeError("Не задан MAX_BOT_TOKEN")

    if not USER_ID:
        raise RuntimeError("Не задан MAX_USER_ID")

    response = requests.post(
        f"{API_URL}/messages",
        params={
            "user_id": USER_ID
        },
        headers={
            "Authorization": TOKEN,
            "Content-Type": "application/json"
        },
        json={
            "text": text
        },
        timeout=15
    )

    response.raise_for_status()

    return response.json()


def check_disk():
    total, used, free = shutil.disk_usage("/")

    used_percent = used / total * 100
    free_gb = free / 1024**3

    print(
        f"Диск занят на {used_percent:.1f}%, "
        f"свободно {free_gb:.1f} ГБ"
    )

    if used_percent >= LIMIT:
        send_message(
            "Внимание!n"
            f"Системный диск занят на {used_percent:.1f}%.n"
            f"Свободно: {free_gb:.1f} ГБ."
        )


if __name__ == "__main__":
    try:
        check_disk()

    except requests.RequestException as error:
        print(f"Ошибка MAX API: {error}")

    except Exception as error:
        print(f"Ошибка: {error}")

Получается уже вполне практичная вещь: маленький Rock Pi может заниматься своими обычными серверными задачами и сообщать в MAX, когда на диске заканчивается место.

По такому же принципу можно контролировать температуру, резервные копии, состояние сервисов или результаты собственных скриптов.

Как запускать скрипт автоматически

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

Можно использовать обычный cron:

crontab -e

Например, проверять диск каждые 30 минут:

*/30 * * * * MAX_BOT_TOKEN='ВАШ_ТОКЕН' MAX_USER_ID='ВАШ_ID' /home/user/maxbot/venv/bin/python /home/user/maxbot/bot.py >> /home/user/maxbot/bot.log 2>&1

Но токен непосредственно в crontab — не лучший вариант для постоянной эксплуатации.

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

Для домашнего проекта это уже вопрос того, насколько далеко хочется зайти с настройкой.

Бот и канал — не одно и то же

Этот момент поначалу может немного путать.

Бот — это приложение, которое работает через API.

Канал — место, где пользователи читают публикации.

Но их можно связать.

Например:

сайт
  │
  ▼
бот
  │
  ▼
канал
  │
  ▼
подписчики

Именно по такой схеме работает автоматизация публикаций v3trov.pro.

API MAX позволяет адресовать сообщения не только конкретному пользователю, но и чату или каналу через его chat_id.

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

Не забываем про ограничения API

У API есть ограничения, и писать бесконечный цикл, который долбит сервер сотнями запросов, точно не стоит.

В текущей документации MAX для стабильной работы рекомендуется не превышать 30 запросов в секунду к platform-api2.max.ru.

Для обычного домашнего или небольшого коммерческого бота это огромный запас.

Но если проект разрастается, rate limit уже стоит учитывать в архитектуре.

Ещё один момент — используйте актуальный адрес:

https://platform-api2.max.ru

В старых примерах в интернете может попадаться:

platform-api.max.ru

Актуальная документация MAX рекомендует использовать именно platform-api2.max.ru.

Важный момент насчёт правил MAX

Получение токена не означает, что с API можно делать вообще всё что угодно.

У платформы есть правила для разработчиков, и перед запуском публичного проекта их действительно стоит хотя бы один раз прочитать.

Это особенно важно, если бот:

• работает с большим количеством пользователей;
• занимается массовой рассылкой;
• автоматически публикует контент;
• хранит пользовательские данные;
• является частью коммерческого сервиса.

И здесь есть достаточно серьёзный нюанс.

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

То есть в теории последствия нарушения правил могут оказаться шире блокировки одного неудачного бота.

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

Особенно если на одном профиле находятся несколько нормальных рабочих проектов.

Можно ли сделать бота без программирования

Да.

MAX поддерживает сценарии, которые можно собирать через конструкторы без собственного кода.

Для простого FAQ, приёма заявок или нескольких кнопок этого может оказаться достаточно.

Но если бот должен общаться с вашим сервером, сайтом, базой данных, датчиками или другими собственными сервисами, Python даёт гораздо больше свободы.

И тут как раз становится интересно использовать маленький домашний сервер.

На сайте есть несколько материалов на эту тему:

• Rock Pi 4B: установка Armbian и SSH
• Armbian для одноплатников: установка и настройка
• Raspberry Pi как домашний сервер
• GPIO на Raspberry Pi: управление из Python

Что в итоге

Создание бота в MAX сейчас состоит из двух довольно разных частей.

Сначала организационная:

ИП / юрлицо / самозанятый
          ↓
MAX для партнёров
          ↓
верификация
          ↓
создание бота
          ↓
модерация
          ↓
токен

И только потом начинается техническая часть:

токен
  ↓
MAX API
  ↓
Python / jаvascript / Go / другой клиент
  ↓
ваша собственная логика

Сам API при этом достаточно обычный: HTTPS-запросы, JSON и авторизация по токену. Поэтому для простых интеграций не требуется какой-то особой инфраструктуры.

Можно начать буквально со старого одноплатника и нескольких десятков строк Python, а потом постепенно связать MAX с мониторингом, сайтом, домашней автоматизацией или собственными сервисами.

У меня первым действительно полезным применением стал мост между сайтом и каналом MAX: новая публикация появляется на v3trov.pro — следом автоматически появляется уведомление в канале v3trov.pro.

И вот в таком виде бот уже перестаёт быть игрушкой «потыкать API» и просто снимает ещё одну небольшую рутинную задачу.