Capture selected WhatsApp chats, read their history, and transcribe audio locally. wpp combines a CLI that runs without a browser and an intuitive web workspace in one Go executable. SQLite stores messages and the session; JSONL supports complete export and incremental consumption by other systems.
Build requirements: Go 1.26+, toolchain 1.26.9, a C compiler (gcc or equivalent), and CGO enabled. Operational support targets Linux and macOS; Windows is unsupported. Node.js/npm are used only for development checks.
make build
# Without make: go build -buildvcs=false -trimpath -o wpp ./cmd/wpp
./wpp serve
# Open http://127.0.0.1:8080In Settings > Account, connect WhatsApp using your phone's QR scanner. Return to Chats, choose Refresh chats, and track the conversations you want. Enable continuous capture under Settings > Capture, or use Sync now in a chat.
Closing the tab keeps the process active; Ctrl+C stops it. A new installation starts with capture paused and remembers preferences. The panel follows the system theme and supports narrow screens and keyboard navigation.
English is the default. Choose English or Português (Brasil) under Settings > Advanced > Application language, then Save language. The saved choice is shared by web and CLI in the same data directory and survives restarts. Browser and terminal locales do not select it automatically.
./wpp language pt-BR # Remember Brazilian Portuguese
./wpp language en # Remember English
./wpp --language en status # Override this invocation onlyApplication language is independent of audio recognition language and time zone. Messages, names, transcripts, and exported data retain their original content. Documentation is maintained in English. See language behavior and overrides.
./wpp login
./wpp chats
./wpp track 'FULL_ID_SHOWN'
./wpp runCopy the full ID from chats; names are not identifiers. run captures in the foreground without starting HTTP. For background execution, see external supervision and the systemd example.
./wpp status
./wpp exportGlobal options come before the command. Relative directories start at the working directory:
./wpp --data-dir ./data --export-dir ./exports --timezone America/Sao_Paulo runReuse matching directories on restart. One process owns capture per archive: with run active, serve opens in consultation mode and explains the conflict. Stop the owner and restart serve to take control. Never delete the lock.
Transcription is optional and uses local Whisper/FFmpeg; no language-model API call is required. Install an engine/model using the transcription guide, configure Settings > Transcription, and inspect the queue in Audio. Sound files are temporary; text persists. Text capture works without an audio engine. Audio recognition defaults to Portuguese independently of the English interface.
SQLite is the primary source. Complete exports live in exports/chat-<hash>.jsonl; incremental batches have a manifest and independent cursor. Data and export directories contain private content and must never be sent to GitHub.
./wpp events next '123456789@g.us'
# Persist events with uniqueness on event_id before acknowledgement.
./wpp events ack '123456789@g.us' E000001
./wpp events status '123456789@g.us'Identifiers above are fictitious. See the JSONL contract for schemas, reactions, edits, and transcripts. Complete export does not acknowledge batches. batch aliases the events protocol.
WhatsApp integration is unofficial, using whatsmeow, and can break or lead to account restrictions. wpp does not send messages to contacts or mark messages read; it makes protocol requests needed for synchronization.
Complete history and absence of gaps are never certified. The application preserves what it receives and attempts to retrieve what the phone makes available. Operational success does not establish coverage. Deleted, expired, or unavailable messages may be unrecoverable.
The panel accepts loopback connections only and does not provide authenticated remote access. One data directory belongs to one account. This version does not provide multiple accounts per directory, manual export imports, channels/status, or downloads of media other than audio.
- Web workspace and settings
- Installation, commands, backup, and background operation
- Capture behavior and guarantees
- Local transcription
- Incremental consumption by AI and external systems
- JSONL event contract
- Architecture and quality
- Contributing, security, and code of conduct
- Public launch preparation
Go/C and Node.js 24+ are needed for checks. Distribution builds use Go/C only and embed the web assets.
make tools
make check
make build
npx playwright install chromium
npm run test:browserStandard tests use temporary/synthetic data without a WhatsApp session. Real pairing needs the account holder's action and is not required to contribute. README images are synthetic browser-test demonstrations.
make tools also installs local publication hooks. Use your GitHub noreply address in commits and stage only reviewed public files from the manifest. Commits, pushes, and packages undergo content validation and secret scanning; new files and images require explicit review. See Contributing and the protection limits in Security.
Created and maintained by Flávio Milan (@flaviomilan), targeting flaviomilan/wpp.
First-party code uses the MIT license, allowing use, modification, and redistribution, including commercial use, while retaining the copyright notice and license text in copies or substantial portions. Attribution does not require a credit in each derivative application's interface.
Dependencies retain their licenses. In particular, an executable incorporating libsignal must meet GPL v3 requirements; the first-party MIT license does not make that combined binary MIT-only. See third-party notices and the release checklist.
Use Issues for usage problems and proposals. Security reports follow SECURITY.md without publishing personal contact details. Preparation does not automatically create/publish the repository or releases.