Verified:GitHub

Send and receive WhatsApp messages via the pywhats linked-device client.

432|47|Updated Dec 22, 2025

Search Tags:#automation #messaging #whatsapp #qr pairing #event stream #pywhats #linked device

Ready to run

npx skills add https://github.com/sanjay3290/ai-skills --skill whatsapp-sanjay3290

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: whatsapp
Source: https://github.com/sanjay3290/ai-skills/tree/main/skills/whatsapp
Command: npx skills add https://github.com/sanjay3290/ai-skills --skill whatsapp-sanjay3290

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires pywhats, qrcode, and includes scripts (resource) and references (resource) components.

What problem does it solve? Automating WhatsApp messaging from scripts or AI agents normally requires the official Business/Cloud API, which is restricted to business accounts. This Skill lets an agent drive a personal WhatsApp account as a linked companion device (like WhatsApp Web) using the unofficial pywhats Python client, enabling programmatic sending, receiving, and presence control. ## Core Features & Use Cases - QR pairing and session management: One-time QR scan links a device; named sessions support multiple accounts, with automatic venv bootstrap and pywhats installation on first run. - Messaging and groups: Send 1:1 text and images (jpg/png/webp up to 16MB), fetch group metadata as JSON, send group messages, mark messages read, and set presence or typing indicators. - Event streaming: The listen command emits a long-running JSON-lines stream of inbound messages, receipts, presence, and history-sync events, with optional auto-read receipts. - Use Case: An AI coding agent finishes a deployment and runs wa.py send-text to notify you on WhatsApp, then uses wa.py listen --read to stream and auto-acknowledge your replies. ## Quick Start Ask the agent to pair WhatsApp by running the wa.py pair command, scan the QR code in WhatsApp Linked Devices, then have it send a text message to your phone number.

Frequently Asked Questions about whatsapp

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I send a WhatsApp message from Python?▼

Use the wa.py CLI: run wa.py pair once to link a device via QR code, then wa.py send-text 15550001234 "hello" to send a message. It uses the pywhats library and prints the message id on success.

How to receive WhatsApp messages programmatically?▼

Run wa.py listen to stream inbound events as JSON lines, one object per message, receipt, or presence update. Add --read to automatically send blue-tick read receipts for incoming messages.

Is pywhats the official WhatsApp Business API?▼

No. pywhats is an unofficial linked-device client that pairs like WhatsApp Web with a personal account. Automating a personal account can violate WhatsApp's terms of service and risk a ban, so use a test number.

Can I send images or files over WhatsApp with pywhats?▼

wa.py send-image supports jpg, png, and webp images up to 16MB with an optional caption. GIFs and other media types are not supported because pywhats 0.1.x handles text and images only.

Why does my WhatsApp device get logged out right after pairing?▼

WhatsApp sometimes reaps freshly linked devices after rapid pair/unpair cycles, known as device churn. Remove all linked devices on the phone, wait 15-20 minutes, then pair once without unpairing.

Does the skill support multiple WhatsApp accounts?▼

Yes. Use the global --session NAME option before the subcommand, for example wa.py --session work pair, to maintain separate session files under $PYWHATS_HOME for each account.