The main commands run JavaScript inside the signed-in Windows Desktop app through a bundled native bridge. They use neither CDP nor UI automation. Ghostwire is an independent, reverse-engineered toolkit; it is not an official WhatsApp API.
**For users:** copy [whatsapp.py](whatsapp.py) into a writable folder. You need Python 3.11 or newer; live Desktop commands require Windows x64, 64-bit Python, and WhatsApp running and signed in. You do not need a C++ compiler or separate DLL files.
The default tests use synthetic data and do not send messages or install listeners. Node.js enables the JavaScript fixture checks; without it, inspect the reported skips.
Exports and reports contain private data. Existing export files are refused: choose a new output name. A message ZIP contains decoded text records and a manifest, not downloaded media or guaranteed complete account history. Contact rows may contain separate PN/LID identities.
## Receive message events
Provide your endpoint token through the environment variable `WHATSAPP_INJECTOR_WEBHOOK_TOKEN`, preferably using your secret manager. Your endpoint must validate the `X-Webhook-Token` header.
The installer exits. Delivery runs inside WhatsApp; no local HTTP server or continuous Python process is needed. The task performs a brief check every minute while your Windows user is logged in. Process memory does not survive restart: the task reinstalls the listener, with a polling gap.
`send-self` sends a real test message and verifies its stored plaintext. It never retries an uncertain send automatically. No AI summarizer or automatic replies are included.
See [webhook setup, payload and removal](docs/WEBHOOKS.md) before integration.
## How it works
```mermaid
flowchart LR
P["Python CLI"] --> B["Bundled native bridge"]
B --> W["WhatsApp WebView JavaScript"]
W --> D["App database getters and decoder"]
D --> E["JSON / ZIP exports"]
W --> L["Message event queue"]
L --> H["Native HTTPS relay"]
H --> T["Your webhook endpoint"]
```
Python orchestrates documented Windows APIs through `ctypes`. A temporary Windows hook loads a native helper into WhatsApp; the helper locates the existing WebView and calls its script-execution interface. The portable file bundles the C++ DLLs; Python does not replace them with a pure-Python implementation. Read [the architecture](docs/ARCHITECTURE.md) for lifetimes and compatibility boundaries.
## Compatibility and verification
Tested with WhatsApp Desktop **2.2639.100.0** on Windows x64. Other versions are attempted with a warning. Native addresses are discovered from binary fingerprints, but compiler layout and interface assumptions remain; support for other builds is unverified.
The verified bundle passed **41 offline tests**. Live checks covered contact export, old-message reading, search, message ZIP export, self-send, direct HTTPS delivery and task restoration after a WhatsApp restart. See [validation evidence and untested cases](docs/VALIDATION.md).
Optional CDP, Frida, RAM and QR research commands have separate dependencies and behavior. They are listed separately in the [CLI reference](docs/CLI.md).
