73 lines
4.1 KiB
Markdown
73 lines
4.1 KiB
Markdown
# 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](docs/CLI.md) | 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:
|
|
|
|
```powershell
|
|
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](docs/CLI.md#optional-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
|
|
|
|
```powershell
|
|
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
|
|
|
|
```text
|
|
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](docs/CLI.md)
|
|
- [Message webhooks and restart behavior](docs/WEBHOOKS.md)
|
|
- [Architecture and native bridge](docs/ARCHITECTURE.md)
|
|
- [Validation and limitations](docs/VALIDATION.md)
|
|
- [Development and contributions](CONTRIBUTING.md)
|
|
- [Publishing to tea.karlcom.de](docs/PUBLISHING.md)
|
|
- [Handling private data](SECURITY.md)
|
|
|
|
## Project status
|
|
|
|
Repository: [karl/whatsapp_injector](https://tea.karlcom.de/karl/whatsapp_injector). It is independent of WhatsApp/Meta. No open-source license has been selected; see [licensing status](LICENSE.md).
|