β
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.
β
β
/start
- Start the bot/language
- Change language/help
- Help/admin
- Command for administrators/dialog
- Demo dialog usingaiogram-dialog
/fsm
- Demo finite state machine form
β
β
π 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
β
β
π 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 andaiogram
.π source/telegram/filters/
- Customaiogram
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 withaiogram-dialog
.π source/utils/
- Helper utilities (logger setup, commands, translations).π source/__main__.py
- Main entry point within thesource
package.π .env.example
- Example file for sensitive data (.env).
β
β
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
β
β
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). |
β
β
β
-
Clone the repository and navigate into the project directory:
git clone https://github.com/MrConsoleka/aiogram-bot-template.git cd aiogram-bot-template
-
Ensure you have
uv
installed. If not, you can install it, for example, usingpip
:pip install uv
-
Create a virtual environment:
make venv
-
Activate the virtual environment:
# For Linux or macOS: source .venv/bin/activate # For Windows: .venv\Scripts\activate
-
Install dependencies:
make install
-
To run the bot, use the command:
make run
β
β
-
Clone the repository and navigate into the project directory:
git clone https://github.com/MrConsoleka/aiogram-bot-template.git cd aiogram-bot-template
-
Build the Docker Image:
make docker-build
-
Run the Project with Docker Compose:
make docker-up
-
Verify Bot is Running (Optional):
make docker-logs
or
make docker-logs SERVICE=bot
-
Stop the Project:
make docker-down
β
β
- touch the grass
- Alembic
- Aiogram-dialog
- .github/workflows
β
β
- aiogram-3x - Asynchronous framework for the Telegram Bot API.
- aiogram-dialog - Dialog manager for building interactive flows.
- dishka - Dependency injection container.
- fastapi & uvicorn - Webhook server stack.
- pydantic & pydantic-settings - Data validation and configuration management.
- postgresql with sqlalchemy and asyncpg - Database layer.
- redis - In-memory data store for FSM and caching.
- loguru - Logging library.
- cachetools & fluentogram - Caching and localization helpers.
- Ruff, Mypy, Pre-commit, Isort, Black - Code quality and formatting tools.
β
β
- aiogram_template - Inspired by Abdullah's project, many thanks to him <3
β
β Β© Roman Alekseev