Telegram Moderation Bot

Telegram bot for group moderation built with Python and Aiogram 3.

Features

• Profanity filter
• Telegram invite link detection
• Warning system
• Auto mute after warning limit
• Progressive mute durations
• Join captcha
• Moderation logs
• User statistics
• Admin moderation commands
• Modular project structure

---

Stack

• Python 3.10+
• Aiogram 3
• SQLAlchemy
• SQLite
• Docker / Docker Compose

---

Project Structure

Telegram-Moderation-Bot
├── app
│   ├── config
│   ├── database
│   ├── filters
│   ├── handlers
│   ├── middlewares
│   ├── services
│   ├── utils
│   ├── app.py
│   ├── requirements.txt
│   └── .env
├── docker-compose.yml
└── LICENSE

---

Commands

Private Chat

Command	Description
/start	Start bot
/help	Show help
/stats	Show personal statistics
/about	Show project information
/how_use_bot	Show setup instructions

---

Admin Commands

Command	Description
/set_admin_chat	Set moderation log chat
/unset_admin_chat	Disable moderation logs
/warn	Add warning
/unwarn	Remove warning
/mute	Mute user
/unmute	Remove mute
/ban	Ban user
/unban	Remove ban
/addfilter	Add banned word
/removefilter	Remove banned word
/mute_list	Show mute history
/ban_list	Show ban history
/warn_list	Show warning history

Examples

/warn
/mute 30m spam
/ban 7d advertising
/addfilter badword

---

Public Commands

Command	Description
/report	Report message to admins
/stats	Show user statistics

---

Installation

Docker

Clone repository:

git clone https://github.com/kapusta123b/Telegram-Moderation-Bot
cd Telegram-Moderation-Bot

Create app/.env:

BOT_TOKEN=your_bot_token

Run container:

docker-compose up -d --build

Stop container:

docker-compose down

---

Manual Installation

Clone repository:

git clone https://github.com/kapusta123b/Telegram-Moderation-Bot
cd Telegram-Moderation-Bot

Create virtual environment:

python -m venv venv

Activate virtual environment:

Linux

source venv/bin/activate

Windows

venv\Scripts\activate

Install dependencies:

pip install -r app/requirements.txt

Create app/.env:

BOT_TOKEN=your_bot_token

Run bot:

cd app
python app.py

---

Notes

Filter words are stored in:

app/database/banwords.txt

You can also manage filters directly from Telegram using:

/addfilter
/removefilter