All source listed below is under MIT license if no LICENSE file stating different is available.

Telegram Scambaiter Bot

An intelligent bot that automatically engages with scammers using a believable persona to waste their time and protect others. The bot uses Marcus - a 35-year-old lonely guy with a Brabus 900 who's terrible with tech but has money to spend.

Features

Core Functionality

  • Automatic Scammer Detection: Anyone not in your contacts is treated as a scammer
  • Realistic Persona: Marcus is desperate, lonely, has money, but struggles with technology
  • Adaptive Learning: Bot learns from conversations and adapts strategies
  • Realistic Timing: 1-5 minute response delays with typing indicators
  • 24/7 Operation: Works day and night automatically

Advanced Features

  • Scammer Type Detection: Identifies romance, crypto, inheritance, lottery scams
  • Conversation Analytics: Tracks engagement and time wasted
  • Adaptive Strategies: Different approaches based on scammer type
  • Fallback Responses: Handles API failures gracefully
  • Memory Management: Cleans up old conversations

Quick Start

1. Prerequisites

  • Python 3.8+
  • Telegram account
  • X.AI (Grok) API key

2. Get API Credentials

Telegram API:

  1. Go to https://my.telegram.org/apps
  2. Create a new application
  3. Note down api_id and api_hash

Grok API:

  1. Go to https://console.x.ai/
  2. Create account and get API key

3. Installation

# Clone the repository (or copy files to your directory)
cd ae

# Install dependencies
pip install -r requirements.txt

# Copy environment template
cp .env.example .env

# Edit .env with your credentials
nano .env

4. Configuration

Edit .env file:

# Telegram API credentials
TELEGRAM_API_ID=12345678
TELEGRAM_API_HASH=your_hash_here
TELEGRAM_PHONE=+1234567890

# Grok API key
GROK_API_KEY=your_grok_key_here

5. Run the Bot

python scambaiter_bot.py

On first run, you'll need to verify your phone number with Telegram.

Meet Marcus - Your Scambaiting Persona

Marcus is a carefully crafted character designed to be the perfect scammer target:

Personality Traits

  • 35 years old, lonely bachelor
  • Works from home (vague IT job)
  • Drives a Brabus 900 (expensive Mercedes)
  • Has money but doesn't know how to attract women
  • Terrible with technology despite working in IT
  • Gets excited when attractive women message him
  • Overthinks responses and makes typos when excited

Conversation Patterns

  • Asks lots of questions to keep conversations going
  • Complains about navigation system problems
  • Mentions expensive purchases awkwardly
  • Shows interest in meeting up (but desperately)
  • Asks for photos
  • Makes spelling mistakes when excited

Safety Features

  • Never shares real personal information
  • Uses only fake details consistently
  • Designed to be obviously fake to real people
  • Perfect bait for scammers

Learning & Analytics

The bot includes sophisticated learning capabilities:

Scammer Type Detection

  • Romance Scams: Lonely, beautiful, love, relationship
  • Crypto Scams: Bitcoin, investment, trading, profit
  • Inheritance Scams: Million, lawyer, deceased, beneficiary
  • Lottery Scams: Winner, prize, congratulations
  • Tech Support: Microsoft, virus, refund

Adaptive Strategies

  • Romance Scammers: Extra lonely/desperate responses
  • Crypto Scammers: Show interest but ask basic questions
  • Inheritance Scammers: Excited but worried about legality

Performance Tracking

  • Total scammers engaged
  • Messages received/sent
  • Time wasted (in minutes)
  • Conversation lengths
  • Engagement scores

Advanced Configuration

Timing Adjustments

Edit scambaiter_bot.py:

self.min_response_time = 60   # Minimum 1 minute
self.max_response_time = 300  # Maximum 5 minutes

Persona Modifications

Edit persona_prompt.txt to adjust Marcus's personality or add new details.

Contact Detection

The bot automatically loads your Telegram contacts. Anyone not in contacts is treated as a scammer.

Logs & Monitoring

Log Files

  • scambaiter.log: Detailed operation logs
  • conversation_stats.json: Analytics and learning data

Monitoring

# Watch logs in real-time
tail -f scambaiter.log

# Check conversation statistics
python -c "
from conversation_manager import ConversationAnalyzer
analyzer = ConversationAnalyzer()
print(analyzer.get_conversation_summary())
"

Troubleshooting

Common Issues

"Missing environment variables"

  • Check .env file exists and has correct credentials
  • Ensure no spaces around = in .env

"Grok API error"

  • Verify API key is correct
  • Check account has available credits
  • Try again after a few minutes

"Not detecting contacts"

  • Make sure contacts are properly synced in Telegram
  • Check bot has permission to access contacts

"Too fast/slow responses"

  • Adjust min_response_time and max_response_time
  • Check delay_factor in conversation analytics

Legal & Ethical Considerations

Legal

  • This is for educational and defensive purposes only
  • Scambaiting may be illegal in some jurisdictions
  • Use at your own risk and check local laws

Ethical Guidelines

  • Only targets unsolicited messages from unknown contacts
  • Designed to waste scammer time, not cause harm
  • Protects others by occupying scammer resources
  • Never attempts to extract personal information

Safety

  • Uses only fake persona details
  • Never shares real personal information
  • Automatically obvious to legitimate contacts
  • Logs all interactions for transparency

Contributing

Feel free to improve the system:

Persona Enhancements

  • Add new personality traits
  • Create conversation variations
  • Improve believability

Technical Improvements

  • Add new scammer type detection
  • Improve learning algorithms
  • Enhance error handling

Analytics

  • Better engagement metrics
  • Conversation effectiveness scoring
  • Response optimization

Expected Results

Typical Performance

  • Response Rate: 95%+ of scammers engage
  • Time Wasted: 10-30 minutes per scammer
  • Detection Accuracy: 99%+ (non-contacts = scammers)
  • Believability: High for scammers, obvious for real people

Success Metrics

  • Length of conversations (longer = better)
  • Number of follow-up messages from scammers
  • Time spent by scammers before giving up
  • Variety of response types

Have Fun!

Remember, you're not just wasting scammer time - you're protecting others by keeping scammers busy with fake targets instead of real victims. Every minute a scammer spends talking to Marcus is a minute they're not scamming someone vulnerable.

The bot runs 24/7, so Marcus never sleeps and is always ready to chat with his new "friends" about his Brabus navigation problems!

Disclaimer: This tool is for educational and defensive purposes. Users are responsible for complying with all applicable laws and regulations in their jurisdiction. - Haha, i'm joking. I don't care. Come to the dark side.

src/marcus
.env.example
.gitignore
LICENSE
MANIFEST.in
pyproject.toml
README.md