ghostwire/README.md

Ghostwire

Inside the process. Across the wire.

Read, search and export local WhatsApp Desktop messages and contacts. Install a message listener that delivers events to an HTTPS webhook.

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.

Start here

For users: copy 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.

python whatsapp.py --help
python whatsapp.py test

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.

Choose the command for your task:

I want to…	Command
Export contacts	python whatsapp.py contacts-export --output exports/contacts.json
Export local messages as a ZIP	python whatsapp.py export-zip --output exports/messages.zip
Read the five oldest local records	python whatsapp.py live --suite history-read
Search the running app	python whatsapp.py desktop-search "keyword" --limit 10
Search an extracted message export	python whatsapp.py search messages.jsonl "keyword"
Test sending to my own account	python whatsapp.py send-self
Deliver message events to a webhook	See the example below

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.

python whatsapp.py webhook install --endpoint https://your-endpoint.example/events --self-only --auto-restore --config listener.json
python whatsapp.py webhook status

• --endpoint selects the HTTPS target.
• --self-only limits delivery to your self-chat for testing. Omit it to subscribe to qualifying events from other chats.
• --auto-restore registers a per-user Windows task that restores the listener after WhatsApp restarts.
• --config saves the listener settings and, for automatic restoration, a Windows-protected token.

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 before integration.

How it works

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

Optional CDP, Frida, RAM and QR research commands have separate dependencies and behavior. They are listed separately in the CLI reference.

Develop and extend

python -m whatsapp_suite test
python build_whatsapp_bundle.py
python whatsapp.py test

Edit whatsapp_suite/; whatsapp.py is generated. The portable file is about 207 KiB and embeds the maintained modules, runtime assets and tests.

Resource	Use it for
CLI reference	Commands, options and output behavior
Webhook guide	Setup, event schema, restart behavior and removal
Architecture	Understand the bridge and choose the right extension point
Contributing	Add a command, change JavaScript, rebuild native helpers
Agent skill	Repository-specific guidance for coding agents
Brand assets	Logo files and usage
Troubleshooting	Resolve common setup and runtime problems
Validation	Distinguish tested behavior from assumptions
Security	Handle private data and credentials
Publishing	Review and upload the clean repository

Repository: karl/ghostwire. No open-source license has been selected; see licensing status.