Whatsapp Web Owner Activity Monitor

A Python-based monitoring system that tracks WhatsApp Web activity for the account user (the person who scans the QR code). Events can be sent to webhooks (N8N, etc.) or printed to console for local monitoring.

🎯 Features

The monitor detects and reports these events (via webhook or console):

1. 📝 Typing Activity

• Started Typing: Detects when the user starts typing a message
• Stopped Typing: Triggers after ~3 seconds of no typing activity

2. 🎤 Voice Recording

• Recording Started: Detects when the user starts recording a voice message
• Recording Stopped: Detects when recording ends

3. 🔄 Connection Status

• Online: WhatsApp Web connects or connection is restored
• Lost: Connection is lost (internet disconnected, browser closed, tab closed, etc.)

4. 🔐 Authentication Status

• QR Ready: QR code is displayed and user needs to scan to login
• Logged In: User successfully scanned QR code and logged in

4. 🖥️ Flexible Output Modes

• Webhook Mode: Send events to N8N or any webhook endpoint
• Console Mode: Print events to terminal (no webhook required)

🛠️ Technical Stack

• Python 3.x - Core programming language
• Selenium WebDriver - Browser automation
• Chrome/Chromium - Headless browser (auto-configured)
• Requests - HTTP webhook calls
• ChromeDriver - Automatically downloaded and configured

📋 Requirements

• Python 3.7 or higher
• Google Chrome or Chromium browser installed
• Internet connection
• N8N instance or any webhook endpoint (optional - can print to console instead)

🚀 Quick Start

Option 1: Automated Setup (Recommended)

Windows:

run.bat

Linux/Mac:

chmod +x run.sh
./run.sh

These scripts will automatically:

• Create a virtual environment
• Install all dependencies
• Check for .env configuration
• Start the monitor

Option 2: Manual Installation

1. Clone or Download

cd "WhatsApp Web Monitoring"

2. Create Virtual Environment (Recommended)

# Windows
python -m venv venv
venv\Scripts\activate

# Linux/Mac
python3 -m venv venv
source venv/bin/activate

3. Install Dependencies

pip install -r requirements.txt

4. Configure Webhook URL (Optional)

If you want to send events to a webhook (N8N, etc.):

Option A: Using .env file (Recommended)

# Windows
copy .env.example .env

# Linux/Mac
cp .env.example .env

# Edit .env and set your webhook URL
WEBHOOK_URL=https://your-n8n-instance.com/webhook/whatsapp-monitor

Option B: Edit config.py directly

Open config.py and modify:

WEBHOOK_URL = "https://your-n8n-instance.com/webhook/whatsapp-monitor"

If you skip this step: Events will be printed to the console instead of sent to a webhook. This is useful for testing or if you just want to monitor activity locally.

🎮 Running the Monitor

Quick Start Scripts

Windows:

run.bat

Linux/Mac:

./run.sh

Manual Start

# Activate virtual environment first
# Windows: venv\Scripts\activate
# Linux/Mac: source venv/bin/activate

python whatsapp_monitor.py

📖 First Time Setup

1. Run the monitor:

   # Using quick start script (recommended)
   run.bat  # Windows
   ./run.sh # Linux/Mac
   
   # Or manually
   python whatsapp_monitor.py
   

2. Scan QR Code:

   • A Chrome window will open (or run in background if headless)
   • Scan the QR code with your WhatsApp mobile app
   • The session will be saved in chrome_profile/ for future runs

3. Monitor Running:

   • Once logged in, the monitor starts automatically
   • Events are sent to your webhook URL (if configured) or printed to console

Subsequent Runs

The monitor will use the saved session and start immediately without requiring QR code scan.

Console Mode (No Webhook)

If you don't configure a webhook URL, the monitor will run in console mode and print all events to the terminal:

python whatsapp_monitor.py

Example console output:

============================================================
📤 EVENT DETECTED:
Event: user_texting
Action: started
Timestamp: 1698062428915
DateTime: 2024-10-23T14:23:48
============================================================

