maxapi 1.2.3

MAX Чат • TG Чат

Документация и ссылки

• Документация maxapi: https://love-apples.github.io/maxapi/
• Официальная документация MAX Bot API: https://dev.max.ru/docs-api/
• Примеры ботов: https://love-apples.github.io/maxapi/examples/

Возможности

• Асинхронный Bot с тонкими обёртками над методами MAX Bot API.
• Dispatcher, Router, фильтры, F и middleware в стиле aiogram.
• FSM-контекст через MemoryContext и RedisContext.
• Polling и webhook через aiohttp, FastAPI или Litestar.
• Работа с медиа: загрузка, отправка и скачивание файлов.
• Inline-кнопки, callbacks и типизированные callback payloads.

Установка из PyPI

Стабильная версия

pip install maxapi

Если проект управляется через uv:

uv add maxapi

Установка из GitHub

Свежая версия, возможны баги. Рекомендуется только для ознакомления с новыми коммитами.

pip install git+https://github.com/love-apples/maxapi.git

Быстрый старт

Если вы тестируете бота в чате - не забудьте дать ему права администратора!

Запуск Polling

⚠️ Long Polling ограничен по скорости и сроку хранения событий и не подходит для production-окружения. Для боевого окружения используйте Webhook.

Если у бота есть активные Webhook-подписки, события не будут приходить через start_polling. Перед переходом на polling удалите подписки через await bot.delete_webhook().

import asyncio
import logging

from maxapi import Bot, Dispatcher, F
from maxapi.filters.command import CommandStart
from maxapi.types import BotStarted, MessageCreated

logging.basicConfig(level=logging.INFO)

# Внесите токен бота в переменную окружения MAX_BOT_TOKEN
# Не забудьте загрузить переменные из .env в os.environ
# или задайте его аргументом в Bot(token='...')
bot = Bot()
dp = Dispatcher()


# Ответ бота при нажатии на кнопку "Начать"
@dp.bot_started()
async def bot_started(event: BotStarted):
    await bot.send_message(
        chat_id=event.chat_id, text="Привет! Отправь мне /start"
    )


# Ответ бота на команду /start
@dp.message_created(CommandStart())
async def hello(event: MessageCreated):
    await event.message.answer("Пример чат-бота для MAX 💙")


@dp.message_created(F.message.body.text)
async def echo(event: MessageCreated):
    await event.message.answer(event.message.body.text)


async def main():
    await dp.start_polling(bot)


if __name__ == "__main__":
    asyncio.run(main())

Запуск Webhook

🔒 С 25.05.2026 прекращается поддержка получения вебхуков по HTTP и самоподписных сертификатов. Используйте HTTPS и сертификаты, выданные доверенным центром сертификации.

Webhook работает «из коробки» — aiohttp уже включён в базовый пакет:

pip install maxapi

Для проекта на uv:

uv add maxapi

Ниже простой запуск через aiohttp. Для production-интеграции с FastAPI, подпиской webhook и проверкой secret смотрите пример 09_webhook_bot.py.

import asyncio
import logging

from maxapi import Bot, Dispatcher
from maxapi.filters.command import CommandStart
from maxapi.types import MessageCreated

logging.basicConfig(level=logging.INFO)

bot = Bot()
dp = Dispatcher()


# Команда /start боту
@dp.message_created(CommandStart())
async def hello(event: MessageCreated):
    await event.message.answer("Привет из вебхука!")


async def main():
    await dp.handle_webhook(
        bot=bot,
        host="0.0.0.0",
        port=8080,
    )


if __name__ == "__main__":
    asyncio.run(main())

FastAPI и Litestar

Если хотите использовать FastAPI или Litestar вместо aiohttp, установите нужную опциональную зависимость через pip:

pip install "maxapi[fastapi]"
pip install "maxapi[litestar]"

Или через uv:

uv add "maxapi[fastapi]"
uv add "maxapi[litestar]"

Пример запуска через FastAPI:

import asyncio
import uvicorn
from fastapi import FastAPI
from maxapi.webhook.fastapi import FastAPIMaxWebhook


async def main():
    webhook = FastAPIMaxWebhook(dp=dp, bot=bot)
    app = FastAPI(lifespan=webhook.lifespan)
    webhook.setup(app, path="/webhook")
    await uvicorn.Server(
        uvicorn.Config(app, host="0.0.0.0", port=8080)
    ).serve()


asyncio.run(main())

Пример запуска через Litestar:

import asyncio
import uvicorn
from maxapi.webhook.litestar import LitestarMaxWebhook


async def main():
    webhook = LitestarMaxWebhook(dp=dp, bot=bot)
    app = webhook.create_app(path="/webhook")
    await uvicorn.Server(
        uvicorn.Config(app, host="0.0.0.0", port=8080)
    ).serve()


asyncio.run(main())

Разработка и релиз

• Окружение: uv sync. Перед PR: make run-test (ruff, mypy, pytest) и make check-ci (сборка пакета, actionlint, zizmor). Подробности и соглашения — в AGENTS.md.
• После правки зависимостей в pyproject.toml обновите lock: uv lock. CI ставит инструменты с --locked и упадёт на рассинхроне.
• Релиз: uv version --bump patch (или minor/major) обновляет версию в pyproject.toml и uv.lock вместе; после мержа в main публикация на PyPI, тег и GitHub Release создаются автоматически, если такой версии на PyPI ещё нет. Если шаг после загрузки на PyPI упал, помогает «Re-run failed jobs» того же run: шаги тега и release идемпотентны. Свежий запуск увидит версию на PyPI и ничего не сделает.