agent-whatsapp

Agent WhatsApp

A Baileys-backed WhatsApp CLI for AI agents. Links as a companion device via QR code or pairing code, so your phone stays connected. Each command connects on demand and disconnects when done.

Use one of these entrypoints:

• Global install: agent-whatsapp ...
• One-off execution: bunx --package agent-messenger agent-whatsapp ...

Key Concepts

Before diving in, a few things about WhatsApp's architecture:

• JID (Jabber ID) = WhatsApp's address format. Individual: 1234567890@s.whatsapp.net. Group: 123456789-123345@g.us. You can pass plain phone numbers and the CLI resolves them to JIDs automatically.
• QR code auth = links the CLI as a companion device by scanning a QR code displayed in the terminal or browser. Open WhatsApp > Linked Devices > Link a Device and scan the code.
• Pairing code auth = links the CLI as a companion device using a numeric code displayed in your terminal. Enter it in WhatsApp on your phone under Linked Devices.
• Connect-on-demand = the CLI opens a WebSocket connection for each command and disconnects afterward. There's no persistent background process.
• Multi-account = multiple WhatsApp accounts can be linked. Use auth list and auth use to switch between them.

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 Flow

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

• QR code (--qr): A QR code is displayed in the terminal and opened in the browser. Scan it with WhatsApp on your phone. No phone number needed.
• Pairing code (--phone): A numeric code is displayed. Enter it in WhatsApp on your phone under Linked Devices > Link with phone number.

Agent Behavior (MANDATORY)

When a command fails because no account is configured, the agent MUST drive the auth flow itself. Never tell the user to run commands. The agent runs everything.

Step 1: Check for existing accounts

agent-whatsapp auth list

If accounts exist, use agent-whatsapp auth use <account-id> and retry the original command.

Step 2: If no accounts, start QR login (preferred)

agent-whatsapp auth login --qr
# -> QR code displayed in terminal + opened in browser
# -> {"next_action":"scan_qr","qr_url":"...","message":"Scan with WhatsApp on your phone"}

Tell the user to scan the QR code with WhatsApp: Settings > Linked Devices > Link a Device > scan the QR code.

Alternative: Pairing code login

If QR scanning is not possible (e.g. headless environment), ask for the phone number and use pairing code:

agent-whatsapp auth login --phone +1234567890
# -> {"pairing_code":"A1B2-C3D4","message":"Enter this code in WhatsApp > Linked Devices > Link with phone number"}

Tell the user the pairing code and ask them to enter it on their phone.

Step 3: Wait for confirmation

The CLI waits until the user confirms on their phone. Once confirmed:

# -> {"authenticated":true,...}

Step 4: Retry the original command

After successful auth, immediately execute whatever the user originally asked for.

Common Auth Commands

agent-whatsapp auth status              # Check current auth state
agent-whatsapp auth status --account <id>  # Check specific account
agent-whatsapp auth list                # List all linked accounts
agent-whatsapp auth use <id>            # Switch active account
agent-whatsapp auth logout              # Unlink current account
agent-whatsapp auth logout --account <id>  # Unlink specific account

Memory

The agent maintains a ~/.config/agent-messenger/MEMORY.md file as persistent memory across sessions. This is agent-managed. The CLI does not read or write this file. Use the Read and Write tools to manage your memory file.

Reading Memory

At the start of every task, read ~/.config/agent-messenger/MEMORY.md using the Read tool to load any previously discovered chat IDs, contact names, and preferences.

• If the file doesn't exist yet, that's fine. Proceed without it and create it when you first have useful information to store.
• If the file can't be read (permissions, missing directory), proceed without memory.

Writing Memory

After discovering useful information, update ~/.config/agent-messenger/MEMORY.md using the Write tool. Write triggers include:

• After discovering chat JIDs and contact names (from chat list)
• After discovering group names and participants
• After the user gives you an alias or preference ("call this the family group", "my work chat is X")

When writing, include the complete file content. The Write tool overwrites the entire file.

What to Store

• Chat JIDs with contact/group names
• Your own phone number and JID
• User-given aliases ("family group", "work chat")
• Commonly referenced chat JIDs
• Any user preference expressed during interaction

What NOT to Store

Never store auth credentials, session keys, or any sensitive data. Never store full message content (just IDs and chat context).

Handling Stale Data

If a memorized JID returns an error, remove it from MEMORY.md. Don't blindly trust memorized data. Prefer re-listing over using a memorized JID that might be stale.

Format / Example

# Agent Messenger Memory

## WhatsApp Account

- Phone: +1234567890
- JID: 1234567890@s.whatsapp.net

## Chats

- `1234567890@s.whatsapp.net` - Alice (1:1)
- `5678901234@s.whatsapp.net` - Bob (1:1)
- `123456789-123345@g.us` - Project Team (group, 8 members)
- `987654321-654321@g.us` - Family (group, 5 members)

## Aliases

