Filter.AI

AI-powered spam detection and moderation bot for Telegram groups using Google Gemini.

Overview

Filter.AI is an intelligent Telegram bot that helps keep your group chats clean and civilized. Using Google's Gemini AI, it analyzes reported messages to detect spam content, automatically banning offenders and maintaining a detailed log of all actions.

Features

• AI-Powered Analysis: Leverages Google Gemini 2.5 Flash for intelligent message classification
• Automatic Moderation: Bans users and deletes messages identified as spam
• Detailed Logging: Maintains a CSV(for local) and @t.me/filterAiLogs for production log of all banned users with timestamps and reasons
• Simple Commands: Easy-to-use interface with /start and /report commands
• Privacy-Focused: Only analyzes messages when explicitly reported by group members

Getting Started

Prerequisites

• Python 3.7 or higher
• A Telegram Bot Token (from @BotFather)
• A Google Gemini API Key (from Google AI Studio)

Installation

1. Clone the repository

   git clone https://github.com/iput-object/Filter.Ai.git
   cd Filter.Ai

2. Install dependencies

   pip install -r requirements.txt

3. Configure environment variables

   cp .env.example .env

   Edit .env and add your credentials:

   TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here
   GEMINI_API_KEY=your_gemini_api_key_here
   TELEGRAM_LOG_CHANNEL=your_telegram_log_channel_id_here
   ENVIRONMENT=your_build_environment_here #PRODUCTION OR DEVELOPMENT
   

4. Run the bot

   python main.py

Running with Docker.

Local Deployment

docker compose up --build filterai-local

• Uses .env file for credentials.
• Stops and removes safely:

docker compose down filterai-local

---

Production Deployment

docker compose up -d filterai-production

• Uses environment variables injected by your hosting platform (e.g., Railway).
• .env is ignored in production.
• Stop and remove production container safely:

docker compose stop filterai-production
docker compose rm filterai-production

---

Services Overview

Service	Description	Environment
filterai-local	Local testing/debugging	.env (local)
filterai-production	Production deployment	Hosting platform env vars

---

Usage

Setting Up in Your Group

1. Add the bot to your Telegram group
2. Promote the bot to admin with the following permissions:
   • Delete messages
   • Ban users

Commands

• /start - Display help and documentation
• /report - Report a message (must be used as a reply to the message you want to report)

How It Works

1. A user replies to a suspicious message with /report
2. The bot analyzes the message content using Gemini AI
3. If classified as "spam":
   • The message is deleted
   • The user is banned from the group
   • The incident is logged to banned_logs.csv or to @t.me/filterAiLogs
4. If the message is safe, the bot notifies that no action is needed

Logging

LOCAL: All ban actions are logged to banned_logs.csv with the following information:

• Timestamp
• User ID
• Username
• Reason (spam)
• Message content PRODUCTION: All bans will be logged to @t.me/filterAiLogs (Depends on the CHANNEL_ID)

Technical Details

Dependencies

• python-telegram-bot - Telegram Bot API wrapper
• google-generativeai - Google Gemini AI integration
• python-dotenv - Environment variable management

Project Structure

Filter.Ai/
├── main.py              # Main bot application
├── requirements.txt     # Python dependencies
├── .env.example        # Environment variables template
├── .gitignore          # Git ignore rules
├── LICENSE             # Project license
├── README.md           # This file
└── banned_logs.csv     # Ban logs (generated at runtime)

Contributing

Contributions are welcome! Feel free to:

• Report bugs
• Suggest new features
• Submit pull requests
• Improve documentation

How to Contribute

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Limitations

• Currently only analyzes texts & captions messages
• Depends on Gemini AI availability and API limits

Future Enhancements

• Support for analyzing images and media
• Customizable sensitivity levels
• Dashboard for viewing ban statistics
• Whitelist/blacklist functionality

Support

Considerably give a Star to the Repo and have fun ✨

Acknowledgments

• python-telegram-bot - Telegram Bot API wrapper
• Google Gemini - AI model for content analysis

---

Made with ❤️ for safer Telegram communities