WhatsApp

Tip: After npm install -g agent-messenger, agent-whatsapp is available directly. For one-off execution without a global install you can use npm exec --package agent-messenger agent-whatsapp ..., pnpm dlx --package agent-messenger agent-whatsapp ..., yarn dlx agent-messenger agent-whatsapp ..., or bunx --package agent-messenger agent-whatsapp ....

Requirements

WhatsApp integration uses Baileys, a reverse-engineered WhatsApp Web API:

• Links as a companion device via QR code or pairing code, so your phone stays connected.
• Each command opens a WebSocket connection on demand and disconnects when done. No persistent background process.
• Multiple WhatsApp accounts can be linked simultaneously.

Quick Start

# Link as companion device via QR code (scan with your phone)
agent-whatsapp auth login --qr

# Or link via pairing code (enter the code on your phone)
agent-whatsapp auth login --phone +1234567890

# List chats
agent-whatsapp chat list

# Send a message
agent-whatsapp message send +1234567890 "Hello from agent-whatsapp"

Authentication

The CLI supports two authentication methods. Both register as a companion (linked) device, so your phone session is never affected.

QR Code Login

agent-whatsapp auth login --qr

A QR code is displayed in the terminal and opened in the browser. Scan it with WhatsApp on your phone: Settings > Linked Devices > Link a Device.

Pairing Code Login

agent-whatsapp auth login --phone +1234567890

A numeric pairing code is displayed. Enter it on your phone: WhatsApp > Settings > Linked Devices > Link with phone number.

Account Management

# Check current auth state
agent-whatsapp auth status
agent-whatsapp auth status --account <id>

# List linked accounts
agent-whatsapp auth list

# Switch active account
agent-whatsapp auth use <id>

# Unlink account
agent-whatsapp auth logout
agent-whatsapp auth logout --account <id>

Commands

Whoami Command

# Show current authenticated user
agent-whatsapp whoami
agent-whatsapp whoami --pretty
agent-whatsapp whoami --account <account-id>

Output includes the authenticated user's identity information.

Chat Commands

# List chats (sorted by most recent activity)
agent-whatsapp chat list
agent-whatsapp chat list --limit 50
agent-whatsapp chat list --account <id>

# Search chats by name
agent-whatsapp chat search "project"
agent-whatsapp chat search "project" --limit 10
agent-whatsapp chat search "project" --account <id>

Message Commands

# List messages in a chat
agent-whatsapp message list <chat> --limit 20
agent-whatsapp message list +1234567890 --limit 50
agent-whatsapp message list 123456789-123345@g.us --limit 10

# Send a text message
agent-whatsapp message send <chat> <text>
agent-whatsapp message send +1234567890 "Hello!"
agent-whatsapp message send 123456789-123345@g.us "Hello team!"

# React to a message
agent-whatsapp message react <chat> <message-id> <emoji>
agent-whatsapp message react +1234567890 ABC123DEF456 "👍"
agent-whatsapp message react +1234567890 ABC123DEF456 "👍" --from-me

The <chat> argument accepts:

• Phone number: +1234567890 (auto-resolved to JID)
• Individual JID: 1234567890@s.whatsapp.net
• Group JID: 123456789-123345@g.us

The --from-me flag on message react indicates the target message was sent by you (outgoing). Without it, the reaction targets an incoming message.

Global Options

Storage

• Credentials stored in ~/.config/agent-messenger/whatsapp-credentials.json
• Session data stored in ~/.config/agent-messenger/whatsapp/<account-id>/

Limitations

• Connect-on-demand: Each command opens a WebSocket connection and closes it when done. No persistent daemon.
• Ban risk: WhatsApp monitors for automated behavior. Avoid high-volume messaging, rapid-fire sends, or bulk operations. Space out commands when sending multiple messages.
• No file uploads or downloads
• No voice or video calls
• No status/story support

Troubleshooting

agent-whatsapp: command not found

agent-whatsapp is NOT the npm package name. The npm package is agent-messenger.

# If installed globally
agent-whatsapp chat list --pretty

# If not installed, use --package
npx -y --package agent-messenger agent-whatsapp chat list --pretty

NEVER run npx agent-whatsapp without --package agent-messenger. It will fail or install a wrong package.

QR code not scanning

1. Make sure WhatsApp is open on your phone
2. Go to Settings > Linked Devices > Link a Device
3. Point your phone camera at the QR code in the terminal or browser
4. If the QR code expires, run auth login --qr again for a fresh code
5. If QR scanning fails, try pairing code: auth login --phone <number>

Pairing code not working

1. Make sure WhatsApp is open on your phone
2. Go to Settings > Linked Devices > Link a Device
3. Choose "Link with phone number instead" if you see a QR code
4. Enter the pairing code shown in the terminal
5. If the code expires, run auth login --phone <number> again for a fresh code

Connection drops

WhatsApp may disconnect linked devices that are inactive for extended periods. If commands start failing:

# Check if still linked
agent-whatsapp auth status

# Re-link if needed
agent-whatsapp auth login --qr

AI Agent Integration

See skills/agent-whatsapp/ for:

• Complete skill documentation
• Common patterns for AI agent workflows