MAX Bot Template (FastAPI + Docker)

Минимальный, чистый каркас чат-бота для мессенджера MAX, построенный на FastAPI (webhook, асинхронно) и упакованный в Docker.

Это не готовый продукт, а стартовая точка: подключение к API MAX, обработка команды /start, аккуратная структура проекта — то, с чего удобно начинать разработку конкретного бота под свою задачу.

Что внутри

• app/main.py — FastAPI-приложение, эндпоинт /webhook
• app/config.py — конфигурация через переменные окружения
• app/max_client.py — минимальный асинхронный клиент MAX Bot API
• app/handlers.py — обработка входящих апдейтов (пример: /start)
• register_webhook.py — разовая регистрация вебхука в MAX
• Dockerfile + docker-compose.yml — запуск одной командой

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

1. Настроить окружение

cp .env.example .env

Впишите в .env:

• BOT_TOKEN — токен вашего бота из настроек в MAX
• WEBHOOK_URL — публичный HTTPS-адрес вашего сервера + /webhook (например https://your-domain.example.com/webhook; для локальной разработки можно временно использовать ngrok или аналог, чтобы получить публичный HTTPS-туннель)

2. Запустить через Docker

docker compose up --build

Сервис поднимется на порту 8000.

3. Зарегистрировать вебхук в MAX

Выполняется один раз, после того как WEBHOOK_URL стал публично доступен:

python register_webhook.py

4. Проверить

Напишите боту в MAX /start — должен прийти ответ «Привет! Бот работает 🤖».

Запуск без Docker (для разработки)

python -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\Activate.ps1
pip install -r requirements.txt
uvicorn app.main:app --reload

Почему именно так

• FastAPI + вебхук, а не long polling — меньше накладных расходов на сервере, стандартный подход для продакшена.
• Асинхронность (async/await) везде, где идёт сетевой ввод-вывод.
• Docker — проект запускается одной командой на любой машине, без плясок с версиями Python и зависимостями.
• Секреты только через .env — токен бота никогда не хранится в коде.

Что дальше

Этот каркас специально не содержит бизнес-логики — добавляйте свои обработчики в app/handlers.py, свою базу данных, свои сценарии диалога.