Skip to content

MrConsoleka/aiogram-bot-template

Repository files navigation

image

Aiogram Bot Template

Static Badge Static Badge Static Badge
Static Badge

πŸ“Œ Description

β €

Aiogram Bot Template β€” This template helps you quickly bootstrap Telegram bots on the aiogram 3.x stack. It already includes a ready project structure, command and message handlers, optional PostgreSQL/Redis integration, logging with loguru, internationalization, support for aiogram-dialog, and dependency injection via dishka with optional webhook handling on FastAPI. The template is designed to remove routine setup and let you focus on your bot’s logic.

β €

πŸ”¨ Functions

β €

  • /start - Start the bot
  • /language - Change language
  • /help - Help
  • /admin - Command for administrators
  • /dialog - Demo dialog using aiogram-dialog
  • /fsm - Demo finite state machine form

β €

πŸ—‚οΈ Template structure

β €

πŸ“ aiogram_bot_template/
β”œβ”€β”€β”€β” πŸ“‚ .github/
β”‚   └───┐ πŸ“‚ ISSUE_TEMPLATE/
β”‚       β”œβ”€β”€ bug_report.md
β”‚       └── feature_request.md
β”‚
β”œβ”€β”€β”€β” πŸ“‚ source/
β”‚   β”œβ”€β”€β”€β” πŸ“‚ config/
β”‚   β”‚   β”œβ”€β”€ __init__.py
β”‚   β”‚   └── config_reader.py
β”‚   β”‚
β”‚   β”œβ”€β”€β”€β” πŸ“‚ constants/
β”‚   β”‚   β”œβ”€β”€ __init__.py
β”‚   β”‚   β”œβ”€β”€ throttling.py
β”‚   β”‚   └── logging.py
β”‚   β”‚
β”‚   β”œβ”€β”€β”€β” πŸ“‚ data/
β”‚   β”‚   β”œβ”€β”€ __init__.py
β”‚   β”‚   β”œβ”€β”€ πŸ“‚ error_logs/
β”‚   β”‚   └── πŸ“‚ full_logs/
β”‚   β”‚
β”‚   β”œβ”€β”€β”€β” πŸ“‚ database/
β”‚   β”‚   β”œβ”€β”€β”€β” πŸ“‚ core/
β”‚   β”‚   β”‚   β”œβ”€β”€ __init__.py
β”‚   β”‚   β”‚   └── manager.py
β”‚   β”‚   β”‚
β”‚   β”‚   β”œβ”€β”€β”€β” πŸ“‚ models/
β”‚   β”‚   β”‚   β”œβ”€β”€ __init__.py
β”‚   β”‚   β”‚   β”œβ”€β”€ base.py
β”‚   β”‚   β”‚   └── user.py
β”‚   β”‚   β”‚
β”‚   β”‚   β”œβ”€β”€β”€β” πŸ“‚ repositories/
β”‚   β”‚   β”‚   β”œβ”€β”€ __init__.py
β”‚   β”‚   β”‚   β”œβ”€β”€ base.py
β”‚   β”‚   β”‚   └── user.py
β”‚   β”‚   β”‚
β”‚   β”‚   β”œβ”€β”€β”€β” πŸ“‚ tools/
β”‚   β”‚   β”‚   β”œβ”€β”€ __init__.py
β”‚   β”‚   β”‚   β”œβ”€β”€ mixin.py
β”‚   β”‚   β”‚   └── uow.py
β”‚   β”‚   β”‚
β”‚   β”‚   └── __init__.py
β”‚   β”‚
β”‚   β”œβ”€β”€β”€β” πŸ“‚ enums/
β”‚   β”‚   β”œβ”€β”€ __init__.py
β”‚   β”‚   └── roles.py
β”‚   β”‚
β”‚   β”œβ”€β”€β”€β” πŸ“‚ factory/
β”‚   β”‚   β”œβ”€β”€ __init__.py
β”‚   β”‚   β”œβ”€β”€ bot.py
β”‚   β”‚   β”œβ”€β”€ dispatcher.py
β”‚   β”‚   β”œβ”€β”€ dishka.py
β”‚   β”‚   └── server.py
β”‚   β”‚
β”‚   β”œβ”€β”€β”€β” πŸ“‚ locales/
β”‚   β”‚   β”œβ”€β”€β”€β” πŸ“‚ en/
β”‚   β”‚   β”‚   β”œβ”€β”€ buttons.ftl
β”‚   β”‚   β”‚   └── messages.ftl
β”‚   β”‚   └───┐ πŸ“‚ ru/
β”‚   β”‚       β”œβ”€β”€ buttons.ftl
β”‚   β”‚       └── messages.ftl
β”‚   β”‚
β”‚   β”œβ”€β”€β”€β” πŸ“‚ services/
β”‚   β”‚   β”œβ”€β”€ __init__.py
β”‚   β”‚   └── user_service.py
β”‚   β”‚
β”‚   β”œβ”€β”€β”€β” πŸ“‚ telegram/
β”‚   β”‚   β”œβ”€β”€β”€β” πŸ“‚ filters/
β”‚   β”‚   β”‚   β”œβ”€β”€ __init__.py
β”‚   β”‚   β”‚   β”œβ”€β”€ admin_protect.py
β”‚   β”‚   β”‚   └── chat_type.py
β”‚   β”‚   β”‚
β”‚   β”‚   β”œβ”€β”€β”€β” πŸ“‚ handlers/
β”‚   β”‚   β”‚   β”œβ”€β”€β”€β” πŸ“‚ admin/
β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ __init__.py
β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ callbacks.py
β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ commands.py
β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ fsm.py
β”‚   β”‚   β”‚   β”‚   └── messages.py
β”‚   β”‚   β”‚   β”œβ”€β”€β”€β” πŸ“‚ errors/
β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ __init__.py
β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ common.py
β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ orm.py
β”‚   β”‚   β”‚   β”‚   └── telegram.py
β”‚   β”‚   β”‚   └───┐ πŸ“‚ user/
β”‚   β”‚   β”‚       β”œβ”€β”€ __init__.py
β”‚   β”‚   β”‚       β”œβ”€β”€ callbacks.py
β”‚   β”‚   β”‚       β”œβ”€β”€ commands.py
β”‚   β”‚   β”‚       β”œβ”€β”€ fsm.py
β”‚   β”‚   β”‚       └── messages.py
β”‚   β”‚   β”‚
β”‚   β”‚   β”œβ”€β”€β”€β” πŸ“‚ keyboards/
β”‚   β”‚   β”‚   β”œβ”€β”€ __init__.py
β”‚   β”‚   β”‚   β”œβ”€β”€ builder.py
β”‚   β”‚   β”‚   β”œβ”€β”€ callback_factory.py
β”‚   β”‚   β”‚   β”œβ”€β”€ inline.py
β”‚   β”‚   β”‚   └── reply.py
β”‚   β”‚   β”‚
β”‚   β”‚   β”œβ”€β”€β”€β” πŸ“‚ middlewares/
β”‚   β”‚   β”‚   β”œβ”€β”€ __init__.py
β”‚   β”‚   β”‚   β”œβ”€β”€ callback_throttling.py
β”‚   β”‚   β”‚   β”œβ”€β”€ message_throttling.py
β”‚   β”‚   β”‚   └── reporting.py
β”‚   β”‚   β”‚
β”‚   β”‚   β”œβ”€β”€β”€β” πŸ“‚ states/
β”‚   β”‚   β”‚   β”œβ”€β”€ __init__.py
β”‚   β”‚   β”‚   β”œβ”€β”€ dialog.py
β”‚   β”‚   β”‚   └── form.py
β”‚   β”‚   β”‚
β”‚   β”‚   └───┐ πŸ“‚ dialogs/
β”‚   β”‚       β”œβ”€β”€ __init__.py
β”‚   β”‚       └── dialog.py
β”‚   β”‚
β”‚   β”œβ”€β”€β”€β” πŸ“‚ utils/
β”‚   β”‚   β”œβ”€β”€ __init__.py
β”‚   β”‚   β”œβ”€β”€ logger.py
β”‚   β”‚   β”œβ”€β”€ set_commands.py
β”‚   β”‚   └── translator.py
β”‚   β”‚
β”‚   └── πŸ“„ __main__.py
β”‚
β”œβ”€β”€ .env.example
β”œβ”€β”€ .dockerignore
β”œβ”€β”€ .gitignore
β”œβ”€β”€ Dockerfile
β”œβ”€β”€ LICENSE
β”œβ”€β”€ Makefile
β”œβ”€β”€ SECURITY.md
β”œβ”€β”€ docker-compose.yml
β”œβ”€β”€ pyproject.toml
└── README.md