To test console mode without running the full monitor:

python test_console_mode.py

📤 Webhook Payload Format

All events are sent as POST requests with JSON payload:

{
  "event": "user_texting",
  "action": "started",
  "timestamp": 1698062428915,
  "datetime": "2024-10-23T14:23:48",
  "source": "whatsapp_monitor"
}

Event Types

| Event | Action | Description | |-------|--------|-------------| | user_texting | started | User started typing | | user_texting | stopped | User stopped typing | | user_recording | started | User started voice recording | | user_recording | stopped | User stopped voice recording | | connection | online | WhatsApp Web is online | | connection | lost | Connection lost (internet, browser closed, tab closed) | | auth | qr_ready | QR code displayed, user needs to scan | | auth | logged_in | User successfully logged in |

⚙️ Configuration

Edit config.py to customize behavior:

Monitoring Settings

MONITOR_INTERVAL = 0.5  # Check every 0.5 seconds
TYPING_STOP_DELAY = 3.0  # Seconds before "stopped typing"

Browser Settings

HEADLESS_MODE = True  # Run without visible window
WINDOW_WIDTH = 1920
WINDOW_HEIGHT = 1080

Event Toggles

EVENTS_ENABLED = {
    "online_offline": True,
    "typing": True,
    "voice_recording": True,
}

Webhook Settings

WEBHOOK_TIMEOUT = 10
WEBHOOK_RETRY_ENABLED = True
WEBHOOK_RETRY_COUNT = 3

🔧 Advanced Usage

Cleanup Utility

If you encounter issues with Chrome processes or need to reset the session:

Windows:

cleanup.bat

This will:

• Kill all Chrome and ChromeDriver processes
• Remove the chrome_profile directory
• Allow you to start fresh with a new QR code scan

Linux/Mac:

rm -rf chrome_profile
pkill -f chrome
pkill -f chromedriver

Run in Headless Mode

Set in config.py:

HEADLESS_MODE = True

Run as Background Service

Windows (using NSSM):

# Install NSSM, then:
nssm install WhatsAppMonitor "C:\path\to\venv\Scripts\python.exe" "C:\path\to\whatsapp_monitor.py"
nssm start WhatsAppMonitor

Linux (using systemd):

Create /etc/systemd/system/whatsapp-monitor.service:

[Unit]
Description=WhatsApp Web Monitor
After=network.target

[Service]
Type=simple
User=youruser
WorkingDirectory=/path/to/Whatsapp Web Monitoring
ExecStart=/path/to/venv/bin/python whatsapp_monitor.py
Restart=always

[Install]
WantedBy=multi-user.target

Then:

sudo systemctl enable whatsapp-monitor
sudo systemctl start whatsapp-monitor

📊 Logging

Logs are written to:

• Console: Colored real-time output
• File: whatsapp_monitor.log

Configure in config.py:

LOG_LEVEL = "INFO"  # DEBUG, INFO, WARNING, ERROR
FILE_LOGGING = True
CONSOLE_LOGGING = True

🐛 Troubleshooting

ChromeDriver Issues

The system automatically downloads ChromeDriver. If issues occur:

python setup_chromedriver.py

QR Code Not Appearing

• Disable headless mode temporarily in config.py: HEADLESS_MODE = False
• Check if Chrome is installed
• Run cleanup script and try again:

  # Windows
  cleanup.bat
  
  # Linux/Mac
  rm -rf chrome_profile
  

Webhook Not Sending

• Verify webhook URL is correct in .env or config.py
• Check network connectivity
• Review logs in whatsapp_monitor.log
• Test webhook URL with curl:

  curl -X POST -H "Content-Type: application/json" -d '{"test":"data"}' YOUR_WEBHOOK_URL
  

• Try console mode first (remove webhook URL) to verify events are being detected

Session Expired / Chrome Profile Issues

Run the cleanup script to reset everything:

Windows:

cleanup.bat

Linux/Mac:

rm -rf chrome_profile
pkill -f chrome
pkill -f chromedriver

