whatsapp

# WhatsApp (pywhats) Drive a WhatsApp account as a **linked companion device** (like WhatsApp Web) from async Python via [`pywhats`](https://pypi.org/project/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 pair` shows 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 listen` prints 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 ```bash scripts/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 scrip...