MaxLoyalty
← Назад к блогу

UmaxBot: Асинхронный Python-фреймворк для создания ботов в мессенджере MAX

UmaxBot: Асинхронный Python-фреймворк для создания ботов в мессенджере MAX

С ростом популярности российского мессенджера MAX всё больше разработчиков обращают внимание на эту платформу. На момент написания материала официальная библиотека от разработчиков существовала только под JavaScript. Для Python-сообщества потребовались альтернативные решения, и одним из них стал UmaxBot — асинхронный Python-фреймворк, построенный по знакомой многим разработчикам архитектуре aiogram.

UmaxBot (на PyPI пакет называется umaxbot, а при импорте используется maxbot) — это библиотека с открытым исходным кодом, распространяемая под лицензией MIT. Она предоставляет разработчикам удобный инструментарий для создания ботов в MAX с минимальным порогом входа, особенно для тех, кто уже знаком с экосистемой Telegram-ботов.

Ключевые особенности

UmaxBot позиционируется как «асинхронный Python-фреймворк для создания ботов в мессенджере MAX» с синтаксисом, аналогичным aiogram. Основные возможности библиотеки включают:

  1. Работа с сообщениями — отправка, редактирование и удаление сообщений.

  2. Передача файлов — поддержка фото, аудио, видео и документов.

  3. Инлайн-клавиатура — создание кнопок с callback-обработкой.

  4. FSM (Finite State Machine) — хранение состояния пользователя с методами set_state(), get_state(), reset_state(), update_data(), get_data().

  5. Роутеры (Router) — для организации кода в масштабируемых проектах.

  6. Polling с поддержкой очередей, воркеров, параллельной обработки и защитой от падений.

Установка и быстрый старт

Установка выполняется стандартной командой pip:

pip install umaxbot

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

Пример простейшего бота выглядит так:

from maxbot.bot import Bot
from maxbot.dispatcher import Dispatcher
from maxbot.types import InlineKeyboardMarkup, InlineKeyboardButton, Message

bot = Bot("YourToken")
dp = Dispatcher(bot)

@dp.message()
async def on_message(message: Message):
    keyboard = InlineKeyboardMarkup(inline_keyboard=[
        [InlineKeyboardButton(text="Поздороваться", callback_data="hello")]
    ])
    await bot.send_message(
        chat_id=message.sender.id,
        text="Привет! Нажми на кнопку ниже:",
        reply_markup=keyboard
    )

@dp.callback()
async def on_callback(cb):
    if cb.payload == "hello":
        await bot.send_message(cb.user.id, "Приятно познакомиться!")

Работа с производительностью

Одним из важных преимуществ UmaxBot является встроенная поддержка параллельной обработки. Dispatcher позволяет настроить количество воркеров и максимальное количество одновременно выполняемых задач:

dp = Dispatcher(bot, workers=10, max_tasks=200)

Разработчики библиотеки рекомендуют следующие настройки в зависимости от ожидаемой нагрузки:

 
 
Нагрузкаworkersmax_tasks
Маленькая550
Средняя10200
Высокая20+500+

 

Работа с медиафайлами

Библиотека предоставляет удобные методы для работы с вложениями:

@dp.message()
async def on_message(msg: Message):
    # Скачать первое аудио-вложение
    audio = msg.get_attachment("audio")
    if audio:
        await audio.download(bot, "voice.ogg")
    
    # Скачать все фото
    for img in msg.get_attachments("image"):
        await img.download(bot)

FSM: управление состояниями

Для создания многошаговых диалогов предусмотрен механизм конечных автоматов:

from maxbot.fsm import State, StatesGroup

class Form(StatesGroup):
    name = State()
    age = State()

@dp.message()
async def on_message(msg: Message):
    await msg.set_state(Form.name)
    state = await msg.get_state()
    await msg.update_data(name="Пользователь")
    # ...
    await msg.reset_state()

Важные изменения в API

Разработчики библиотеки предупреждают о ключевых изменениях, которые важно учитывать:

  • Авторизация: передача access_token через query-параметры больше не поддерживается — используется только заголовок Authorization.

  • Работа с файлами: теперь все типы файлов обрабатываются единообразно через получение upload_url, загрузку файла и передачу всего payload в attachments.

  • Reply (ответ на сообщение): добавлено поле link с типом reply.

Экосистема MAX: контекст и альтернативы

UmaxBot — не единственное решение для разработки ботов в MAX. На момент написания существует несколько альтернатив:

  • max-botapi-python — неофициальная библиотека, форк которой проверен командой MAX.

  • maxigram / maxapi — библиотеки, стремящиеся к совместимости с pyTelegramBotAPI.

  • maxbot-ai — open-source фреймворк для создания диалоговых приложений.

  • pyromax — фреймворк для создания юзерботов, также вдохновлённый aiogram 3.x.

Стоит отметить, что официальная документация MAX API доступна на портале dev.max.ru. Она описывает работу с API через HTTPS-запросы, где поддерживаются методы GET, POST, PUT, DELETE и PATCH.

Практические нюансы разработки под MAX

Разработчики, имеющие опыт работы с Telegram Bot API, могут столкнуться с определёнными отличиями при переходе на MAX. Как отмечается в практических обзорах, структура входящих вебхуков может отличаться от документации: например, объект сообщения может быть обёрнут в мета-контейнер, а таймстемпы передаются в миллисекундах, а не в секундах.

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

Плюсы и минусы UmaxBot

Преимущества:

✅ Знакомый синтаксис — для тех, кто работал с aiogram, переход будет максимально плавным.

✅ Асинхронность — все методы асинхронные, что обеспечивает высокую производительность.

✅ Богатый функционал — поддержка FSM, роутеров, инлайн-кнопок, медиафайлов.

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

✅ MIT-лицензия — библиотека свободна для использования в коммерческих проектах.

Недостатки и риски:

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

⚠️ Небольшое сообщество — по сравнению с экосистемой Telegram, количество готовых примеров и статей по UmaxBot ограничено.

⚠️ Изменчивость API — сам MAX API ещё развивается, что может требовать доработок в библиотеке.

⚠️ Ограниченная документация — в основном документация представлена в самом репозитории и на PyPI, без отдельного сайта с подробными руководствами.

Заключение

UmaxBot — это достойная попытка создать для мессенджера MAX такой же удобный инструмент для разработки ботов, каким aiogram стал для Telegram. Библиотека предлагает широкий набор возможностей: от базовой отправки сообщений до сложных сценариев с FSM и роутерами.

Для Python-разработчиков, которые хотят освоить новую платформу или перенести существующих ботов в экосистему MAX, UmaxBot может стать отличной стартовой точкой. Однако стоит учитывать, что экосистема MAX находится в стадии активного развития, а библиотека является неофициальной. Перед использованием в серьёзных production-проектах рекомендуется протестировать совместимость с актуальной версией API и быть готовым к возможным доработкам.

Проект доступен на PyPI и GitHub. Исходный код открыт, и любой желающий может внести свой вклад в его развитие.