idanbeck 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:
- First, show them the complete message details:
- Recipient (phone number or group)
- Full message text
- Session being used
- Ask: "Do you want me to send this WhatsApp message?"
- ONLY run the send command AFTER the user explicitly confirms
- NEVER send without confirmation
First-Time Setup
cd ~/.claude/skills/whatsapp-skill
npm install
This installs:
whatsapp-web.js- WhatsApp Web automationqrcode-terminal- QR code display for authentication
Authentication
First time requires scanning a QR code with your phone:
node ~/.claude/skills/whatsapp-skill/whatsapp_skill.js auth
- QR code appears in terminal
- Open WhatsApp on your phone
- Go to Settings → Linked Devices → Link a Device
- Scan the QR code
- Session is saved for future use
Commands
Authentication & Status
# 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)
# 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
# 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
# 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:
# 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:
14155551234@c.us - Group chats:
120363123456789012@g.us
Examples
Send a Quick Message
node ~/.claude/skills/whatsapp-skill/whatsapp_skill.js send 14155551234 "Meeting at 3pm today?"
Check Recent Chats
node ~/.claude/skills/whatsapp-skill/whatsapp_skill.js chats --limit 5
Read Messages from a Contact
node ~/.claude/skills/whatsapp-skill/whatsapp_skill.js messages 14155551234@c.us --limit 10
Search for Something
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