Telegram Scam Detection Bot 🕵️‍♂️

A Python-based digital forensic tool that helps detect potential scams in Telegram groups using AI-powered analysis.

📋 Overview

This bot analyzes forwarded messages from Telegram groups to identify potential scam activities. Using Groq AI, it examines message patterns, content, and various fraud indicators to provide a comprehensive risk assessment.

🚀 Quick Start

Prerequisites

• Python 3.8 or higher
• Telegram account
• Groq API key
• Telegram Bot token

Installation Steps

1. Clone and Setup

   # Create and enter project directory
   git clone https://github.com/yourusername/telegram-scam-detector.git
   cd telegram-scam-detector
   
   # Create virtual environment
   python -m venv myenv
   
   # Activate virtual environment
   # For Windows:
   myenv\Scripts\activate
   # For Linux/Mac:
   source myenv/bin/activate
   
   # Install dependencies
   pip install -r requirements.txt

2. Configuration

   • Create a .env file in project root
   • Add your API keys:

     TELEGRAM_BOT_TOKEN=your_telegram_bot_token
     GROQ_API_KEY=your_groq_api_key
     

   • Get your API keys:
     • Groq API key: https://console.groq.com/keys
     • Telegram Bot token: Message @BotFather on Telegram

3. Start the Bot

   python bot.py

💡 How to Use

1. Start Interaction

   • Find your bot on Telegram
   • Send /start to initialize

2. Analyze Messages

   • Type /identify to begin analysis
   • Forward at least 5 messages from suspicious group
   • Wait for analysis results
   • Use /cancel to stop analysis

📊 Analysis Features

What We Detect

• Social engineering tactics
• Urgency/pressure tactics
• Suspicious links and domains
• Requests for sensitive information
• Unusual language patterns
• Cryptocurrency/payment references

Risk Levels

• 🟢 LOW: Minimal risk detected
• 🟡 MEDIUM: Some suspicious elements
• 🔴 HIGH: Multiple scam indicators
• ⚫ CRITICAL: Clear evidence of scam

Analysis Output

• Risk level assessment
• Scam probability percentage
• Identified forensic indicators
• Extracted suspicious elements
• Pattern analysis
• Recommended actions

📁 Logging System

Analysis results are automatically saved in JSON format:

forensic_logs/
└── analysis_YYYYMMDD_HHMMSS_USER_ID.json

⚙️ Project Structure

telegram-scam-detector/
├── bot.py              # Main bot implementation
├── .env               # Environment variables (create this)
├── requirements.txt   # Python dependencies
├── README.md         # Documentation
├── .gitignore        # Git ignore rules
└── forensic_logs/    # Analysis logs directory

📦 Dependencies

This project requires the following Python packages:

python-telegram-bot==21.10
groq==0.15.0
python-dotenv==1.0.0

You can install all dependencies using:

pip install -r requirements.txt

⚠️ Troubleshooting

Common issues and solutions:

1. ModuleNotFoundError:

   pip install -r requirements.txt

2. Environment Variables:

   • Ensure .env file exists
   • Check API keys are correct
   • No quotes around values

3. Bot Not Responding:

   • Check internet connection
   • Verify bot is running
   • Confirm Groq API service status

4. Message Analysis Failed:

   • Ensure messages are forwarded, not copied
   • Check minimum 5 messages requirement
   • Verify Groq API key validity

🤝 Support

Need help?

• Open an issue on GitHub
• Check existing issues
• Review documentation

⚖️ Disclaimer

This tool provides forensic analysis for educational and protective purposes. Analysis results should be used as guidance, not as definitive proof. Always exercise personal judgment when dealing with suspicious messages.

📝 License

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