Telegram bot template

Best way to create a scalable telegram bot with analytics

✨ Features

• Admin Panel based on Flask-Admin-Dashboard (Flask-Admin + AdminLTE = ❤️ )
• Product Analytics System: using Amplitude or Posthog or Google Analytics
• Performance Monitoring System: using Prometheus and Grafana
• Tracking System: using Sentry
• Seamless use of Docker and Docker Compose
• Export all users in .csv (or .xlsx, .json, yaml from admin panel)
• Configured CI pipeline from git hooks to github actions
• SQLAlchemy V2 is used to communicate with the database
• Database Migrations with Alembic
• Ability to cache using decorator
• Convenient validation using Pydantic V2
• Internationalization (i18n) using GNU gettex and Babel

🚀 How to Use

🐳 Running in Docker (recommended method)

• configure environment variables in .env file

• start services

  docker compose up -d --build

💻 Running on Local Machine

• set environment and install dependencies using uv (you can find branch with Poetry here)

  uv sync --frozen --all-groups

• start the necessary services (at least your database and redis)

• configure environment variables in .env file

• start telegram bot

  uv run python -m bot

• start admin panel

  uv run gunicorn -c admin/gunicorn_conf.py

• make migrations

  uv run alembic upgrade head

🌍 Environment variables

to launch the bot you only need a token bot, database and redis settings, everything else can be left out

name	description
BOT_TOKEN	Telegram bot API token
RATE_LIMIT	Maximum number of requests allowed per minute for rate limiting
DEBUG	Enable or disable debugging mode (e.g., True or False)
USE_WEBHOOK	Flag to indicate whether the bot should use a webhook for updates (e.g., True or False)
WEBHOOK_BASE_URL	Base URL for the webhook
WEBHOOK_PATH	Path to receive updates from Telegram
WEBHOOK_SECRET	Secret key for securing the webhook communication
WEBHOOK_HOST	Hostname or IP address for the main application
WEBHOOK_PORT	Port number for the main application
ADMIN_HOST	Hostname or IP address for the admin panel
ADMIN_PORT	Port number for the admin panel
DEFAULT_ADMIN_EMAIL	Default email for the admin user
DEFAULT_ADMIN_PASSWORD	Default password for the admin user
SECURITY_PASSWORD_HASH	Hashing algorithm for user passwords (e.g., bcrypt)
SECURITY_PASSWORD_SALT	Salt value for user password hashing
DB_HOST	Hostname or IP address of the PostgreSQL database
DB_PORT	Port number for the PostgreSQL database
DB_USER	Username for authenticating with the PostgreSQL database
DB_PASS	Password for authenticating with the PostgreSQL database
DB_NAME	Name of the PostgreSQL database
REDIS_HOST	Hostname or IP address of the Redis database
REDIS_PORT	Port number for the Redis database
REDIS_PASS	Password for authenticating with the Redis database
SENTRY_DSN	Sentry DSN (Data Source Name) for error tracking
AMPLITUDE_API_KEY	API key for Amplitude analytics
POSTHOG_API_KEY	API key for PostHog analytics
PROMETHEUS_PORT	Port number for the Prometheus monitoring system
GRAFANA_PORT	Port number for the Grafana monitoring and visualization platform
GRAFANA_ADMIN_USER	Admin username for accessing Grafana
GRAFANA_ADMIN_PASSWORD	Admin password for accessing Grafana

📂 Project Folder Structure

.
├── admin # Source code for admin panel
│   ├── __init__.py
│   ├── app.py # Main application module for the admin panel
│   ├── config.py # Configuration module for the admin panel
│   ├── Dockerfile # Dockerfile for admin panel
│   ├── gunicorn_conf.py # Gunicorn configuration file for serving admin panel
│   ├── static # Folder for static assets
│   │   ├── css/
│   │   ├── fonts/
│   │   ├── img/
│   │   ├── js/
│   │   └── plugins/
│   ├── templates # HTML templates for the admin panel
│   │   ├── admin/
│   │   ├── index.html
│   │   ├── my_master.html
│   │   └── security/
│   └── views # Custom View modules for handling web requests
│       ├── __init__.py
│       └── users.py
│
├── bot # Source code for Telegram Bot
│   ├── __init__.py
│   ├── __main__.py # Main entry point to launch the bot
│   ├── analytics/ # Interaction with analytics services (e.g., Amplitude or Google Analytics)
│   ├── cache/ # Logic for using Redis cache
│   ├── core/ # Settings for application and other core components
│   ├── database/ # Database functions and SQLAlchemy Models
│   ├── filters/ # Filters for processing incoming messages or updates
│   ├── handlers/ # Handlers for processing user commands and interactions
│   ├── keyboards # Modules for creating custom keyboards
│   │   ├── default_commands.py # Default command keyboards
│   │   ├── __init__.py
│   │   ├── inline/ # Inline keyboards
│   │   └── reply/ # Reply keyboards
│   ├── locales/ # Localization files for supporting multiple languages
│   ├── middlewares/ # Middleware modules for processing incoming updates
│   ├── services/ # Business logic for application
│   └── utils/ # Utility functions and helper modules
│
├── migrations # Database Migrations managed by Alembic
│   ├── env.py # Environment setup for Alembic
│   ├── __init__.py
│   ├── README
│   ├── script.py.mako # Script template for generating migrations
│   └── versions/ # Folder containing individual migration scripts
│
├── configs # Config folder for Monitoring (Prometheus, Node-exporter and Grafana)
│   ├── grafana # Configuration files for Grafana
│   │   └── datasource.yml
│   └── prometheus # Configuration files for Prometheus
│       └── prometheus.yml
│
├── scripts/ # Sripts folder
├── Makefile # List of commands for standard
├── alembic.ini # Configuration file for migrations
├── docker-compose.yml # Docker Compose configuration file for orchestrating containers
├── Dockerfile # Dockerfile for Telegram Bot
├── LICENSE.md # License file for the project
├── uv.lock # Lock file for UV dependency management
├── pyproject.toml # Configuration file for Python projects, including build tools, dependencies, and metadata
└── README.md # Documentation

🔧 Tech Stack

• sqlalchemy — object-relational mapping (ORM) library that provides a set of high-level API for interacting with relational databases
• asyncpg — asynchronous PostgreSQL database client library
• aiogram — asynchronous framework for Telegram Bot API
• flask-admin — simple and extensible administrative interface framework
• loguru — third party library for logging in Python
• uv — development workflow
• docker — to automate deployment
• postgres — powerful, open source object-relational database system
• pgbouncer — connection pooler for PostgreSQL database
• redis — in-memory data structure store used as a cache and FSM
• prometheus — time series database for collecting metrics from various systems
• grafana — visualization and analysis from various sources, including Prometheus

⭐ Star History

👷 Contributing

First off, thanks for taking the time to contribute! Contributions are what makes the open-source community such an amazing place to learn, inspire, and create. Any contributions you make will benefit everybody else and are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork this repository
2. Create a branch
3. Commit your changes
4. Push your commits to the branch
5. Submit a pull request

📝 License

Distributed under the MIT license. See LICENSE for more information.

📢 Contact

donbarbos: donbarbos@proton.me