CleanAcc - Enhanced Telegram Account Cleaner Bot

Repository: https://github.com/MeherMankar/CleanAcc
Developer: @MeherMankar

A comprehensive Telegram bot for cleaning and managing multiple Telegram accounts with advanced features including progress tracking, error recovery, and security enhancements.

🚀 Features

Core Functionality

• Multi-Account Management: Add and manage multiple Telegram accounts
• Comprehensive Cleanup: Clean personal chats, bot chats, groups, channels, and contacts
• Preview Mode: See what will be deleted before cleanup
• Progress Tracking: Real-time progress updates with detailed metrics
• Error Recovery: Robust error handling with retry mechanisms

Security & Safety

• Input Validation: Comprehensive validation for all user inputs
• Rate Limiting: Prevent abuse with configurable rate limits
• Session Security: Encrypted session storage with validation
• Activity Logging: Complete audit trail of all user actions
• Admin Controls: Advanced admin panel with user management

Performance & Reliability

• Connection Pooling: Efficient database connection management
• Proxy Support: Automatic proxy testing and rotation
• Background Tasks: Health monitoring and maintenance
• Flood Protection: Telegram API rate limit handling
• Graceful Degradation: Continues operation even with partial failures

📋 Requirements

• Python 3.8+
• Redis Server
• SQLite (included)
• Telegram Bot Token
• Telegram API credentials

🛠️ Installation (Step-by-Step for Beginners)

Step 1: Download the Code

git clone https://github.com/MeherMankar/CleanAcc.git
cd CleanAcc

Step 2: Install Python Dependencies

pip install -r requirements.txt

Step 3: Get Your Bot Credentials

3.1 Create a Telegram Bot

1. Open Telegram and message @BotFather
2. Send /newbot command
3. Choose a name for your bot (e.g., "My CleanAcc Bot")
4. Choose a username ending in "bot" (e.g., "mycleanaccbot")
5. Copy the bot token (looks like: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)

3.2 Get Telegram API Credentials

1. Go to https://my.telegram.org
2. Login with your phone number
3. Click "API Development Tools"
4. Fill the form:
   • App title: CleanAcc Bot
   • Short name: cleanaccbot
   • Platform: Desktop
5. Copy your api_id (number like: 12345678)
6. Copy your api_hash (text like: abcdef1234567890abcdef1234567890)

3.3 Get Your Telegram ID

1. Message @userinfobot on Telegram
2. Copy your ID number (like: 123456789)

Step 4: Setup Configuration

1. Copy .env.example to .env:

   cp .env.example .env

2. Open .env file in any text editor
3. Replace the placeholder values:

   BOT_TOKEN=paste_your_bot_token_here
   API_ID=paste_your_api_id_here
   API_HASH=paste_your_api_hash_here
   ADMIN_IDS=paste_your_telegram_id_here

Step 5: Install Redis (Optional but Recommended)

Windows:

1. Download Redis from https://redis.io/download
2. Install and start Redis service

Linux/Mac:

# Ubuntu/Debian
sudo apt install redis-server
sudo systemctl start redis

# Mac with Homebrew
brew install redis
brew services start redis

Step 6: Run the Bot

python main.py

If you see "Bot initialized" - congratulations! Your bot is running! 🎉

⚙️ Configuration

Required Environment Variables

# Bot Configuration (REQUIRED)
BOT_TOKEN=your_bot_token_here
API_ID=your_api_id_here
API_HASH=your_api_hash_here
ADMIN_IDS=123456789,987654321

# Database Configuration
DATABASE_PATH=bot_database.db
DATABASE_POOL_SIZE=10

# Redis Configuration
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

# Rate Limiting
RATE_LIMIT_REQUESTS=10
RATE_LIMIT_WINDOW=60

# Cleanup Configuration
MAX_CLEANUP_BATCH_SIZE=50
CLEANUP_DELAY_SECONDS=0.5

# Logging
LOG_LEVEL=INFO
LOG_FILE=bot.log

Optional Configuration

• Proxy Settings: Configure proxy list URL for account protection
• Sessions Directory: Custom location for session files
• Logging: Adjust log levels and file locations

🚀 Running the Bot

1. Start Redis server

   redis-server

2. Run the bot

   python main.py

3. Monitor logs

   tail -f logs/bot.log

📱 Usage

Adding Accounts

1. Start the bot with /start
2. Click "➕ Add Account"
3. Enter phone number in international format
4. Enter verification code
5. Complete 2FA if enabled

Cleaning Accounts

1. Go to "🧹 Clean Account"
2. Select account to clean
3. Choose cleanup options
4. Preview changes (recommended)
5. Confirm and start cleanup

Managing Sessions

