agent-messenger 1.14.0 → 2.0.0

package/skills/agent-whatsapp/templates/post-message.sh

@@ -0,0 +1,120 @@
+#!/bin/bash
+#
+# post-message.sh - Send a message to WhatsApp with error handling
+#
+# Usage:
+#   ./post-message.sh <chat> <message>
+#
+# Arguments:
+#   chat    - Phone number (e.g. 15551234567) or JID (e.g. 15551234567@s.whatsapp.net)
+#   message - Message text to send
+#
+# Example:
+#   ./post-message.sh 15551234567 "Hello from script!"
+#   ./post-message.sh 15551234567@s.whatsapp.net "Deployment completed ✅"
+
+set -euo pipefail
+
+# Check arguments
+if [ $# -lt 2 ]; then
+  echo "Usage: $0 <chat> <message>"
+  echo ""
+  echo "Examples:"
+  echo "  $0 15551234567 'Hello world!'"
+  echo "  $0 15551234567@s.whatsapp.net 'Build completed'"
+  exit 1
+fi
+
+CHAT="$1"
+MESSAGE="$2"
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Function to send message with retry logic
+send_message() {
+  local chat=$1
+  local message=$2
+  local max_attempts=3
+  local attempt=1
+
+  while [ $attempt -le $max_attempts ]; do
+    echo -e "${YELLOW}Attempt $attempt/$max_attempts...${NC}"
+
+    # Send message and capture result
+    RESULT=$(agent-whatsapp message send "$chat" "$message" 2>&1) || true
+
+    # Check if successful
+    if echo "$RESULT" | jq -e '.id' > /dev/null 2>&1; then
+      echo -e "${GREEN}✓ Message sent successfully!${NC}"
+
+      # Extract message details
+      MSG_ID=$(echo "$RESULT" | jq -r '.id // ""')
+
+      echo ""
+      echo "Message details:"
+      echo "  Chat: $chat"
+      if [ -n "$MSG_ID" ]; then
+        echo "  Message ID: $MSG_ID"
+      fi
+
+      return 0
+    fi
+
+    # Extract error information
+    if echo "$RESULT" | jq -e '.error' > /dev/null 2>&1; then
+      ERROR_MSG=$(echo "$RESULT" | jq -r '.error // "Unknown error"')
+
+      echo -e "${RED}✗ Failed: $ERROR_MSG${NC}"
+    else
+      echo -e "${RED}✗ Unexpected error: $RESULT${NC}"
+    fi
+
+    # Exponential backoff before retry
+    if [ $attempt -lt $max_attempts ]; then
+      SLEEP_TIME=$((attempt * 2))
+      echo "Retrying in ${SLEEP_TIME}s..."
+      sleep $SLEEP_TIME
+    fi
+
+    attempt=$((attempt + 1))
+  done
+
+  echo -e "${RED}Failed after $max_attempts attempts${NC}"
+  return 1
+}
+
+# Check if agent-whatsapp is installed
+if ! command -v agent-whatsapp &> /dev/null; then
+  echo -e "${RED}Error: agent-whatsapp not found${NC}"
+  echo ""
+  echo "Install it with:"
+  echo "  npm install -g agent-messenger"
+  exit 1
+fi
+
+# Check authentication
+echo "Checking authentication..."
+AUTH_STATUS=$(agent-whatsapp auth status 2>&1) || true
+
+if ! echo "$AUTH_STATUS" | jq -e '.account_id' > /dev/null 2>&1; then
+  echo -e "${RED}Not authenticated!${NC}"
+  echo ""
+  echo "Run this to authenticate:"
+  echo "  agent-whatsapp auth login"
+  exit 1
+fi
+
+PHONE=$(echo "$AUTH_STATUS" | jq -r '.phone_number // "Unknown"')
+echo -e "${GREEN}✓ Authenticated as: $PHONE${NC}"
+echo ""
+
+# Send the message
+echo "Sending message to $CHAT..."
+echo "Message: $MESSAGE"
+echo ""
+
+send_message "$CHAT" "$MESSAGE"

package/skills/agent-whatsappbot/SKILL.md

@@ -0,0 +1,371 @@
+---
+name: agent-whatsappbot
+description: Interact with WhatsApp using Cloud API credentials - send messages, manage templates
+version: 2.0.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
+
+```bash
+# 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:
+
+```bash
+# 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
+
+```bash
+# 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
+
+```markdown
+# 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
+
+```bash
+# 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
+```
+
+### Message Commands
+
+```bash
+# Send a text message
+agent-whatsappbot message send <to> <text>
+agent-whatsappbot message send 15551234567 "Your order has shipped!"
+
+# Send a template message
+agent-whatsappbot message send-template <to> <template-name>
+agent-whatsappbot message send-template 15551234567 order_confirmation --language en_US --components '[{"type":"body","parameters":[{"type":"text","text":"Alice"},{"type":"text","text":"ORD-9876"}]}]'
+
+# Send a reaction to a message
+agent-whatsappbot message send-reaction <to> <message-id> <emoji>
+agent-whatsappbot message send-reaction 15551234567 wamid.abc123 "👍"
+
+# Send an image
+agent-whatsappbot message send-image <to> <url>
+agent-whatsappbot message send-image 15551234567 "https://example.com/photo.jpg" --caption "Product photo"
+
+# Send a document
+agent-whatsappbot message send-document <to> <url>
+agent-whatsappbot message send-document 15551234567 "https://example.com/invoice.pdf" --filename "invoice.pdf" --caption "Your invoice"
+```
+
+### Template Commands
+
+```bash
+# List message templates
+agent-whatsappbot template list
+agent-whatsappbot template list --limit 20
+
+# Get template details
+agent-whatsappbot template get <template-name>
+agent-whatsappbot template get order_confirmation
+```
+
+## Output Format
+
+### JSON (Default)
+
+All commands output JSON by default for AI consumption:
+
+```json
+{
+  "messaging_product": "whatsapp",
+  "contacts": [{ "input": "15551234567", "wa_id": "15551234567" }],
+  "messages": [{ "id": "wamid.HBgNMTU1NTEyMzQ1NjcVAgA..." }]
+}
+```
+
+### Pretty (Human-Readable)
+
+Use `--pretty` flag for formatted output:
+
+```bash
+agent-whatsappbot template list --pretty
+```
+
+## Global Options
+
+| Option          | Description                                |
+| --------------- | ------------------------------------------ |
+| `--pretty`      | Human-readable output instead of JSON      |
+| `--account <id>`| Use a specific account for this command     |
+
+## Common Patterns
+
+### Send a notification outside the 24h window
+
+Template messages are required when the customer hasn't messaged you in the last 24 hours. Always check your available templates first:
+
+```bash
+# List templates to find the right one
+agent-whatsappbot template list --pretty
+
+# Get template details to see required parameters
+agent-whatsappbot template get order_confirmation --pretty
+
+# Send the template message
+agent-whatsappbot message send-template 15551234567 order_confirmation \
+  --language en_US \
+  --components '[{"type":"body","parameters":[{"type":"text","text":"Alice"},{"type":"text","text":"ORD-9876"}]}]'
+```
+
+### Send a free-form reply within the 24h window
+
+When a customer has messaged you within the last 24 hours, you can send any text:
+
+```bash
+agent-whatsappbot message send 15551234567 "Thanks for reaching out! We'll look into this right away."
+```
+
+### Send a document with a receipt
+
+```bash
+agent-whatsappbot message send-document 15551234567 "https://example.com/receipt.pdf" \
+  --filename "receipt-2024-01.pdf" \
+  --caption "Here's your receipt for January"
+```
+
+### CI/CD deployment notification
+
+```bash
+agent-whatsappbot message send-template 15559876543 deployment_alert \
+  --language en_US \
+  --components '[{"type":"body","parameters":[{"type":"text","text":"v2.1.0"},{"type":"text","text":"production"},{"type":"text","text":"success"}]}]'
+```
+
+## Error Handling
+
+All commands return consistent error format:
+
+```json
+{
+  "error": "No credentials. Run \"auth set <phone-number-id> <access-token>\" first."
+}
+```
+
+Common errors: `No credentials`, `Account not found`, `Template not found`, `Invalid phone number format`, `Message failed to send (outside 24h window, use a template)`.
+
+## Configuration
+
+Credentials stored in `~/.config/agent-messenger/whatsappbot-credentials.json` (0600 permissions).
+
+Config format:
+
+```json
+{
+  "current": { "account_id": "112233445566" },
+  "accounts": {
+    "112233445566": {
+      "account_id": "112233445566",
+      "phone_number_id": "112233445566",
+      "phone_number": "+1 555 012 3456",
+      "access_token": "..."
+    }
+  }
+}
+```
+
+## Limitations
+
+- **Cannot list or read received messages** — WhatsApp Cloud API delivers inbound messages via webhooks only. This CLI is send-only.
+- **Template messages required outside 24h window** — Free-form text only works within 24 hours of the customer's last message to you.
+- **Business verification required for higher tiers** — Unverified businesses are limited in daily messaging volume.
+- **Rate limits** — Tier 0-3: 80 messages per second. Tier 4: 1,000 messages per second.
+- **No group chat support** — WhatsApp Cloud API does not support group messaging.
+- **No real-time events / WebSocket connection** — Inbound messages require a separate webhook server.
+- **No message editing or deletion**
+- **No file upload from local disk** — Images and documents must be provided as URLs.
+- **No voice or video calls**
+- **Phone number must be registered with WhatsApp Business** — Personal WhatsApp numbers won't work.
+
+## Troubleshooting
+
+### `agent-whatsappbot: command not found`
+
+**`agent-whatsappbot` is NOT the npm package name.** The npm package is `agent-messenger`.
+
+If the package is installed globally, use `agent-whatsappbot` directly:
+
+```bash
+agent-whatsappbot message send 15551234567 "Hello"
+```
+
+If the package is NOT installed, run it directly with `npx -y`:
+
+```bash
+npx -y agent-messenger whatsappbot message send 15551234567 "Hello"
+```
+
+> **Note**: If the user prefers a different package runner (e.g., `bunx`, `pnpx`, `pnpm dlx`), use that instead.
+
+**NEVER run `npx agent-whatsappbot`, `bunx agent-whatsappbot`, or `pnpm dlx agent-whatsappbot`**. It will fail or install a wrong package since `agent-whatsappbot` is not the npm package name.
+
+### How to get API credentials
+
+1. Go to [Meta Business Manager](https://business.facebook.com/)
+2. Navigate to your WhatsApp Business Account
+3. Open **WhatsApp Manager > Phone Numbers** to find your **Phone Number ID**
+4. Go to **Business Settings > System Users** to create a system user and generate an **Access Token** with `whatsapp_business_messaging` permission
+5. Run `agent-whatsappbot auth set <phone-number-id> <access-token>`
+
+### Template messages not sending
+
+- Verify the template exists: `agent-whatsappbot template get <name>`
+- Check the template status is `APPROVED` (not `PENDING` or `REJECTED`)
+- Ensure the `--language` matches the template's language code exactly
+- Verify `--components` JSON matches the template's parameter structure
+
+### Rate limiting
+
+WhatsApp enforces rate limits based on your business tier. The CLI automatically retries on rate limit (429) responses. For bulk operations, add delays between requests to avoid hitting limits.
+
+### Message not delivered
+
+- Confirm the recipient's phone number is on WhatsApp
+- Use full international format without `+` prefix (e.g., `15551234567` not `+1-555-123-4567`)
+- If outside the 24h window, use `message send-template` instead of `message send`
+- Check that your WhatsApp Business account is active and not restricted

package/skills/agent-whatsappbot/references/authentication.md

@@ -0,0 +1,216 @@
+# Authentication Guide
+
+## Overview
+
+agent-whatsappbot uses the WhatsApp Business Cloud API with Phone Number ID + Access Token authentication. Credentials come from Meta Business Manager. No desktop app extraction or pairing codes needed.
+
+## API Credential Setup
+
+### How It Works
+
+1. You create a System User in Meta Business Manager
+2. Generate an Access Token with `whatsapp_business_messaging` permission
+3. Find your Phone Number ID in WhatsApp Manager
+4. Store both in the CLI with `auth set`
+
+The CLI validates credentials against the WhatsApp Cloud API before saving.
+
+### Setting Credentials
+
+```bash
+agent-whatsappbot auth set <phone-number-id> <access-token>
+```
+
+Response on success:
+
+```json
+{"success":true,"phone_number_id":"112233445566","account_name":"..."}
+```
+
+Response on failure:
+
+```json
+{
+  "error": "Invalid credentials. Check your Phone Number ID and Access Token."
+}
+```
+
+### Getting Credentials from Meta Business Manager
+
+1. Go to [Meta Business Manager](https://business.facebook.com/)
+2. Navigate to your WhatsApp Business Account
+3. **Phone Number ID**: Open **WhatsApp Manager > Phone Numbers**. The Phone Number ID is displayed next to each registered number.
+4. **Access Token**: Go to **Business Settings > System Users**. Create a system user (or use an existing one), then generate a token with the `whatsapp_business_messaging` permission.
+5. Run `agent-whatsappbot auth set <phone-number-id> <access-token>`
+
+### Permanent vs Temporary Tokens
+
+Meta provides two types of tokens:
+
+- **Temporary tokens** expire after 24 hours. Good for testing.
+- **Permanent tokens** (System User tokens) don't expire. Use these for production and CI/CD.
+
+To create a permanent token, use a System User in Meta Business Manager rather than the temporary token from the API Setup page.
+
+## Multi-Account Management
+
+Multiple WhatsApp Business accounts can be stored simultaneously.
+
+### List Accounts
+
+```bash
+agent-whatsappbot auth list
+```
+
+```json
+[
+  {
+    "account_id": "112233445566",
+    "phone_number_id": "112233445566",
+    "phone_number": "+1 555 012 3456",
+    "current": true
+  },
+  {
+    "account_id": "998877665544",
+    "phone_number_id": "998877665544",
+    "phone_number": "+44 20 7946 0958",
+    "current": false
+  }
+]
+```
+
+### Switch Account
+
+```bash
+agent-whatsappbot auth use 998877665544
+```
+
+### Per-Command Account
+
+Commands that operate on account-scoped data accept `--account <id>` to use a specific account without switching:
+
+```bash
+agent-whatsappbot message send 15551234567 "Hello" --account 998877665544
+agent-whatsappbot template list --account 998877665544
+```
+
+### Remove Account
+
+```bash
+agent-whatsappbot auth remove <account-id>
+```
+
+## Credential Storage
+
+### Location
+
+```
+~/.config/agent-messenger/whatsappbot-credentials.json
+```
+
+### Format
+
+```json
+{
+  "current": { "account_id": "112233445566" },
+  "accounts": {
+    "112233445566": {
+      "phone_number_id": "112233445566",
+      "account_name": "...",
+      "access_token": "..."
+    }
+  }
+}
+```
+
+### Security
+
+- File permissions: `0600` (owner read/write only)
+- Access tokens are stored in plaintext
+- Keep this file secure. The token grants full messaging access to your WhatsApp Business account
+- Never commit to version control
+
+## Authentication Status
+
+Check current auth state:
+
+```bash
+agent-whatsappbot auth status
+```
+
+Output when authenticated:
+
+```json
+{
+  "authenticated": true,
+  "account_id": "112233445566",
+  "phone_number_id": "112233445566",
+  "phone_number": "+1 555 012 3456"
+}
+```
+
+Output when not authenticated:
+
+```json
+{
+  "error": "No credentials. Run \"auth set <phone-number-id> <access-token>\" first."
+}
+```
+
+Check a specific account:
+
+```bash
+agent-whatsappbot auth status --account 998877665544
+```
+
+## Clear Credentials
+
+Remove all stored credentials:
+
+```bash
+agent-whatsappbot auth clear
+```
+
+## Token Lifecycle
+
+### When Tokens Expire
+
+- **Temporary tokens** expire after 24 hours
+- **System User tokens** (permanent) don't expire unless manually revoked
+- Tokens are invalidated if the System User is deleted or permissions are changed
+
+### Re-authentication
+
+If commands start failing with auth errors:
+
+```bash
+# Check current status
+agent-whatsappbot auth status
+
+# Re-set credentials with a fresh token
+agent-whatsappbot auth set <phone-number-id> <new-access-token>
+
+# Verify it worked
+agent-whatsappbot auth status
+```
+
+## Security Considerations
+
+### What agent-whatsappbot Can Access
+
+With stored credentials, agent-whatsappbot can:
+
+- Send text messages to any WhatsApp user
+- Send template messages
+- Send images and documents (via URL)
+- Send reactions to messages
+- List and inspect message templates
+
+### What agent-whatsappbot Cannot Do
+
+- Read or list received messages (webhook-only for inbound)
+- Access group chats
+- Make voice or video calls
+- Manage WhatsApp Business settings
+- Upload files from local disk
+- Edit or delete sent messages