maxapi 1.2.1

Библиотека для разработки чат-ботов с помощью API мессенджера MAX

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())