Send and receive WhatsApp messages via the unofficial linked-device client pywhats (pip install pywhats) — pair with QR, send text/images, group chat, read receipts, presence/typing, and a long-running JSON event stream. Use when the user wants to script WhatsApp as a linked comp
Install
npx skills add https://github.com/sanjay3290/ai-skills/tree/main/skills/whatsapp
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install sanjay3290-ai-skills@llmmart
git clone https://github.com/sanjay3290/ai-skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole sanjay3290/ai-skills collection as a plugin from our marketplace. Git is the plain clone.
README
WhatsApp Skill (pywhats)
An AI agent skill for sending and receiving WhatsApp messages via the
unofficial linked-device client pywhats
— pair with a QR code, send text and images, message groups, mark read, set
presence/typing, and stream inbound events as JSON lines. Works with Claude
Code, Gemini CLI, Cursor, OpenAI Codex, Goose, and other AI clients supporting
the Agent Skills Standard.
Not the official WhatsApp Business / Cloud API. This links as a companion device (like WhatsApp Web) to a personal WhatsApp account.
Features
- Pair — One-time QR link; ASCII QR printed in the terminal
- Send text / image — 1:1 chats; images: jpg/png/webp up to 16MB
- Groups — Fetch metadata (JSON) and send group text
- Receipts — Blue-tick messages (
mark-read); optional auto-read inlisten - Presence / typing — Global available/unavailable; composing/paused/recording
- Listen — Long-running JSONL event stream for every pywhats event
- Managed venv — Auto-creates
$PYWHATS_HOME/venvand installspywhatson first run
Requirements
- Python 3.11+
bash(for the bootstrap script)- Network access to WhatsApp + PyPI on first bootstrap
- A phone with WhatsApp to scan the pair QR
Caveats
pywhats is a young library (0.1.x, text/image only) and an unofficial
client. Automating a personal account can violate WhatsApp's ToS and risk a
ban — use a personal/test number, not production.
In testing we found WhatsApp sometimes removes freshly linked devices within
a minute or so if the account has seen rapid pair/unpair cycles. The pair
command detects this and prints recovery steps (remove linked devices on the
phone, wait ~15–20 minutes, pair once).
Quick Start
1. Pair a device
skills/whatsapp/scripts/wa.py pair
On first run this will:
- Create
$HOME/.pywhats/venv(or$PYWHATS_HOME/venv), streaming progress pip install "pywhats>=0.1.1,<0.2"- Print an ASCII QR code (also saved as
<session>.qr.pngfor terminals where the ASCII render isn't scannable)
On your phone: WhatsApp → Linked Devices → Link a Device and scan the QR. When pairing succeeds the CLI prints the device JID, waits briefly for history sync, saves the session, and exits.
Re-running pair on an already-paired session is a no-op (exits 0).
2. Send a message
skills/whatsapp/scripts/wa.py send-text 15550001234 "hello from the skill"
skills/whatsapp/scripts/wa.py send-image 15550001234 ./photo.jpg --caption "hi"
<to> accepts a bare international number without +, or a full JID
(...@s.whatsapp.net / ...@g.us).
3. Listen for events
skills/whatsapp/scripts/wa.py listen --read
# one JSON object per line, e.g.
# {"event":"message","id":"...","chat":"...","text":"hi",...}
Command Reference
| Command | Description | Key options |
|---|---|---|
pair |
Link a new companion device (ASCII QR) | --session NAME |
send-text <to> <text> |
Send 1:1 text; prints message id | --session |
send-image <to> <path> |
Send image; prints message id | --caption, --session |
group-info <gid> |
Group metadata as JSON | --session |
group-send <gid> <text> |
Group text (resolves participants) | --session |
mark-read <chat> <ids...> |
Blue-tick message ids | --sender (groups), --session |
presence <available\|unavailable> |
Global presence | --session |
typing <to> <composing\|paused> |
Chat presence / typing | --media audio, --session |
listen |
Stream events as JSON lines until Ctrl-C | --read, --subscribe JID (presence), --events LIST, --session |
Global options (go before the subcommand, e.g. wa.py --session work pair):
--session NAME— session file$PYWHATS_HOME/<NAME>.session(defaultdefault, or envPYWHATS_SESSION)
Presence events only flow after subscribing: wa.py listen --subscribe 15550001234 --events presence (this also marks the linked device "available").
Exit codes: 0 success, 1 error / unpaired / logged out, 2 usage error,
130 interrupted (Ctrl-C).
Runtime layout
| Path | Purpose |
|---|---|
$PYWHATS_HOME |
Default $HOME/.pywhats |
$PYWHATS_HOME/venv |
Managed Python venv with pywhats |
$PYWHATS_HOME/<NAME>.session |
Pairing credentials |
$PYWHATS_HOME/<NAME>.session.signal.db |
Signal ratchet / keys |
Bootstrap script: scripts/_bootstrap.sh — creates the venv if needed, ensures
pywhats + qrcode are importable, prints the absolute path to the venv
python as its last stdout line. wa.py re-execs under that interpreter when
started with a system python3 that lacks pywhats.
Multi-account
wa.py --session personal pair
wa.py --session work pair
wa.py --session work send-text 15550001234 "from work session"
export PYWHATS_SESSION=work # default for subsequent commands
Claude Code / agent usage
When the agent needs to message you on WhatsApp:
# after a one-time pair
skills/whatsapp/scripts/wa.py send-text "$MY_PHONE" "Deploy finished ✅"
For full method/event docs when writing custom Python against pywhats, see references/api.md.
Security notes
- A paired session file is equivalent to a logged-in WhatsApp Web session —
protect
$PYWHATS_HOME(filesystem permissions, backups). pywhatsis an unofficial reimplementation of the protocol — do not rely on it for sensitive traffic.- Prefer a secondary/test WhatsApp number for automation.
License
Apache 2.0 (skill packaging). pywhats is separately licensed on PyPI.
Skill manifest
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
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
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.
Files (ai-skills)
-
references
-
api.md 10.3 KB
Loading…
-
-
scripts
-
wa.py 27.4 KB
Loading… -
_bootstrap.sh 3.3 KB
Loading…
-
-
README.md 5.6 KB
# WhatsApp Skill (pywhats) An AI agent skill for sending and receiving WhatsApp messages via the **unofficial** linked-device client [`pywhats`](https://pypi.org/project/pywhats/) — pair with a QR code, send text and images, message groups, mark read, set presence/typing, and stream inbound events as JSON lines. Works with Claude Code, Gemini CLI, Cursor, OpenAI Codex, Goose, and other AI clients supporting the [Agent Skills Standard](https://agentskills.io). > **Not** the official WhatsApp Business / Cloud API. This links as a companion > device (like WhatsApp Web) to a personal WhatsApp account. ## Features - **Pair** — One-time QR link; ASCII QR printed in the terminal - **Send text / image** — 1:1 chats; images: jpg/png/webp up to 16MB - **Groups** — Fetch metadata (JSON) and send group text - **Receipts** — Blue-tick messages (`mark-read`); optional auto-read in `listen` - **Presence / typing** — Global available/unavailable; composing/paused/recording - **Listen** — Long-running JSONL event stream for every pywhats event - **Managed venv** — Auto-creates `$PYWHATS_HOME/venv` and installs `pywhats` on first run ## Requirements - Python 3.11+ - `bash` (for the bootstrap script) - Network access to WhatsApp + PyPI on first bootstrap - A phone with WhatsApp to scan the pair QR ## Caveats `pywhats` is a young library (0.1.x, text/image only) and an **unofficial** client. Automating a personal account can violate WhatsApp's ToS and risk a ban — use a personal/test number, not production. In testing we found WhatsApp sometimes removes freshly linked devices within a minute or so if the account has seen rapid pair/unpair cycles. The `pair` command detects this and prints recovery steps (remove linked devices on the phone, wait ~15–20 minutes, pair once). ## Quick Start ### 1. Pair a device ```bash skills/whatsapp/scripts/wa.py pair ``` On first run this will: 1. Create `$HOME/.pywhats/venv` (or `$PYWHATS_HOME/venv`), streaming progress 2. `pip install "pywhats>=0.1.1,<0.2"` 3. Print an ASCII QR code (also saved as `<session>.qr.png` for terminals where the ASCII render isn't scannable) On your phone: **WhatsApp → Linked Devices → Link a Device** and scan the QR. When pairing succeeds the CLI prints the device JID, waits briefly for history sync, saves the session, and exits. Re-running `pair` on an already-paired session is a no-op (exits 0). ### 2. Send a message ```bash skills/whatsapp/scripts/wa.py send-text 15550001234 "hello from the skill" skills/whatsapp/scripts/wa.py send-image 15550001234 ./photo.jpg --caption "hi" ``` `<to>` accepts a bare international number without `+`, or a full JID (`...@s.whatsapp.net` / `...@g.us`). ### 3. Listen for events ```bash skills/whatsapp/scripts/wa.py listen --read # one JSON object per line, e.g. # {"event":"message","id":"...","chat":"...","text":"hi",...} ``` ## Command Reference | Command | Description | Key options | |---------|-------------|-------------| | `pair` | Link a new companion device (ASCII QR) | `--session NAME` | | `send-text <to> <text>` | Send 1:1 text; prints message id | `--session` | | `send-image <to> <path>` | Send image; prints message id | `--caption`, `--session` | | `group-info <gid>` | Group metadata as JSON | `--session` | | `group-send <gid> <text>` | Group text (resolves participants) | `--session` | | `mark-read <chat> <ids...>` | Blue-tick message ids | `--sender` (groups), `--session` | | `presence <available\|unavailable>` | Global presence | `--session` | | `typing <to> <composing\|paused>` | Chat presence / typing | `--media audio`, `--session` | | `listen` | Stream events as JSON lines until Ctrl-C | `--read`, `--subscribe JID` (presence), `--events LIST`, `--session` | Global options (go **before** the subcommand, e.g. `wa.py --session work pair`): - `--session NAME` — session file `$PYWHATS_HOME/<NAME>.session` (default `default`, or env `PYWHATS_SESSION`) Presence events only flow after subscribing: `wa.py listen --subscribe 15550001234 --events presence` (this also marks the linked device "available"). Exit codes: `0` success, `1` error / unpaired / logged out, `2` usage error, `130` interrupted (Ctrl-C). ## Runtime layout | Path | Purpose | |------|---------| | `$PYWHATS_HOME` | Default `$HOME/.pywhats` | | `$PYWHATS_HOME/venv` | Managed Python venv with `pywhats` | | `$PYWHATS_HOME/<NAME>.session` | Pairing credentials | | `$PYWHATS_HOME/<NAME>.session.signal.db` | Signal ratchet / keys | Bootstrap script: `scripts/_bootstrap.sh` — creates the venv if needed, ensures `pywhats` + `qrcode` are importable, prints the absolute path to the venv python as its last stdout line. `wa.py` re-execs under that interpreter when started with a system `python3` that lacks pywhats. ## Multi-account ```bash wa.py --session personal pair wa.py --session work pair wa.py --session work send-text 15550001234 "from work session" export PYWHATS_SESSION=work # default for subsequent commands ``` ## Claude Code / agent usage When the agent needs to message you on WhatsApp: ```bash # after a one-time pair skills/whatsapp/scripts/wa.py send-text "$MY_PHONE" "Deploy finished ✅" ``` For full method/event docs when writing custom Python against pywhats, see [references/api.md](references/api.md). ## Security notes - A paired session file is equivalent to a logged-in WhatsApp Web session — protect `$PYWHATS_HOME` (filesystem permissions, backups). - `pywhats` is an unofficial reimplementation of the protocol — do not rely on it for sensitive traffic. - Prefer a secondary/test WhatsApp number for automation. ## License Apache 2.0 (skill packaging). `pywhats` is separately licensed on PyPI. -
SKILL.md 4.2 KB
--- name: whatsapp description: "Send and receive WhatsApp messages via the unofficial linked-device client pywhats (pip install pywhats) — pair with QR, send text/images, group chat, read receipts, presence/typing, and a long-running JSON event stream. Use when the user wants to script WhatsApp as a linked companion device (like WhatsApp Web), pair a device, send a WhatsApp from Python, or listen for inbound messages. Triggers: 'whatsapp', 'send whatsapp', 'pair whatsapp', 'pywhats', 'linked device', 'whatsapp web client'. NOT the official WhatsApp Business/Cloud API." --- # 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 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](references/api.md) — every `Client` method, every event payload, JID construction, and the `download_media` note.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.