Документация и ссылки
- Документация 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())
1 maintainer
Metadata
1 maintainer
Release files for maxapi 1.2.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| maxapi-1.2.2.tar.gz | 228.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| maxapi-1.2.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 457.0 kB
Release files / maxapi-1.2.2.tar.gz
| Download URL | maxapi-1.2.2.tar.gz |
|---|---|
| Size | 228.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
86f337681dc02036997d74c6e589728b0d0f6cfd4d6025db1e4e95eb9c25423d
|
|
BLAKE2b-256 checksum How to use checksums |
20cbc9afac78787b8c0b8091faee292b957a7c8c8648d6fd7645bcfe3869ea3f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 15, 2026.
Transparency logRelease files / maxapi-1.2.2-py3-none-any.whl
| Download URL | maxapi-1.2.2-py3-none-any.whl |
|---|---|
| Size | 228.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e01975da7ffe002624450c14cd49d2820b917c95bba81a8c59424e55ba3faee0
|
|
BLAKE2b-256 checksum How to use checksums |
2eba976a1386e79510b63f934bf48ffb38a939dbbd5c72705d8b668f4a9a066f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 15, 2026.
Transparency log
