SkillAgentSearch skills...

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

Install / Use

npx skills add sanjay3290/ai-skills --skill whatsapp

Installs into whichever agent you are using.

About this skill
📄

SKILL.md

Installable skill definition

Quality Score

83/100

Supported Platforms

Universal

Our assessment of whatsapp

whatsapp scores 83/100 on our quality scale, 3210th of 4,717 Development & Engineering skills we index.

Its SKILL.md is 4.1 KB long, split into 6 sections with 2 code examples: a solid amount of guidance for an agent.

It has 426 GitHub stars, a meaningful sign that others use it.

Substance
26/30
Structure
16/20
Description
15/15
Adoption
11/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated about 2 months ago, so whatsapp is actively maintained.
  • Our last check on 2026-11-07 found the source still online.
  • It is released under the Apache-2.0 license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-10-05. Automated pattern scan on 2026-10-05. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

whatsapp compared with similar skills

All 4 of these similar skills score higher than whatsapp; compare them before choosing.

SkillScoreStarsUpdatedFormat
whatsapp (this skill)by sanjay3290834262mo agoSKILL.md
taste-skillby Leonxlnx100118.3k10d agoCLAUDE.md
Agent-Reachby Panniantong100113.0k10d agoCLAUDE.md
hyperframesby heygen-com10086.4ktodayCLAUDE.md
headroomby headroomlabs-ai10080.1ktodayCLAUDE.md

Frequently asked questions

How do I install whatsapp?
Run npx skills add sanjay3290/ai-skills --skill whatsapp. The install tabs above show the steps for each supported agent.
Which AI agents does whatsapp work with?
It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
Is whatsapp safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is Apache-2.0-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is whatsapp still maintained?
The repository was last updated about 2 months ago, so whatsapp is actively maintained.

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

Related Skills

View on GitHub
GitHub Stars426
CategoryDevelopment
Updated2mo ago
Forks45

Languages

Python

Trust signals

100/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

No cautions