/agent-whatsappbot

name: agent-whatsappbot
description: Interact with WhatsApp using Cloud API credentials - send messages, manage templates
version: 2.36.0
allowed-tools: Bash(agent-whatsappbot:*)
metadata:
  openclaw:
    requires:
      bins:
        - agent-whatsappbot
    install:
      - kind: node
        package: agent-messenger
        bins: [agent-whatsappbot]

Agent WhatsAppBot

A TypeScript CLI tool that enables AI agents and humans to send messages through WhatsApp Business Cloud API. Designed for customer notifications, transactional messaging, and CI/CD integrations using Phone Number ID + Access Token authentication.

Key Concepts

Before diving in, a few things about WhatsApp Business Cloud API:

• **Send-only** — The Cloud API is webhook-only for inbound messages. This CLI cannot list or read received messages.
• **Template messages** — Outside the 24-hour customer service window, you must use pre-approved message templates. Free-form text only works within 24 hours of the customer's last message.
• **Phone Number ID** — Your WhatsApp Business phone number's unique identifier (not the phone number itself). Found in Meta Business Manager.
• **Access Token** — A permanent or temporary token from Meta Business Manager with `whatsapp_business_messaging` permission.
• **Meta Business Manager** — All setup (phone numbers, templates, verification) happens at [business.facebook.com](https://business.facebook.com).
• **Rate limits** — Tier 0-3: 80 messages per second. Tier 4: 1,000 messages per second. Tiers are based on business verification and messaging volume.

Quick Start

# Set your API credentials
agent-whatsappbot auth set your-phone-number-id your-access-token

# Verify authentication
agent-whatsappbot auth status

# Send a text message (recipient must have messaged you within 24h)
agent-whatsappbot message send 15551234567 "Hello from the CLI!"

# List available message templates
agent-whatsappbot template list --pretty

Authentication

API Credential Setup

agent-whatsappbot uses Phone Number ID + Access Token pairs from Meta Business Manager:

# Set credentials (validates against WhatsApp Cloud API before saving)
agent-whatsappbot auth set your-phone-number-id your-access-token

# Check auth status
agent-whatsappbot auth status

# Clear stored credentials
agent-whatsappbot auth clear

Multi-Account Management

# List stored accounts
agent-whatsappbot auth list

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

# Remove a stored account
agent-whatsappbot auth remove <account-id>

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 account IDs, template names, recipient numbers, 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. Don't error out.

Writing Memory

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

• After discovering account IDs and phone numbers (from `auth list`, `auth status`, etc.)
• After discovering template names and their parameters (from `template list`, `template get`, etc.)
• After the user gives you an alias or preference ("call this the notifications account", "my main template is X")

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

What to Store

• Account IDs with phone numbers
• Template names with their required parameters
• Frequently used recipient numbers with context
• User-given aliases ("notifications account", "marketing number")
• Any user preference expressed during interaction

What NOT to Store

Never store access tokens or any credentials. Never store full message content (just context). Never store personal user data.

Handling Stale Data

If a memorized template returns an error (template not found, account invalid), remove it from `MEMORY.md`. Don't blindly trust memorized data. Verify when something seems off. Prefer re-listing over using a memorized value that might be stale.

Format / Example

# Agent Messenger Memory

## WhatsApp Accounts

- `112233445566` - Acme Notifications (Phone: +1 555 012 3456)

## Templates (Acme Notifications)

- `order_confirmation` - language: en_US, params: [customer_name, order_id]
- `shipping_update` - language: en_US, params: [customer_name, tracking_number]
- `appointment_reminder` - language: en_US, params: [customer_name, date, time]

## Frequent Recipients

- `15559876543` - Support escalation line
- `15551112222` - QA test number

## Aliases

- "notifications" -> `112233445566` (Acme Notifications)

## Notes

- order_confirmation template requires customer_name and order_id as components
- Business verified at Tier 2 (80 MPS limit)

> Memory lets you skip repeated `template list` calls. When you already know a template name from a previous session, use it directly.

Commands

Auth Commands

# Set account credentials (validates against API)
agent-whatsappbot auth set <phone-number-id> <access-token>

# Check auth status
agent-whatsappbot auth status
agent-whatsappbot auth status --account <account-id>

# List stored accounts
agent-whatsappbot auth list

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

# Remove a stored account
agent-whatsappbot auth remove <account-id>

# Clear all credentials
agent-whatsappbot auth clear

Whoami Command

# Show current authenticated bot
agent-whatsappbot whoami
agent-wh