home / skills / idanbeck / claude-skills / whatsapp-skill

whatsapp-skill skill

This skill helps you manage WhatsApp messaging across multiple accounts by sending, reading, and searching chats via automated sessions.

npx playbooks add skill idanbeck/claude-skills --skill whatsapp-skill

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

5.2 KB

---
name: whatsapp-skill
description: Send and receive WhatsApp messages. Use when the user asks to send WhatsApp messages, check WhatsApp chats, search messages, or manage WhatsApp contacts. Supports multiple accounts via sessions.
allowed-tools: Bash, Read
---

# WhatsApp Skill - Messaging Automation

Send messages, read chats, and search WhatsApp via WhatsApp Web automation.

## CRITICAL: Message Confirmation Required

**Before sending ANY WhatsApp message, you MUST get explicit user confirmation.**

When the user asks to send a message:
1. First, show them the complete message details:
   - Recipient (phone number or group)
   - Full message text
   - Session being used
2. Ask: "Do you want me to send this WhatsApp message?"
3. ONLY run the send command AFTER the user explicitly confirms
4. NEVER send without confirmation

## First-Time Setup

```bash
cd ~/.claude/skills/whatsapp-skill
npm install
```

This installs:
- `whatsapp-web.js` - WhatsApp Web automation
- `qrcode-terminal` - QR code display for authentication

## Authentication

First time requires scanning a QR code with your phone:

```bash
node ~/.claude/skills/whatsapp-skill/whatsapp_skill.js auth
```

1. QR code appears in terminal
2. Open WhatsApp on your phone
3. Go to Settings → Linked Devices → Link a Device
4. Scan the QR code
5. Session is saved for future use

## Commands

### Authentication & Status

```bash
# Authenticate (scan QR)
node ~/.claude/skills/whatsapp-skill/whatsapp_skill.js auth [--session NAME]

# Check status
node ~/.claude/skills/whatsapp-skill/whatsapp_skill.js status [--session NAME]

# Logout
node ~/.claude/skills/whatsapp-skill/whatsapp_skill.js logout [--session NAME]
```

### Sending Messages (Requires Confirmation)

```bash
# Send to phone number (include country code, no + or spaces)
node ~/.claude/skills/whatsapp-skill/whatsapp_skill.js send 14155551234 "Hello!" [--session NAME]

# Send to group
node ~/.claude/skills/whatsapp-skill/whatsapp_skill.js send-group GROUP_ID "Hello group!" [--session NAME]
```

### Reading Chats & Messages

```bash
# List recent chats
node ~/.claude/skills/whatsapp-skill/whatsapp_skill.js chats [--limit N] [--session NAME]

# Get messages from a chat
node ~/.claude/skills/whatsapp-skill/whatsapp_skill.js messages CHAT_ID [--limit N] [--session NAME]

# Search messages
node ~/.claude/skills/whatsapp-skill/whatsapp_skill.js search "query" [--session NAME]
```

### Contacts & Groups

```bash
# List contacts
node ~/.claude/skills/whatsapp-skill/whatsapp_skill.js contacts [--session NAME]

# List groups
node ~/.claude/skills/whatsapp-skill/whatsapp_skill.js groups [--session NAME]
```

## Multi-Account Support

Use `--session` flag for different WhatsApp accounts:

```bash
# Personal account
node ~/.claude/skills/whatsapp-skill/whatsapp_skill.js auth --session personal

# Work account
node ~/.claude/skills/whatsapp-skill/whatsapp_skill.js auth --session work

# Send from specific account
node ~/.claude/skills/whatsapp-skill/whatsapp_skill.js send 14155551234 "Hi" --session work
```

Sessions stored in `~/.claude/skills/whatsapp-skill/sessions/`

## Phone Number Format

Always use full international format without + or spaces:
- US: `14155551234` (1 = country code)
- UK: `447911123456` (44 = country code)
- India: `919876543210` (91 = country code)

## Chat IDs

Chat IDs are returned by the `chats` command:
- Individual chats: `[email protected]`
- Group chats: `[email protected]`

## Examples

### Send a Quick Message

```bash
node ~/.claude/skills/whatsapp-skill/whatsapp_skill.js send 14155551234 "Meeting at 3pm today?"
```

### Check Recent Chats

```bash
node ~/.claude/skills/whatsapp-skill/whatsapp_skill.js chats --limit 5
```

### Read Messages from a Contact

```bash
node ~/.claude/skills/whatsapp-skill/whatsapp_skill.js messages [email protected] --limit 10
```

### Search for Something

```bash
node ~/.claude/skills/whatsapp-skill/whatsapp_skill.js search "meeting agenda"
```

## Output

All commands output JSON for easy parsing.

## Requirements

- Node.js 16+
- npm
- Chrome/Chromium (installed automatically by puppeteer)

## Important Notes

- **One phone per session**: Each WhatsApp account can only be linked to one session at a time
- **Stay connected**: WhatsApp may disconnect if your phone loses internet for extended periods
- **Rate limits**: Don't spam - WhatsApp can ban accounts for suspicious activity
- **Business accounts**: Works with both personal and WhatsApp Business accounts

## Security Notes

- **Message confirmation required** - Claude must confirm before sending any message
- Session data stored in `~/.claude/skills/whatsapp-skill/sessions/`
- Sessions contain authentication data - keep secure
- Logout removes session data from your computer (but device stays linked in WhatsApp until you unlink)

## Troubleshooting

**QR code not appearing?**
- Make sure puppeteer dependencies are installed: `npx puppeteer browsers install chrome`

**Authentication keeps failing?**
- Delete session folder and re-authenticate
- Make sure your phone has internet connection

**Messages not sending?**
- Verify phone number format (country code, no spaces/dashes)
- Check if contact has blocked you
- Verify WhatsApp is still connected on your phone

Overview

This skill automates sending, reading, and searching WhatsApp messages via WhatsApp Web. It supports multiple accounts through session names and returns JSON for easy parsing. Before sending any message, explicit user confirmation is required.

How this skill works

The skill uses a WhatsApp Web automation client to list chats, fetch messages, search content, manage contacts and send messages. Sessions are stored locally so you can authenticate multiple accounts by scanning a QR code once per session. All commands output JSON and support a --session flag to target a specific account.

When to use it

Send a WhatsApp message to a phone or group (only after explicit confirmation)
Check recent chats or read messages from a specific chat
Search message history for keywords or topics
List contacts or groups for mapping and selection
Manage multiple WhatsApp accounts via named sessions

Best practices

Always verify recipient phone numbers in full international format (no + or spaces) before sending
Never send messages without asking the user to confirm the complete send details (recipient, message text, session)
Use the --session flag to separate personal and work accounts and avoid cross-account mistakes
Limit automated send frequency to avoid rate limits or triggering bans
Keep session folders secure; treat session files as sensitive authentication data

Example use cases

Send: Prepare a message to a contact or group, show the recipient, full text and session, then send after user confirmation
Read: List the latest chats and fetch the last N messages from a selected chat for quick context
Search: Find past messages containing meeting notes, links, or keywords across a session
Account management: Authenticate a new session by scanning the QR code and then use that session for later sends
Contact list: Retrieve contacts or groups to display possible recipients and their chat IDs

FAQ

Do I need to scan a QR code every time?

No. You authenticate once per session by scanning the QR code. Session data is saved locally so future runs use the stored session until you logout.

What phone number format should I use?

Use full international format with country code and no + or spaces (e.g., US 14155551234).

Can the skill send messages without my go-ahead?

No. The skill requires explicit user confirmation showing recipient, full message text, and session before executing any send command.