WhatsApp Beacon tracks when specific WhatsApp contacts go online and stores every completed session in SQLite. It can export to Excel, generate a polished analytics dashboard, and run fully headless once the session is authenticated.
View Interactive Presentation | Animated overview of the project
 |
 |
 |
 |
 |
 |
Disclaimer: This tool is for educational and research purposes only. Do not use it for stalking or any illegal activities.
- PyPI install:
pip install whatsapp-osintgets you the package fast. - One-command installer: clone, create a local
.venv, install the package, and verify the browser setup. - Best-effort Linux bootstrap: if Git, Python, or Chrome/Chromium are missing, the installer will try to install them with
sudo. - Automated browser driver resolution: Selenium Manager handles matching drivers, with manual override flags if you need them.
- Headless tracking: authenticate once, then run quietly in the background.
- SQLite session history: every finished online session is stored locally.
- Excel export: turn the database into
History_wp.xlsx. - Advanced analytics dashboard: generate a static HTML report with filters, heatmaps, leaderboards, and recent-session views.
python3 -m pip install whatsapp-osintThe package installs 2 equivalent entry points:
whatsapp-osintwhatsapp-beacon
curl -fsSL https://raw.githubusercontent.com/jasperan/whatsapp-osint/master/install.sh | bashWhat it does:
- clones or updates the repo into
./whatsapp-osint - creates
./whatsapp-osint/.venv - installs the package and the
whatsapp-beaconcommand - on Linux, uses
sudowhen needed to install missing system packages and Chrome/Chromium - verifies that a browser binary is available before it finishes
If you want a custom location:
PROJECT_DIR=/opt/whatsapp-osint curl -fsSL https://raw.githubusercontent.com/jasperan/whatsapp-osint/master/install.sh | bashManual / development install
Use this only if you explicitly want to manage setup yourself.
git clone https://github.com/jasperan/whatsapp-osint.git
cd whatsapp-osint
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip setuptools wheel
python -m pip install -e ".[dev]"If you installed from PyPI:
whatsapp-osint -u "John Doe"whatsapp-osint and whatsapp-beacon run the same CLI. The rest of the examples keep using whatsapp-beacon.
If you used the GitHub installer:
cd whatsapp-osint
source .venv/bin/activate
whatsapp-beacon -u "John Doe"If you do not want to activate the venv first:
./whatsapp-osint/.venv/bin/whatsapp-beacon -u "John Doe"The first run must authenticate with WhatsApp Web.
- Non-headless is the easiest path. Scan the QR code once, then the saved browser profile will be reused.
- Headless also works. If the session is not authenticated yet, the tool will save a QR screenshot to
qrcode.png.
Example:
whatsapp-beacon -u "Maria" --headlessGenerate a static HTML dashboard from the collected SQLite history:
whatsapp-beacon --analyticsBy default, the report is written to:
analytics/index.html
Custom output path:
whatsapp-beacon --analytics --analytics-output reports/contact-dashboard.htmlOnce generated, open it in your browser:
xdg-open analytics/index.html
# or on macOS
open analytics/index.htmlThe dashboard includes:
- top-level KPIs
- per-contact leaderboard
- daily online-time bars
- weekday/hour heatmap
- duration distribution
- recent sessions and longest sessions tables
- live filtering by contact inside the page
Captured from a demo dataset generated through the built-in analytics exporter.
Same dashboard, narrowed to one contact to show the live filter state.
| Argument | Description | Default |
|---|---|---|
-u, --username |
Exact WhatsApp contact name to track. | Required for tracking |
-l, --language |
WhatsApp Web language code (en, es, fr, etc.). |
en |
-e, --excel |
Export the database to Excel before doing anything else. | False |
--headless |
Run without a visible browser window. | False |
--chrome-driver-path |
Explicit path to chromedriver. |
Auto-detect |
--chrome-binary-path |
Explicit path to Chrome or Chromium. | Auto-detect |
--analytics |
Generate the analytics dashboard and exit. | False |
--analytics-output |
Output path for the analytics HTML report. | analytics/index.html |
--config |
Path to a custom config file. | config.yaml |
You can keep defaults in config.yaml:
username: "Target Name"
language: "en"
headless: false
excel: false
browser: "chrome"
log_level: "INFO"
data_dir: "data"
chrome_binary_path: null- Logs:
logs/whatsapp_beacon.log - Database:
data/victims_logs.db - Excel export:
History_wp.xlsx - Analytics report:
analytics/index.htmlby default - Saved WhatsApp profile:
data/chrome_profile
The installer now tries to fix this automatically on Linux. If your distro keeps the browser in a weird place, launch with an explicit path:
whatsapp-beacon -u "John Doe" --chrome-binary-path /full/path/to/browserUseful checks:
which google-chrome google-chrome-stable chromium chromium-browser
whatsapp-beacon --helpTracking mode needs a contact name:
whatsapp-beacon -u "John Doe"Analytics mode does not:
whatsapp-beacon --analyticsContributions are welcome. Fork it, build what you need, and send a PR.
Distributed under the MIT License. See LICENSE for more information.
Original concept developed in 2019. Revamped in 2025 for better performance and usability.
