Skip to main content

aiogram-max

PyPI Python CI License Checked with mypy Ruff

Запускает бота, написанного на aiogram, в мессенджере MAX — без правок кода бота.

from aiogram import Dispatcher
from aiogram_max import make_bot

bot = make_bot(max_token="...")  # единственная изменённая строка
await Dispatcher().start_polling(bot)

Роутеры, фильтры (Command, магический F), FSM, middleware и типы остаются родными aiogram-овскими.

Статус

Рабочая библиотека, проверенная на живом MAX. Настоящий Dispatcher.start_polling ходит в MAX Bot API, хендлеры срабатывают, ответы и callback.answer() доезжают до мессенджера.

Покрыто 40 методов — всё, чему нашёлся аналог у платформы: сообщения и правки, вложения всех типов, клавиатуры и callback'и, группы с участниками и пинами, вебхук, команды бота, разметка. Каждый проверен на реальном боте, а не только тестами.

Как это работает

Весь исходящий трафик aiogram проходит через одну функцию:

BaseSession.make_request(bot, method: TelegramMethod, timeout) -> TelegramType

Bot не ходит в сеть сам: он собирает типизированный объект метода (SendMessage, GetUpdates, AnswerCallbackQuery, …) и отдаёт его сессии. Мы подменяем сессию — и перехватываем поток целиком:

Бот на aiogram  (код не меняется)
  Dispatcher / Router / фильтры / FSM
  Bot.send_message(...)
        │  TelegramMethod
        ▼
  MaxSession(BaseSession)     ← вся библиотека здесь
        │  HTTP
        ▼
  MAX Bot API

Long polling тоже работает штатно: aiogram сам зовёт GetUpdates, а сессия ходит в GET /updates?marker= и собирает из событий MAX валидные aiogram-Update.

Отличие от obabot, решающего похожую задачу: там своя система типов (obabot.Message, obabot.FSMContext) и импорты в боте меняются. Здесь типы остаются aiogram-овскими, подменяется только транспорт.

Что уже проверено тестами

Что Как проверено
MAX-событие → валидный aiogram Update test_get_updates_returns_aiogram_updates
Роутер + фильтр Command test_dispatcher_routes_message_to_handler
Inline-клавиатура → MAX inline_keyboard там же, сверка тела запроса
Callback + магический фильтр F.data test_callback_query_flows_through_aiogram
FSM (StatesGroup, FSMContext) test_fsm_state_survives_platform_swap
Родной Dispatcher.start_polling test_native_polling_loop_delivers_max_events
Правка сообщения (seq ↔ mid) test_edit_message_uses_max_mid
Неподдерживаемый метод test_unsupported_method_raises_in_strict_mode
Метка диплинка (?start=) → хвост команды test_deeplink_payload_arrives_as_command_tail
Живые payload'ы MAX tests/test_live_fixtures.py (9 тестов на снятых с API событиях)
Пересланное сообщение → forward_origin test_live_forward_keeps_text_and_author
Ответ на сообщение → reply_to_message test_live_reply_keeps_quoted_message
Потеря кнопки без аналога test_dropped_button_warns_but_keeps_the_rest
Маппинг parse_mode / notify / reply test_supported_params_are_mapped_not_dropped
Вложения: загрузка и отправка test_send_photo_uploads_and_attaches_token
Ожидание обработки файла на стороне MAX test_send_photo_waits_until_attachment_is_ready
MarkdownV2 → html (включая подчёркивание) tests/test_markup.py, 11 тестов
entities → html без потерь test_entities_are_no_longer_dropped_silently
MarkupPolicy.RAW не трогает текст test_raw_policy_leaves_text_alone

Диплинки: метка в ссылке на бота

Чтобы передать боту данные при запуске, добавьте к ссылке параметр start:

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

Метка (до 128 символов) приезжает в поле payload события bot_started, а библиотека кладёт её хвостом команды — ровно так, как отдаёт Telegram:

@router.message(Command("start"))
async def on_start(message: Message, command: CommandObject) -> None:
    tag = command.args  # «t7k3f9zqm» для ?start=t7k3f9zqm, None без метки

То есть обработчику не нужно знать, с какой он площадки: и в Telegram, и в MAX метка лежит в message.text после пробела.

Зачем это нужно: привязка бота к аккаунту внешнего сервиса одним нажатием, реферальные ссылки, метки рекламного источника. В документации MAX поле payload описано, а вот то, что заполняется он параметром start, — нет; отсюда и распространённое «в MAX такого нет».

