# 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).