A powerful Telegram bot that monitors user activity and analyzes communication patterns using metadata tracking (Online/Offline/Typing indicators).

This bot monitors public metadata from Telegram users (without reading messages or violating privacy) to:

• Track online/offline status changes
• Detect typing indicators
• Analyze temporal synchronization patterns between users
• Generate detailed activity reports
• Identify potential communication patterns based on activity correlation

Privacy First: This bot only monitors public status indicators and does NOT read messages or private conversations.

• Real-time Status Tracking - Monitor when users go online/offline
• ⌨ Typing Detection - Detect when users are typing
• Activity Logging - Complete activity logs with timestamps
• Continuous Polling - Configurable polling intervals

• Sync Pattern Detection - Identify when two users are active simultaneously
• Confidence Scoring - Calculate probability of communication (0-100%)
• Peak Activity Analysis - Identify peak activity hours
• Temporal Correlation - Analyze activity patterns over time

• Detailed Activity Reports - Per-user activity summaries
• Top Sync Pairs - Most synchronized user pairs
• Statistical Analysis - Comprehensive statistics dashboard
• Daily Stats - Automated daily activity tracking

• Easy-to-use Commands - 10+ bot commands for full control
• User Management - Add/remove monitored users dynamically
• Real-time Notifications - Instant activity alerts
• Admin Controls - Secure admin-only operations

┌─────────────────┐
│    main.py      │  Entry Point
│  System Manager │
└────────┬────────┘
         │
    ┌────┴────┬─────────────┬──────────────┐
    │         │             │              │
┌───▼────┐ ┌─▼──────┐ ┌────▼─────┐ ┌─────▼────┐
│database│ │telegram│ │   bot    │ │ analyzer │
│ .py    │ │_monitor│ │_controller│ │   .py    │
│        │ │  .py   │ │   .py    │ │          │
│PostgreSQL│ │Telethon│ │Bot Commands│ │Patterns │
└────────┘ └────────┘ └──────────┘ └──────────┘

• Python 3.8 or higher
• PostgreSQL database (we recommend Neon)
• Telegram API credentials (get them here)
• Telegram Bot Token (from @BotFather)

1. Clone the repository

git clone https://github.com/waheeb71/telegram-activity-monitor.git
cd telegram-activity-monitor

2. Install dependencies

pip install -r requirements.txt

3. Configure environment variables

Create a .env file:

# Telegram API Credentials
TELEGRAM_API_ID=your_api_id
TELEGRAM_API_HASH=your_api_hash
TELEGRAM_PHONE_NUMBER=your_phone_number
TELEGRAM_BOT_TOKEN=your_bot_token

# Database Configuration
DATABASE_URL=postgresql://user:password@host:port/database

# Monitoring Settings
POLL_INTERVAL=10
SYNC_THRESHOLD=30
MAX_CONCURRENT_USERS=10

4. Run the bot

python main.py

On first run, you'll be prompted to enter the verification code sent to your Telegram account.

/add @john_doe

Output:

✅ User added to monitoring

👤 Information:
• Name: John Doe
• Username: @john_doe
• ID: 123456789

 Now monitoring this user's activity

/sync @john_doe @jane_smith 48

Output:

 Synchronization Analysis

 User 1: @john_doe
 User 2: @jane_smith
⏱ Period: 48 hours

 Results:
• Sync events: 15
• Confidence score: 73.5%
• Avg time difference: 8.3 seconds

 Assessment:
🟠 High probability of communication

• monitored_users - List of users being monitored
• activity_logs - Complete activity log with timestamps
• sync_patterns - Detected synchronization patterns
• daily_stats - Daily aggregated statistics

• Telethon - Telegram client library
• SQLAlchemy - Database ORM
• asyncpg - Async PostgreSQL driver
• python-dotenv - Environment management

IMPORTANT: This bot monitors PUBLIC metadata only

• ✅ Only tracks online/offline/typing status
• ✅ Does NOT read messages or conversations
• ✅ Does NOT access private chats
• ✅ Complies with Telegram's Terms of Service
• ✅ All data stored locally/securely

Use Responsibly: Ensure compliance with local privacy laws and regulations.

1. SQLAlchemy Error: "metadata is reserved"

• Fixed: Column renamed from metadata to extra_data

2. NoneType += int Error

• Fixed: Proper None handling in daily stats

3. Event attribute error

• Fixed: Using hasattr() for event checking

See walkthrough.md for detailed troubleshooting.

• Handles 5-10 concurrent monitored users efficiently
• Configurable polling to avoid rate limiting
• Optimized database queries with indexing
• Async architecture for non-blocking operations

Contributions are welcome! Please feel free to submit a Pull Request.

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

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

This tool is for educational and research purposes only. Users are responsible for ensuring their use complies with:

• Telegram's Terms of Service
• Local privacy and data protection laws
• Ethical monitoring practices

The developers assume no liability for misuse of this software.

• Telethon for the excellent Telegram client library
• Neon for serverless PostgreSQL
• The open-source community

For questions or support, please open an issue on GitHub.

Made with ❤️ by waheeb Al-Humaeri

Star ⭐ this repository if you find it useful!