WhatsApp Beacon

You can generate a static HTML report containing KPIs, heatmaps, and leaderboards based on the collected SQLite history using the --analytics flag.

By default, the report is saved to analytics/index.html. You can specify a custom output path using --analytics-output.

# Default output
whatsapp-beacon --analytics

# Custom output
whatsapp-beacon --analytics --analytics-output reports/contact-dashboard.html

To start tracking a specific contact, use the -u or --username flag with the exact WhatsApp contact name.

Note on Authentication: The first time you run the tool, you must authenticate via WhatsApp Web.

• Non-headless (default): A browser window will open; scan the QR code manually.
• Headless: If you use --headless during the first run, the tool will save a QR code screenshot to qrcode.png for you to scan.

Once authenticated, the session profile is saved and can be reused for future headless runs.

whatsapp-beacon -u "John Doe"

Use the following command to clone the repository, create a local virtual environment (.venv), install the package, and attempt to bootstrap necessary system dependencies (like Chrome/Chromium on Linux).

curl -fsSL https://raw.githubusercontent.com/jasperan/whatsapp-osint/master/install.sh | bash

To install to a specific directory, set the PROJECT_DIR environment variable:

PROJECT_DIR=/opt/whatsapp-osint curl -fsSL https://raw.githubusercontent.com/jasperan/whatsapp-osint/master/install.sh | bash

You can install the package directly using pip. This provides two equivalent CLI entry points: whatsapp-osint and whatsapp-beacon.

python3 -m pip install whatsapp-osint

You can manage settings using a config.yaml file. The following keys are supported:

username: "Target Name"
language: "en"
headless: false
excel: false
browser: "chrome"
log_level: "INFO"
data_dir: "data"
chrome_binary_path: null

If the tool cannot find the Chrome binary, you can explicitly provide the path using the --chrome-binary-path flag.

whatsapp-beacon -u "John Doe" --chrome-binary-path /full/path/to/browser

The WhatsAppBeacon resolves the Chrome browser and ChromeDriver using the following priority:

ChromeDriver Resolution:

1. Explicit path provided in config.chrome_driver_path.
2. System chromedriver found on the PATH.
3. Selenium Manager (automatic discovery).

Chrome Browser Resolution:

1. Explicit path provided in config.chrome_binary_path.
2. Common binaries found on PATH (e.g., google-chrome, chromium, chrome).
3. Common absolute installation paths (e.g., /usr/bin/google-chrome, /Applications/Google Chrome.app/...).
4. Selenium auto-discovery.

The tool generates several files and directories during operation:

• Logs: logs/whatsapp_beacon.log
• Database: data/victims_logs.db (SQLite history)
• Excel export: History_wp.xlsx (generated when using -e or excel: true)
• Analytics report: analytics/index.html (default location)
• Saved WhatsApp profile: data/chrome_profile (used for session persistence)

The following command-line arguments are available for whatsapp-beacon and whatsapp-osint:

If you need the raw processed data instead of an HTML file, use build_payload(). This method returns a dictionary containing structured analytics, including:

• summary: High-level metrics like total_sessions, total_contacts, total_seconds, average_seconds, longest_seconds, busiest_hour, and busiest_hour_count.
• users: A list of user statistics (total time, session count, average duration, last seen).
• sessions: The raw list of processed session objects.
• daily_activity: Aggregated activity per date.
• hourly_heatmap: A 7x24 grid representing activity by day of the week and hour of the day.
• duration_buckets: Counts of sessions categorized by length (e.g., '<30 sec', '30-120 sec', etc.).
• recent_sessions: The 25 most recent sessions.
• top_sessions: The 10 longest sessions.

The run() method starts the full lifecycle of the tracker:

1. If config.excel is enabled, it converts existing database logs to Excel.
2. Sets up the Selenium WebDriver (handling Chrome binary/driver resolution).
3. Performs the WhatsApp Web login (handling QR code authentication).
4. Searches for the target user defined in config.username.
5. Enters a continuous loop that polls the user's online status based on the configured config.language.
6. Logs session start and end times to the database.

Note: The loop continues until a KeyboardInterrupt is received or the browser window is closed.