Claude Skill

whatsapp

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

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Download sanjay3290-ai-skills-skills_whatsapp-c842558.zip · 18 KB

Install

skills CLI npx skills add https://github.com/sanjay3290/ai-skills/tree/main/skills/whatsapp
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install sanjay3290-ai-skills@llmmart
Git 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 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

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

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

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

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.

No comments yet.

Reviews (0)

No reviews yet.