Требования к приложению MAX: iOS 2.7.0+, Android 2.9.0+. На старых версиях метка не придёт, и bot_started приедет без payload — обработчик обязан это переживать.

Неподдерживаемое в MAX

У MAX нет части возможностей Telegram. Политика задаётся при создании бота:

make_bot(token)  # WARN, по умолчанию
make_bot(token, unsupported=UnsupportedPolicy.STRICT)

Расхождения бывают трёх видов:

  1. Метода нет вовсе (SendPoll, SendDice). WARN — предупреждение и пропуск, STRICT — UnsupportedByMax с именем метода.
  2. Метод есть, а параметра нет (кнопка web_app, switch_inline_query). Такая кнопка выбрасывается, остальные остаются: WARN пишет в лог что именно потерялось, STRICT падает. Молча не выбрасываем никогда — «кнопка исчезла, а бот не упал» ищется потом часами.
  3. Семантика другая — это работа слоя конвертации, а не политики: message_id (int) ↔ MAX mid (str) сшиваются через seq.

Где аналог есть — параметр переводится, а не теряется:

aiogram MAX
parse_mode="HTML" format: html
parse_mode="MarkdownV2" конвертация в html, см. «Разметка»
entities=[...] конвертация в html, см. «Разметка»
disable_notification=True notify: false
reply_to_message_id link: {type: reply, mid}

Обратный перевод, из MAX в aiogram, разбирает то же поле link:

MAX aiogram
link: {type: forward, sender, message} forward_origin (MessageOriginUser), текст из link.message.text
link: {type: reply, sender, message} reply_to_message

У пересланного сообщения внешний body.text приходит пустым — текст лежит только внутри link.message.text. До версии 1.2.0 библиотека читала внешний текст, и форвард превращался в сообщение без текста: бот на другой стороне не видел ни текста, ни признака пересылки и обычно не отвечал вовсе. Форма объекта снята с живого API 2026-08-17: в документации MAX страница LinkedMessage отдаёт 404.

Отдельный случай — пустой callback.answer(). В Telegram он снимает индикатор загрузки на кнопке и стоит почти в каждом хендлере; у MAX такой семантики нет, POST /answers с пустым телом отвечает 400 proto.payload («message or notification required»). Запрос не уходит вовсе. С текстом — answer("Принято") — уходит как notification.

Разметка

Работает из коробки: бот шлёт привычный телеграмный parse_mode или entities, библиотека переводит это в html, который MAX понимает.

await bot.send_message(chat_id, "*жирный* и __подчёркнутый__", parse_mode="MarkdownV2")
# в MAX уедет: {"text": "<b>жирный</b> и <u>подчёркнутый</u>", "format": "html"}

Форматируете под MAX сами — отключите посредника:

make_bot(token, markup=MarkupPolicy.RAW)  # текст уйдёт как есть

Почему html, а не markdown. MAX принимает оба формата, но markdown у него CommonMark, а в CommonMark __текст__ — это жирный. В MarkdownV2 та же запись означает подчёркивание, и перевод «markdown в markdown» молча превратил бы одно в другое. Тип underline MAX отдаёт только за <u>. Вдобавок html не требует правил экранирования, которых в MarkdownV2 полтора десятка, причём внутри кодовых спанов они другие.

Что MAX действительно поддерживает. Официальная страница «Форматирование» отдаёт 404, поэтому таблица снята с живого API: бот отправил пробу, MAX вернул разобранную разметку.

Разметка format: html format: markdown
жирный <b> → strong **x** → strong
курсив <i> → emphasized *x*, _x_ → emphasized
подчёркнутый <u> → underline нет: __x__ даёт strong
зачёркнутый <s> → strikethrough ~~x~~ → strikethrough
моноширинный <code>, <pre> → monospaced `x` → monospaced
ссылка <a href> → link [x](url) → link
заголовок не проверялся # x → heading
цитата <blockquote> — не распознаётся > x — не распознаётся
списки, спойлер нет нет

Чего у MAX нет вовсе — спойлер, цитата, кастомные эмодзи — проходит через ту же политику unsupported: WARN пишет в лог что именно потерялось, STRICT падает. Текст при этом сохраняется, теряется только оформление.