1. Access "👤 Personal Cabinet"
2. View "📱 My Accounts"
3. Select account for management
4. Clean or delete sessions

🔧 Admin Features

Admin Panel Access

• Use /admin command (admin only)
• View comprehensive statistics
• Manage users and sessions
• Configure proxy settings
• Send broadcasts

User Management

• Ban/unban users
• View user activity logs
• Monitor cleanup operations
• Access detailed statistics

🛡️ Security Features

Input Validation

• Phone number format validation
• Telegram ID validation
• Cleanup settings validation
• URL and filename sanitization

Rate Limiting

• Per-user request limits
• Configurable time windows
• Automatic cooldown periods
• Admin bypass options

Activity Monitoring

• Complete audit trail
• Suspicious activity detection
• Failed attempt tracking
• Admin notifications

📊 Monitoring & Health Checks

Health Monitoring

• Database connectivity
• Redis connectivity
• Proxy availability
• Service status checks

Logging

• Structured logging with levels
• File and console output
• Error tracking
• Performance metrics

Statistics

• User registration trends
• Cleanup operation metrics
• Error rates and types
• System performance data

🔄 Maintenance

Database Maintenance

• Automatic connection pooling
• Transaction management
• Backup recommendations
• Migration support

Proxy Management

• Automatic proxy testing
• Failed proxy removal
• Performance monitoring
• Health statistics

Log Management

• Log rotation
• Archive policies
• Cleanup procedures
• Monitoring alerts

🚨 Troubleshooting (Common Problems & Solutions)

🚫 Bot Won't Start

Error: "Token is invalid!"

• ✅ Solution: Check your BOT_TOKEN in .env file
• Make sure you copied the complete token from @BotFather
• Token should look like: 123456789:ABCdefGHIjklMNOpqrsTUVwxyz

Error: "API_ID is required"

• ✅ Solution: Get API credentials from https://my.telegram.org
• Make sure API_ID is a number (like 12345678)
• Make sure API_HASH is filled (like abcdef1234567890abcdef1234567890)

Error: "Redis connection failed"

• ✅ Solution: This is optional - bot will work without Redis
• To fix: Install Redis server or set REDIS_HOST= (empty) in .env

📱 Bot Commands Not Working

Bot doesn't respond to /start

• Check if bot is running (should show "Bot initialized" message)
• Make sure you're messaging the correct bot
• Try stopping and restarting: Ctrl+C then python main.py

"Access denied" errors

• Make sure your Telegram ID is in ADMIN_IDS in .env file
• Get your ID from @userinfobot

📁 File & Permission Issues

"Permission denied" errors

• Make sure you have write permissions in the bot folder
• Try running as administrator (Windows) or with sudo (Linux/Mac)

"Module not found" errors

• Run: pip install -r requirements.txt
• Make sure you're in the correct folder: cd CleanAcc

🆘 Need Help?

1. Check the logs: Look at logs/bot.log file for detailed error messages
2. Restart the bot: Stop with Ctrl+C and run python main.py again
3. Check your .env file: Make sure all required fields are filled
4. Test your credentials:
   • Message your bot on Telegram
   • Check if @BotFather shows your bot as active
   • Verify API credentials at https://my.telegram.org

Error Recovery

• Automatic retry mechanisms
• Graceful degradation
• Session recovery
• Data consistency checks

📈 Performance Optimization

Database Optimization

• Connection pooling
• Query optimization
• Index management
• Batch operations

Memory Management

• Efficient data structures
• Garbage collection
• Resource cleanup
• Memory monitoring

Network Optimization

• Request batching
• Connection reuse
• Timeout management
• Retry strategies

🔐 Security Best Practices

Deployment Security

• Use environment variables
• Secure file permissions
• Network isolation
• Access controls

Data Protection

• Session encryption
• Secure storage
• Data minimization
• Regular cleanup

Monitoring

• Security event logging
• Anomaly detection
• Access monitoring
• Incident response

📝 Contributing

1. Fork the repository
2. Create feature branch
3. Make changes with tests
4. Submit pull request
5. Follow code review process

📄 License

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

⚠️ Disclaimer

This bot is for educational and legitimate account management purposes only. Users are responsible for complying with Telegram's Terms of Service and applicable laws. The developers are not responsible for any misuse of this software.

🆘 Support & Quick Links

🔗 Important Links

• Create Bot: @BotFather
• Get API Credentials: https://my.telegram.org
• Get Your Telegram ID: @userinfobot
• Download Redis: https://redis.io/download
• Repository: https://github.com/MeherMankar/CleanAcc

📞 Getting Help

1. Check troubleshooting section above
2. Review logs: Look at logs/bot.log for errors
3. Submit issues: Create issue on GitHub with error details
4. Include information: Bot version, Python version, OS, error messages