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, 64-bit Python and WhatsApp Desktop 2.2639.100.0 with the verified WebView component. This is a version-specific integration, not a general promise of compatibility with future WhatsApp releases. 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.