Грабли MAX, которые стоит знать

  • Индикатор набора у MAX есть, вопреки расхожему мнению: работает и в личке, и в группе. Только называется иначе — телеграмное typing он не понимает, нужно typing_on, и библиотека переводит сама.
  • Вложение не готово сразу после заливки. Отправка отвечает 400 attachment.not.ready, пока MAX обрабатывает файл. Библиотека ждёт и повторяет сама, но знать об этом стоит: в Telegram такого шага нет.
  • recipient.user_id — это получатель сообщения, а не собеседник. В событии от пользователя там лежит id бота, в сообщении бота пользователю — id пользователя. Подставите его как chat_id — бот начнёт молча отвечать сам себе. chat_id в диалоге MAX присылает, брать надо только его.
  • Позиция в ленте — marker, и она же update_id. MAX отдаёт в ответе «следующую ожидаемую» позицию, что совпадает по смыслу с телеграмным offset. Поэтому update_id события — его позиция в ленте (marker - 1 для последнего события пачки), а не порядковый номер внутри процесса. Для бота с дедупом по update_id это принципиально: счётчик из памяти после рестарта начинается заново, и свежие события выглядят уже обработанными.
  • seq — не маленький счётчик. Живое значение: 116993690454357274. В int64 влезает и aiogram переваривает, но узкое поле БД (integer вместо bigint) на этом сломается.
  • /start приходит обычным message_created, а не отдельным событием — фильтр Command работает без спецобработки. Нажатие «Начать» и переход по диплинку — другое событие, bot_started; библиотека приводит и его к /start, вместе с меткой из payload (см. «Диплинки»).
  • Идентификатор сообщения двойной: aiogram знает message_id (int из seq), MAX правит и удаляет по строковому mid. Соответствие держит сессия в памяти (последние 10 000 сообщений), поэтому правка переживает рестарт только в пределах жизни процесса. Обратного преобразования mid → seq MAX не даёт, так что иначе никак.

Тихие события ухода: bot_stopped, dialog_removed

Площадка сама присылает события ухода — человек удалил диалог или остановил бота. Потребитель, не знавший этих типов, терял их «прыжком позиции» — не узнать даже, кто ушёл.

Теперь оба типа конвертируются в пустой Update (без message и callback_query): потребительский разбор превращает их в своё kind=unknown, позиция ленты двигается штатно, без подсказки. Сырые словари той же пачки остаются в session.dropped_events — оттуда доступны update_type, user_id, chat_id, timestamp для аналитики отписок:

bot = make_bot(token)
async for _ in ...:  # ваш цикл get_updates
    for quiet in bot.session.dropped_events:
        ...  # кто ушёл, из какого чата

Список заменяется целиком на каждом get_updates — копления нет.

Что ещё не сделано

  • Webhook (у MAX это рекомендованный для прода транспорт).
  • Разметка подписей (caption, caption_entities) — вместе с вложениями.
  • Покрыто 40 методов из 185 в aiogram — всё, чему есть аналог у MAX. Что уже работает, что можно добавить и чего в MAX нет вовсе — в docs/method-coverage.md.

Установка

pip install aiogram-max      # после публикации; пока — pip install -e .

Python 3.12+, единственные зависимости — aiogram и httpx. Библиотека типизирована (py.typed), mypy strict проходит без ignore'ов.

Разработка

uv venv && uv pip install -e ".[dev]"
.venv/bin/ruff check . && .venv/bin/mypy && .venv/bin/pytest -q

Как добавить метод и чем NotImplementedYet отличается от UnsupportedByMax — в CONTRIBUTING.md.

Лицензия

MIT

Metadata

Release files for aiogram-max 1.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aiogram-max 1.4.0
File Size Uploaded Provenance Actions
aiogram_max-1.4.0.tar.gz 137.1 kB Without provenance Details for aiogram_max-1.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aiogram-max 1.4.0
File Interpreter ABI Platform Actions
aiogram_max-1.4.0-py3-none-any.whl Python 3 none any Details for aiogram_max-1.4.0-py3-none-any.whl

Total release size: 181.1 kB

Release files / aiogram_max-1.4.0.tar.gz

Download URL aiogram_max-1.4.0.tar.gz
Size 137.1 kB
Tags Source
SHA-256 checksum
How to use checksums
22b40f76bef2f7550ba4c29621365d7f49d02cca98d01116ddeb2a230c26667c
BLAKE2b-256 checksum
How to use checksums
ddc3bea6af53d9414b52bbd470187684eeb3b895968a3f6dcc3e0d288bcfed7e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / aiogram_max-1.4.0-py3-none-any.whl

Download URL aiogram_max-1.4.0-py3-none-any.whl
Size 44.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
dfb1ac821a9072c8348b947284fc5f0eea3528f307b94e03919244bf53ddb688
BLAKE2b-256 checksum
How to use checksums
3d62a0d1b6ef630c32b3c75c4ba07835878d0fb32f9a5699eda6820d09de2233
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for aiogram-max 1.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page