- "alice" -> `1234567890@s.whatsapp.net`
- "project" -> `123456789-123345@g.us` (Project Team)
- "family" -> `987654321-654321@g.us` (Family group)

## Notes

- User prefers --pretty output
- Project Team is the most frequently used chat

Memory lets you skip repeated chat list calls. When you already know a JID from a previous session, use it directly.

Commands

Auth Commands

# Link as companion device via QR code (no phone number needed)
agent-whatsapp auth login --qr

# Link as companion device via pairing code
agent-whatsapp auth login --phone +1234567890

# Check auth status
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>

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>

Output includes:

• jid - chat JID (individual or group)
• name - contact or group name
• unread_count - unread message count
• last_message - most recent message preview

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
agent-whatsapp message list +1234567890 --limit 20 --account <id>

# 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!"
agent-whatsapp message send +1234567890 "Hello!" --account <id>

# 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
agent-whatsapp message react +1234567890 ABC123DEF456 "👍" --account <id>

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.

Output Format

JSON (Default)

All commands output JSON by default for AI consumption:

{
  "jid": "1234567890@s.whatsapp.net",
  "name": "Alice",
  "unread_count": 3,
  "last_message": {
    "id": "ABC123DEF456",
    "text": "See you tomorrow!",
    "from": "1234567890@s.whatsapp.net",
    "timestamp": 1705312200
  }
}

Pretty (Human-Readable)

Use --pretty flag for formatted output:

agent-whatsapp chat list --pretty

Global Options

Option	Description
--pretty	Human-readable output instead of JSON
--account <id>	Use a specific account for this command

Common Patterns

Check unread messages

# List chats to see unread counts
agent-whatsapp chat list --limit 20

# Read messages from a specific chat
agent-whatsapp message list +1234567890 --limit 10

Send a message to a contact

# By phone number (simplest)
agent-whatsapp message send +1234567890 "Hey, are we still on for tomorrow?"

# By JID
agent-whatsapp message send 1234567890@s.whatsapp.net "Hey, are we still on for tomorrow?"

Send a message to a group

# Find the group first
agent-whatsapp chat search "Project Team"

# Send to the group JID
agent-whatsapp message send 123456789-123345@g.us "Status update: deployment complete."

React to the latest message

# Get the latest message ID
agent-whatsapp message list +1234567890 --limit 1

# React to it
agent-whatsapp message react +1234567890 <message-id> "👍"

Error Handling

All commands return consistent error format:

{
  "error": "No WhatsApp account linked. Run: agent-whatsapp auth login --qr"
}

Common errors:

• No WhatsApp account linked - not authenticated. Run auth login --qr or auth login --phone <number>.
• Connection timeout - WebSocket connection to WhatsApp failed. Retry the command.
• Invalid JID - malformed phone number or JID. Use international format with + prefix.
• Not a group participant - can't send to a group you're not a member of.

Notes

• JID format: Individual chats use 1234567890@s.whatsapp.net, groups use 123456789-123345@g.us. Phone numbers can be passed directly and are auto-resolved.
• Connect-on-demand: Each command opens a WebSocket connection and closes it when done. There's no persistent daemon or background process.
• Ban risk: WhatsApp monitors for automated behavior. Avoid high-volume messaging, rapid-fire sends, or bulk operations. Space out commands when sending multiple messages.
• Multi-account: Multiple WhatsApp numbers can be linked simultaneously. Use auth list to see all accounts and auth use <id> to switch.
• Phone numbers: Always use international format with country code (e.g. +1234567890, +821012345678).
• agent-whatsapp returns JSON by default and --pretty for indented output.

Troubleshooting

agent-whatsapp: command not found

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

If the package is installed globally, use agent-whatsapp directly:

agent-whatsapp chat list --pretty

If the package is NOT installed, use --package to install and run:

npx -y --package agent-messenger agent-whatsapp chat list --pretty
bunx --package agent-messenger agent-whatsapp chat list --pretty
pnpm dlx --package agent-messenger agent-whatsapp chat list --pretty

NEVER run npx agent-whatsapp, bunx agent-whatsapp, or pnpm dlx agent-whatsapp without --package agent-messenger. It will fail or install a wrong package since agent-whatsapp is not the npm package name.

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

Empty chat list after linking a new device

WhatsApp companion devices receive their chat list from the primary phone — there's no server API to fetch it directly. On a freshly linked device, chat list may return only group chats (or nothing at all) for individual/DM conversations.

• Keep your phone online with WhatsApp open during and after linking. The phone pushes history to the new device; if it's off or WhatsApp is killed, nothing arrives.
• Wait a few minutes and run chat list again. History trickles in over time and is saved locally, so subsequent runs will show more chats.
• Groups always work immediately — they're fetched from the server, not from history sync.
• Sending a message to a known phone number will make that chat appear even if it wasn't in the initial sync.

This is a WhatsApp protocol limitation, not a bug.

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