71 lines
3.9 KiB
Markdown
71 lines
3.9 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 |
|
|
| 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 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](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 158 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)
|
|
- [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).
|