A professional Telegram moderation tool built with Python and Aiogram 3. This bot provides automatic profanity filtering, anti-spam protection, and advanced administrative tools to keep your group chats clean and safe. Fully containerized with Docker Compose.
- 🛡️ Join Captcha: Automated anti-bot verification for new members.
- 🚀 Automated Moderation: Real-time scanning for prohibited keywords and external links.
- 🚫 Anti-Advertising: Automatically detects and removes Telegram invitation links.
- 📊 User Statistics: Track mutes, bans, warning history, and message count.
- 📜 Moderation Logs: Dedicated channel logging for all administrative actions.
- 🔧 Modular Architecture: Decoupled handlers and services for high maintainability.
⚠️ Smart Warning System: Configurable warning limits (default: 5) leading to auto-mutes.- 📈 Progressive Mutes: Restriction durations that scale based on violation history.
- 🛠️ Admin Toolkit: Comprehensive commands for manual moderation and filter management.
graph TD
subgraph Core[Bot Entry Point]
A[app/app.py]
end
subgraph Config[Central Configuration]
CFG[app/config/config.py]
STR[app/config/strings.py]
LOG_CFG[app/config/logging_config.py]
end
subgraph Handlers[Modular Handlers]
H_MOD[moderation.py]
H_CAP[captcha.py]
H_LST[lists.py]
H_REP[reports.py]
H_FADMIN[filter_admin.py]
H_PRIV[user_private.py]
H_USR[user.py]
end
subgraph Services[Business Logic]
S_REST[restriction_service.py]
S_HIST[history_service.py]
S_LOG[log_service.py]
S_CAP[captcha_service.py]
S_FILT[filters_service.py]
end
subgraph Data[Persistence & Middlewares]
DB[(app/database/)]
MID[app/middlewares/]
UTL(app/utils/)
end
A --> Config
A --> Handlers
Handlers --> Services
Services --> Data
Handlers --> Data
A --> MID
📦 Telegram-Moderation-Bot
┣ 📂 app
┃ ┣ 📂 config # Configuration, strings, and logging setup
┃ ┣ 📂 database # SQLAlchemy models, SQLite, and banwords
┃ ┣ 📂 filters # Admin validation and chat-type filters
┃ ┣ 📂 handlers # Modular routers (Moderation, Captcha, Filters, etc.)
┃ ┣ 📂 middlewares # DB session and Statistics middlewares
┃ ┣ 📂 services # Core business logic (Restrictions, History, Filters)
┃ ┣ 📂 utils # Helper functions (Time parsing, Text normalization)
┃ ┣ 📜 app.py # Main entry point & dispatcher configuration
┃ ┣ 📜 requirements.txt # Project dependencies
┃ ┗ 📜 .env # Environment variables
┣ 📜 docker-compose.yml # Docker orchestration
┗ 📜 LICENSE # MIT License
/start— Start the bot and get an overview./help— Detailed guide on how to use commands./stats— View your personal statistics./about— Technical information about the bot./how_use_bot— Step-by-step setup instructions.
/set_admin_chat— Configure current chat for admin logs./unset_admin_chat— Disable admin logging for current chat./warn— Issue a warning (Reply required)./unwarn— Remove one warning (Reply required)./mute [duration/ID] [set] [reason]— Mute a user./unmute [ID]— Lift a mute./ban [duration/ID] [set] [reason]— Ban a user./unban [ID]— Lift a ban./addfilter [word]— Add a word to the profanity filter./removefilter [word]— Remove a word from the filter./mute_list [current]— View mute history./ban_list [current]— View ban history./warn_list— View warning history.
/report— Report a message to admins (Reply required)./stats— View your stats in the current chat.
- Clone the repository:
git clone https://github.com/kapusta123b/Telegram-Moderation-Bot cd Telegram-Moderation-Bot - Configure environment:
Create
app/.envand add your token:BOT_TOKEN=your_bot_token_here
- Launch with Docker Compose:
docker-compose up -d --build
- Clone the repository:
git clone https://github.com/kapusta123b/Telegram-Moderation-Bot cd Telegram-Moderation-Bot - Install dependencies:
pip install -r app/requirements.txt
- Configure environment:
Create
app/.env:BOT_TOKEN=your_bot_token_here
- Run the bot:
cd app python app.py
This bot uses a keyword-matching system. You can manage the filter list directly using /addfilter and /removefilter commands in your group, or by manually editing app/database/banwords.txt.
Made with ❤️ for clean communities