β €

πŸ“‹ About the content

β €

  • πŸ“ source/ - Main application source code.
  • πŸ“ source/config/ - Application configuration settings.
  • πŸ“ source/constants/ - Project constants.
  • πŸ“ source/data/ - Data generated by the application (e.g., logs).
  • πŸ“ source/data/error_logs/ - Log files containing only errors.
  • πŸ“ source/data/full_logs/ - Full log files.
  • πŸ“ source/database/ - Database interaction logic.
  • πŸ“ source/database/core/ - Database core modules (connection, sessions).
  • πŸ“ source/database/models/ - Database model definitions.
  • πŸ“ source/database/repositories/ - Repositories for database data access.
  • πŸ“ source/database/tools/ - Helper tools for working with the database.
  • πŸ“ source/enums/ - Enum definitions.
  • πŸ“ source/factory/ - Factories for creating the bot, dispatcher, webhook server and DI container.
  • πŸ“ source/locales/ - Localization files (translations).
  • πŸ“ source/locales/en/ - English language localization.
  • πŸ“ source/locales/ru/ - Russian language localization.
  • πŸ“ source/services/ - Business logic layer.
  • πŸ“ source/telegram/ - Components related to Telegram and aiogram.
  • πŸ“ source/telegram/filters/ - Custom aiogram filters.
  • πŸ“ source/telegram/handlers/ - Handlers for processing Telegram updates.
  • πŸ“ source/telegram/handlers/admin/ - Handlers for administrators.
  • πŸ“ source/telegram/handlers/errors/ - Error handlers.
  • πŸ“ source/telegram/handlers/user/ - Handlers for users.
  • πŸ“ source/telegram/keyboards/ - Telegram keyboards.
  • πŸ“ source/telegram/middlewares/ - aiogram middlewares (throttling, error reporting).
  • πŸ“ source/telegram/states/ - aiogram FSM states.
  • πŸ“ source/telegram/dialogs/ - Dialog windows built with aiogram-dialog.
  • πŸ“ source/utils/ - Helper utilities (logger setup, commands, translations).
  • πŸ“„ source/__main__.py - Main entry point within the source package.
  • πŸ“„ .env.example - Example file for sensitive data (.env).