Then restart the monitor and scan QR code again.

Voice Recording Not Detected

If voice recording detection isn't working, use the element inspector tool:

python inspect_elements.py

This will show you which selectors are being detected in real-time. Try recording a voice message and see which elements appear. You can then update the selectors in config.py if needed.

Debugging Element Selectors

Run the element inspector to see what's being detected:

python inspect_elements.py

This tool will:

• Show which elements are currently detected
• Display all voice/audio related data-testid and data-icon attributes
• Help you find the correct selectors if WhatsApp Web UI changes
• Update every 2 seconds with current status

Chrome Crashes or Hangs

1. Run the cleanup script to kill all Chrome processes
2. Delete the chrome_profile folder
3. Restart the monitor
4. See Fix Chrome Crash for detailed troubleshooting

📁 Project Structure

WhatsApp Web Monitoring/
├── whatsapp_monitor.py      # Main monitoring application
├── inspect_elements.py      # Element inspector tool for debugging
├── setup_chromedriver.py    # ChromeDriver auto-setup
├── test_console_mode.py     # Test script for console mode
├── config.py                # Configuration settings
├── requirements.txt         # Python dependencies
├── .env.example             # Environment variables template
├── .gitignore               # Git ignore rules
├── README.md                # This file
├── run.bat                  # Quick start script (Windows)
├── run.sh                   # Quick start script (Linux/Mac)
├── cleanup.bat              # Cleanup script (Windows)
├── docs/                    # Documentation folder
│   ├── QUICK_START.md       # Quick start guide
│   ├── CONSOLE_MODE.md      # Console mode documentation
│   ├── ARCHITECTURE.md      # System architecture
│   ├── FLOW_DIAGRAM.md      # Event flow diagrams
│   ├── SYSTEM_OVERVIEW.md   # Detailed system overview
│   └── REQUIREMENTS_CHECKLIST.md  # Feature checklist
├── chrome_profile/          # WhatsApp session data (auto-created)
├── drivers/                 # ChromeDriver (auto-downloaded)
└── whatsapp_monitor.log     # Log file (auto-created)

🔒 Security Notes

• Session Data: The chrome_profile folder contains your WhatsApp session. Keep it secure.
• Webhook URL: Contains sensitive endpoint. Use environment variables.
• HTTPS: Always use HTTPS for webhook URLs in production.

🤝 N8N Integration Example

Create a webhook node in N8N:

1. Add Webhook node
2. Set HTTP Method: POST
3. Set Path: /webhook/whatsapp-monitor
4. Use the full URL in your .env file

Example N8N workflow:

Webhook → Switch (by event type) → Different actions per event

🚀 Quick Reference

Common Commands

# Quick start (Windows)
run.bat

# Quick start (Linux/Mac)
./run.sh

# Manual start
python whatsapp_monitor.py

# Test console mode
python test_console_mode.py

# Debug element selectors
python inspect_elements.py

# Cleanup and reset
cleanup.bat  # Windows
rm -rf chrome_profile  # Linux/Mac

Configuration Files

• .env - Webhook URL and environment variables (create from .env.example)
• config.py - All monitoring settings and selectors
• chrome_profile/ - WhatsApp session data (auto-created)
• whatsapp_monitor.log - Application logs

📚 Documentation

Additional documentation is available in the docs/ folder:

Getting Started

• Quick Start Guide - Get up and running in 5 minutes
• Console Mode - Running without webhook URL (print events to console)

Technical Documentation

• Architecture Diagram - System architecture and component interactions
• Flow Diagram - Event detection and webhook flow
• System Overview - Detailed architecture and how it works
• Requirements Checklist - Complete feature implementation status

📝 License

This project is provided as-is for personal use.

🙏 Credits

Built with:

• Selenium WebDriver
• Python Requests
• Colorama
• WebDriver Manager

---

Note: This tool monitors your own WhatsApp Web activity. Use responsibly and in compliance with WhatsApp's Terms of Service.