A Windows toolkit for reading, searching and exporting local WhatsApp Desktop data, with a portable single-file Python distribution and an editable source package.

The core live commands execute JavaScript inside the signed-in Desktop WebView through a bundled native bridge. They require neither CDP nor UI automation. Separate optional research commands use CDP, Frida or process-memory inspection.

Features

Feature	Command	Scope
Contact export	`contacts-export`	Local contact rows, including distinct PN/LID records
Message ZIP export	`export-zip`	Local message rows, decoded text/captions and manifest; no media downloads
Old message reading	`live --suite history-read`	Five oldest local records, including records outside loaded chats
Desktop search	`desktop-search`	Bounded app search through the native bridge
Saved export search	`search`	Unicode-aware literal search, filtering and optional redaction
Self-message test	`send-self`	One fixed message to the signed-in account, with stored-text verification
Inspection and diagnostics	`inventory`, `stats`, `live`	Storage inventory, export summaries and fixed probes
Optional research tools	See CLI reference	CDP history export, RAM tools, SQLite probes and pairing tools

Quick start

Copy whatsapp.py into a writable folder. Run with Python 3.11 or newer:

python whatsapp.py --help
python whatsapp.py test
python whatsapp.py contacts-export --output contacts.json
python whatsapp.py export-zip --output messages.zip
python whatsapp.py live --suite history-read

Live bridge commands require Windows x64 and 64-bit Python. They were tested with WhatsApp Desktop 2.2639.100.0 and the recorded WebView component. Other versions are attempted with a compatibility warning rather than blocked. The helper still uses native layout offsets from the tested component, so success on other versions is unverified and changed layouts can cause failure or process instability. The core commands need only Python's standard library. Optional tools have additional dependencies; Node.js enables the JavaScript fixture tests.

send-self actually sends a message. It is never part of the default tests and does not retry automatically. ZIP exports cover the local database, not necessarily every message ever received. Contacts are local table rows, not a deduplicated phone address book.

Development

python -m whatsapp_suite --help
python -m whatsapp_suite test
python build_whatsapp_bundle.py
python whatsapp.py test

The builder embeds the maintained modules, DLLs and fixtures. Modules load from memory; a verified DLL is extracted only when needed. The distribution is approximately 158 KiB. Keep source and bundle changes together.

Project layout

whatsapp.py                       Portable generated distribution
whatsapp_suite/                   Canonical Python implementations
whatsapp_suite/assets/            Runtime DLLs and SQLite agent
native/                           Native helper C++ source
tests/                           Synthetic Python and JavaScript fixtures
build_whatsapp_bundle.py          Deterministic bundle builder
docs/                            Architecture, validation and publishing guide

Documentation

Project status

Repository: karl/whatsapp_injector. It is independent of WhatsApp/Meta. No open-source license has been selected; see licensing status.