β €

βš™οΈ Configuration

β €

Before running the bot, you need to set up your environment variables. Copy the .env.example file to .env and fill in your credentials and settings:

cp .env.example .env
# Then edit the .env file with your configurations

β €

πŸ”“ Bot .env Variables

β €

Environment Variable Name Description
TG__WEBHOOK_USE Boolean value (True/False) indicating whether to use webhooks (True) or long polling (False).
TG__WEBHOOK_PATH Path for Telegram to send webhook updates (appended to WEBHOOK__URL).
TG__BOT_TOKEN Your Telegram bot token, obtained from @BotFather in Telegram.
TG__ADMIN_IDS List of Telegram user IDs (JSON list or comma-separated) who will have administrator rights in the bot.
WEBHOOK__URL Public URL where Telegram will send updates if webhooks are enabled.
WEBHOOK__HOST Host or IP address where the webhook server will listen for incoming connections (usually 0.0.0.0).
WEBHOOK__PORT Port on which the webhook server will listen for incoming connections.
WEBHOOK__PATH Specific path on the server where Telegram will send POST requests with updates.
WEBHOOK__SECRET Secret token that Telegram includes in webhook request headers to verify authenticity.
DB__HOST Database server host.
DB__PORT Port for connecting to the database.
DB__USER Username for database authentication.
DB__PASSWORD Password for database authentication.
DB__NAME Name of the database to connect to.
REDIS__HOST Redis server host used for FSM and/or caching.
REDIS__PORT Port for connecting to the Redis server.
REDIS__USER Username for Redis authentication (if used).
REDIS__PASSWORD Password for Redis authentication (if used).
REDIS__DB Redis database index to use (a number from 0 to 15, default is 0).

β €

πŸ’» Bot Setup

β €

πŸ“¦ Using UV

β €

  1. Clone the repository and navigate into the project directory:

     git clone https://github.com/MrConsoleka/aiogram-bot-template.git
     cd aiogram-bot-template
  2. Ensure you have uv installed. If not, you can install it, for example, using pip:

    pip install uv
  3. Create a virtual environment:

    make venv
  4. Activate the virtual environment:

    # For Linux or macOS:
    source .venv/bin/activate
    
    # For Windows:
    .venv\Scripts\activate
  5. Install dependencies:

    make install
  6. To run the bot, use the command:

    make run

β €

πŸ“¦ Using Docker

β €

  1. Clone the repository and navigate into the project directory:

    git clone https://github.com/MrConsoleka/aiogram-bot-template.git
    cd aiogram-bot-template
  2. Build the Docker Image:

    make docker-build
  3. Run the Project with Docker Compose:

    make docker-up
  4. Verify Bot is Running (Optional):

    make docker-logs

    or

    make docker-logs SERVICE=bot
  5. Stop the Project:

    make docker-down

β €

πŸ“‹ Todo List

β €

  • touch the grass
  • Alembic
  • Aiogram-dialog
  • .github/workflows

β €

πŸ—ƒοΈ Stack of Technologies

β €

β €

πŸ’Ό Credits

β €

β €

πŸ‘€ Author of Aiogram Template Bot

β € Β© Roman Alekseev