WhatsApp (pywhats)
Drive a WhatsApp account as a linked companion device (like WhatsApp Web)
from async Python via pywhats (pre-alpha,
text/image only). This is an unofficial multi-device client — not the
official WhatsApp Business / Cloud API.
CLI entrypoint: scripts/wa.py (auto-bootstraps a managed venv on first run).
Mental model
- Pairing = one-time QR scan.
wa.py pairshows an ASCII QR; scan it in WhatsApp → Linked Devices. Credentials persist to$PYWHATS_HOME/<session>.session(+.signal.db). - Resuming = silent. Later commands reconnect with the same session — no QR.
- JIDs address chats. Bare phone
15550001234→15550001234@s.whatsapp.net; groups use...@g.us. - Events are how you receive.
wa.py listenprints one JSON object per event.
⚠️ Never bare-await Client calls inside a handler
Event handlers run inline on the receive loop. Awaiting send_*,
mark_read, get_group_info, download_media, etc. inside a handler
deadlocks the connection. Always asyncio.create_task(...). The listen
subcommand already does this for --read.
Commands
bashscripts/wa.py pair # one-time QR pair scripts/wa.py send-text 15550001234 "hello" # 1:1 text scripts/wa.py send-image 15550001234 photo.jpg --caption hi # 1:1 image scripts/wa.py group-info 120363000000000000@g.us # group metadata JSON scripts/wa.py group-send 120363000000000000@g.us "hi all" # group text scripts/wa.py mark-read 15550001234 MSGID [--sender JID] # blue ticks scripts/wa.py presence available # global presence scripts/wa.py typing 15550001234 composing [--media audio] # typing indicator scripts/wa.py listen --read --events message,receipt # JSONL event stream scripts/wa.py --session work send-text 15550001234 "hi" # named session
| Command | Behavior |
|---|---|
pair | Fresh link via ASCII QR; idempotent if already paired |
send-text <to> <text> | Send 1:1 text; print message id |
send-image <to> <path> [--caption C] | Send image (jpg/png/webp, ≤16MB); print id |
group-info <gid> | Print group JSON (subject, owner, participants, …) |
group-send <gid> <text> | Resolve members then send group text; print id |
mark-read <chat> <ids...> | Blue-tick; --sender for groups |
presence <available|unavailable> | Global presence |
typing <to> <composing|paused> | Chat presence; optional --media audio |
listen | Long-running JSON lines; --read, --events, --subscribe JID (required for presence events) |
Global: --session NAME (default default, or env PYWHATS_SESSION) —
goes before the subcommand: wa.py --session work pair.
Sessions / multi-account
$PYWHATS_HOME/ # default: ~/.pywhats venv/ # managed Python + pywhats default.session # --session default default.session.signal.db work.session # --session work
Override home with PYWHATS_HOME. Unpaired / logged-out sessions print a clear
message to re-run wa.py --session <name> pair.
If pair reports the device was logged out right after scanning, that is
WhatsApp device-churn reaping, not a failure of the skill — the dead session is
deleted automatically; follow the recovery steps it prints (remove linked
devices, wait 15–20 min, pair once).
Full reference
references/api.md — every Client method, every event
payload, JID construction, and the download_media note.
