4.8 KiB
WhatsApp Desktop Suite
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 |
| Message webhooks | webhook |
In-process listener, direct HTTPS or loopback delivery, optional automatic restoration |
| 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 discovers function/vtable locations from binary fingerprints rather than fixed module RVAs. It retains compiler/object-layout and ABI assumptions, so other versions remain unverified and incompatible patterns fail discovery. 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.
Message listener with automatic restoration
Supply your endpoint token through WHATSAPP_INJECTOR_WEBHOOK_TOKEN using your secret manager, then run:
python whatsapp.py webhook install --endpoint https://your-endpoint.example/events --auto-restore --config listener.json
--endpoint selects the HTTPS target; --auto-restore creates a per-user Windows task that checks every minute and restores the listener after WhatsApp restarts. Delivery runs inside WhatsApp, without CDP, UI automation, a local HTTP server or a continuously running Python process. Add --self-only for self-chat testing. The endpoint must authenticate the token header and accept message batches. See setup, payload, limitations and full removal.
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 207 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
- CLI and export behavior
- Message webhooks and restart behavior
- Architecture and native bridge
- Validation and limitations
- Development and contributions
- Publishing to tea.karlcom.de
- Handling private data
Project status
Repository: karl/whatsapp_injector. It is independent of WhatsApp/Meta. No open-source license has been selected; see licensing status.