/agent-whatsapp

name: agent-whatsapp
description: Interact with WhatsApp - send messages, read chats, manage conversations
version: 2.38.0
allowed-tools: Bash(agent-whatsapp:*)
metadata:
  openclaw:
    requires:
      bins:
        - agent-whatsapp
    install:
      - kind: node
        package: agent-messenger
        bins: [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

## Wh