agent-messenger 1.14.0 → 2.0.0

package/skills/agent-whatsappbot/references/common-patterns.md

@@ -0,0 +1,331 @@
+# Common Patterns
+
+## Overview
+
+This guide covers typical workflows for AI agents interacting with WhatsApp Business Cloud API using agent-whatsappbot.
+
+## Pattern 1: Send a Simple Text Message
+
+**Use case**: Send a free-form message within the 24-hour window
+
+```bash
+#!/bin/bash
+
+RECIPIENT="15551234567"
+
+# Direct approach
+agent-whatsappbot message send "$RECIPIENT" "Your order has shipped!"
+
+# With error handling
+RESULT=$(agent-whatsappbot message send "$RECIPIENT" "Hello world")
+if echo "$RESULT" | jq -e '.error' > /dev/null 2>&1; then
+  echo "Failed: $(echo "$RESULT" | jq -r '.error')"
+  exit 1
+fi
+echo "Message sent: $(echo "$RESULT" | jq -r '.messages[0].id')"
+```
+
+**When to use**: Replying to a customer who messaged you within the last 24 hours.
+
+**Note**: Free-form text only works within the 24-hour customer service window. Outside that window, use template messages.
+
+## Pattern 2: Send a Template Message
+
+**Use case**: Send a notification outside the 24-hour window
+
+```bash
+#!/bin/bash
+
+RECIPIENT="15551234567"
+
+# First, check available templates
+agent-whatsappbot template list --pretty
+
+# Get details for a specific template
+agent-whatsappbot template get order_confirmation --pretty
+
+# Send the template
+agent-whatsappbot message send-template "$RECIPIENT" order_confirmation \
+  --language en_US \
+  --components '[{"type":"body","parameters":[{"type":"text","text":"Alice"},{"type":"text","text":"ORD-9876"}]}]'
+```
+
+**When to use**: Proactive notifications, order confirmations, appointment reminders, shipping updates.
+
+**Important**: Templates must be pre-approved in Meta Business Manager before use.
+
+## Pattern 3: Discover Templates
+
+**Use case**: Find the right template and its required parameters
+
+```bash
+#!/bin/bash
+
+# List all templates
+TEMPLATES=$(agent-whatsappbot template list)
+
+# Find a specific template by name
+TEMPLATE=$(agent-whatsappbot template get order_confirmation)
+
+# Extract parameter info
+echo "$TEMPLATE" | jq '.components[] | select(.type == "BODY") | .example'
+```
+
+**When to use**: First time sending templates, or when you need to verify parameter structure.
+
+## Pattern 4: Send Media Messages
+
+**Use case**: Send images or documents to a customer
+
+```bash
+#!/bin/bash
+
+RECIPIENT="15551234567"
+
+# Send an image with caption
+agent-whatsappbot message send-image "$RECIPIENT" \
+  "https://example.com/product-photo.jpg" \
+  --caption "Here's the product you asked about"
+
+# Send a document
+agent-whatsappbot message send-document "$RECIPIENT" \
+  "https://example.com/invoice-2024-01.pdf" \
+  --filename "invoice-2024-01.pdf" \
+  --caption "Your January invoice"
+```
+
+**When to use**: Sharing product images, invoices, receipts, or other files.
+
+**Note**: Files must be provided as publicly accessible URLs. Local file upload is not supported.
+
+## Pattern 5: React to a Message
+
+**Use case**: Acknowledge a customer message with a reaction
+
+```bash
+#!/bin/bash
+
+RECIPIENT="15551234567"
+MESSAGE_ID="wamid.HBgNMTU1NTEyMzQ1NjcVAgA..."
+
+agent-whatsappbot message send-reaction "$RECIPIENT" "$MESSAGE_ID" "👍"
+```
+
+**When to use**: Quick acknowledgment, confirming receipt of a message.
+
+## Pattern 6: Multi-Recipient Notification
+
+**Use case**: Send the same template to multiple recipients
+
+```bash
+#!/bin/bash
+
+TEMPLATE="shipping_update"
+RECIPIENTS=("15551234567" "15559876543" "15551112222")
+
+for recipient in "${RECIPIENTS[@]}"; do
+  echo "Sending to $recipient..."
+  RESULT=$(agent-whatsappbot message send-template "$recipient" "$TEMPLATE" \
+    --language en_US \
+    --components '[{"type":"body","parameters":[{"type":"text","text":"Your package"},{"type":"text","text":"TRACK-12345"}]}]')
+
+  if echo "$RESULT" | jq -e '.error' > /dev/null 2>&1; then
+    echo "  Failed: $(echo "$RESULT" | jq -r '.error')"
+  else
+    echo "  Sent: $(echo "$RESULT" | jq -r '.messages[0].id')"
+  fi
+
+  # Respect rate limits
+  sleep 1
+done
+```
+
+**When to use**: Bulk notifications, shipping updates, appointment reminders.
+
+## Pattern 7: Multi-Account Workflow
+
+**Use case**: Send from different WhatsApp Business numbers
+
+```bash
+#!/bin/bash
+
+# Send from notifications account
+agent-whatsappbot message send-template 15551234567 order_confirmation \
+  --language en_US \
+  --components '[{"type":"body","parameters":[{"type":"text","text":"Alice"},{"type":"text","text":"ORD-001"}]}]' \
+  --account 112233445566
+
+# Send from support account
+agent-whatsappbot message send 15559876543 "We're looking into your issue." \
+  --account 998877665544
+```
+
+**When to use**: Managing multiple business lines (notifications, support, marketing).
+
+## Pattern 8: CI/CD Deployment Notification
+
+**Use case**: Notify a team channel after deployment
+
+```bash
+#!/bin/bash
+
+VERSION="v2.1.0"
+ENVIRONMENT="production"
+STATUS="success"
+RECIPIENT="15559876543"
+
+agent-whatsappbot message send-template "$RECIPIENT" deployment_alert \
+  --language en_US \
+  --components "[{\"type\":\"body\",\"parameters\":[{\"type\":\"text\",\"text\":\"$VERSION\"},{\"type\":\"text\",\"text\":\"$ENVIRONMENT\"},{\"type\":\"text\",\"text\":\"$STATUS\"}]}]"
+```
+
+**When to use**: Automated deployment notifications, build status alerts.
+
+## Pattern 9: Error Handling and Retry
+
+**Use case**: Robust message sending with retries
+
+```bash
+#!/bin/bash
+
+send_with_retry() {
+  local recipient=$1
+  local message=$2
+  local max_attempts=3
+  local attempt=1
+
+  while [ $attempt -le $max_attempts ]; do
+    echo "Attempt $attempt/$max_attempts..."
+
+    RESULT=$(agent-whatsappbot message send "$recipient" "$message" 2>&1)
+
+    if ! echo "$RESULT" | jq -e '.error' > /dev/null 2>&1; then
+      echo "Message sent!"
+      return 0
+    fi
+
+    ERROR=$(echo "$RESULT" | jq -r '.error')
+    echo "Failed: $ERROR"
+
+    # Don't retry auth errors
+    if echo "$ERROR" | grep -q "No credentials"; then
+      echo "Not authenticated. Run: agent-whatsappbot auth set <phone-number-id> <access-token>"
+      return 1
+    fi
+
+    # Don't retry if outside 24h window
+    if echo "$ERROR" | grep -q "outside 24h window"; then
+      echo "Use template messages instead: agent-whatsappbot message send-template ..."
+      return 1
+    fi
+
+    if [ $attempt -lt $max_attempts ]; then
+      SLEEP_TIME=$((attempt * 3))
+      echo "Retrying in ${SLEEP_TIME}s..."
+      sleep $SLEEP_TIME
+    fi
+
+    attempt=$((attempt + 1))
+  done
+
+  echo "Failed after $max_attempts attempts"
+  return 1
+}
+
+# Usage
+send_with_retry "15551234567" "Important update!"
+```
+
+**When to use**: Production scripts, critical notifications, unreliable networks.
+
+## Best Practices
+
+### 1. Cache Template Info
+
+```bash
+# Good: discover once, reuse
+TEMPLATE=$(agent-whatsappbot template get order_confirmation)
+# ... use template info for multiple sends
+
+# Bad: fetch template before every send
+agent-whatsappbot template get order_confirmation  # Wasteful
+agent-whatsappbot message send-template ...
+agent-whatsappbot template get order_confirmation  # Wasteful
+agent-whatsappbot message send-template ...
+```
+
+### 2. Use Memory for Known Templates
+
+Store frequently used template names and their parameters in `~/.config/agent-messenger/MEMORY.md` to skip `template list` calls in future sessions.
+
+### 3. Respect Rate Limits
+
+```bash
+# Good: pause between operations
+for recipient in "${RECIPIENTS[@]}"; do
+  agent-whatsappbot message send-template "$recipient" "$TEMPLATE" ...
+  sleep 1
+done
+
+# Bad: rapid-fire
+for recipient in "${RECIPIENTS[@]}"; do
+  agent-whatsappbot message send-template "$recipient" "$TEMPLATE" ...
+done
+```
+
+### 4. Check Auth Before Multi-Step Workflows
+
+```bash
+# Good: verify auth upfront
+STATUS=$(agent-whatsappbot auth status)
+if echo "$STATUS" | jq -e '.error' > /dev/null 2>&1; then
+  echo "Not authenticated"
+  exit 1
+fi
+
+# Proceed with workflow
+agent-whatsappbot template list
+agent-whatsappbot message send-template ...
+```
+
+### 5. Use Templates for Proactive Messages
+
+```bash
+# Bad: will fail outside 24h window
+agent-whatsappbot message send 15551234567 "Your order shipped!"
+
+# Good: works anytime
+agent-whatsappbot message send-template 15551234567 shipping_update \
+  --language en_US \
+  --components '...'
+```
+
+## Anti-Patterns
+
+### Don't Send Free-Form Text Outside 24h Window
+
+```bash
+# Bad: will fail if customer hasn't messaged recently
+agent-whatsappbot message send 15551234567 "Reminder: your appointment is tomorrow"
+
+# Good: use a template
+agent-whatsappbot message send-template 15551234567 appointment_reminder \
+  --language en_US \
+  --components '...'
+```
+
+### Don't Hardcode Template Parameters
+
+```bash
+# Bad: fragile if template changes
+agent-whatsappbot message send-template 15551234567 order_confirmation \
+  --components '[{"type":"body","parameters":[{"type":"text","text":"Alice"}]}]'
+
+# Good: verify template structure first
+TEMPLATE=$(agent-whatsappbot template get order_confirmation)
+# Check required parameters, then build components dynamically
+```
+
+## See Also
+
+- [Authentication Guide](authentication.md) - Setting up API credentials

package/skills/agent-whatsappbot/templates/account-summary.sh

@@ -0,0 +1,127 @@
+#!/bin/bash
+#
+# account-summary.sh - Generate a summary of WhatsApp Business account and templates
+#
+# Usage:
+#   ./account-summary.sh [--json]
+#
+# Options:
+#   --json  Output raw JSON instead of formatted text
+#
+# Example:
+#   ./account-summary.sh
+#   ./account-summary.sh --json > summary.json
+
+set -euo pipefail
+
+OUTPUT_JSON=false
+if [ $# -gt 0 ] && [ "$1" = "--json" ]; then
+  OUTPUT_JSON=true
+fi
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+CYAN='\033[0;36m'
+BOLD='\033[1m'
+NC='\033[0m'
+
+if ! command -v agent-whatsappbot &> /dev/null; then
+  echo -e "${RED}Error: agent-whatsappbot not found${NC}" >&2
+  echo "" >&2
+  echo "Install it with:" >&2
+  echo "  npm install -g agent-messenger" >&2
+  exit 1
+fi
+
+AUTH_STATUS=$(agent-whatsappbot auth status 2>&1) || true
+
+if ! echo "$AUTH_STATUS" | jq -e '.valid' > /dev/null 2>&1; then
+  echo -e "${RED}Not authenticated!${NC}" >&2
+  echo "" >&2
+  echo "Run this to authenticate:" >&2
+  echo "  agent-whatsappbot auth set <phone-number-id> <access-token>" >&2
+  exit 1
+fi
+
+echo -e "${YELLOW}Fetching account info and templates...${NC}" >&2
+TEMPLATES_RESULT=$(agent-whatsappbot template list 2>&1) || true
+
+if ! echo "$TEMPLATES_RESULT" | jq -e '.templates' > /dev/null 2>&1; then
+  echo -e "${RED}Failed to get template list${NC}" >&2
+  if echo "$TEMPLATES_RESULT" | jq -e '.error' > /dev/null 2>&1; then
+    ERROR_MSG=$(echo "$TEMPLATES_RESULT" | jq -r '.error // "Unknown error"')
+  else
+    ERROR_MSG="$TEMPLATES_RESULT"
+  fi
+  echo -e "${RED}Error: $ERROR_MSG${NC}" >&2
+  exit 1
+fi
+
+if [ "$OUTPUT_JSON" = true ]; then
+  jq -n \
+    --argjson auth "$AUTH_STATUS" \
+    --argjson templates "$TEMPLATES_RESULT" \
+    '{"auth": $auth, "templates": $templates}'
+  exit 0
+fi
+
+PHONE_ID=$(echo "$AUTH_STATUS" | jq -r '.phone_number_id // "Unknown"')
+DISPLAY_PHONE=$(echo "$AUTH_STATUS" | jq -r '.phone_number_id // "Unknown"')
+ACCOUNT_NAME=$(echo "$AUTH_STATUS" | jq -r '.account_name // "Unknown"')
+
+TEMPLATES=$(echo "$TEMPLATES_RESULT" | jq '.templates // []')
+TEMPLATE_COUNT=$(echo "$TEMPLATES" | jq 'length')
+APPROVED_COUNT=$(echo "$TEMPLATES" | jq '[.[] | select(.status == "APPROVED")] | length')
+PENDING_COUNT=$(echo "$TEMPLATES" | jq '[.[] | select(.status == "PENDING")] | length')
+
+echo ""
+echo -e "${BOLD}${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo -e "${BOLD}${BLUE}  WhatsApp Business Account Summary${NC}"
+echo -e "${BOLD}${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo ""
+echo -e "${BOLD}Account:${NC}  $ACCOUNT_NAME"
+echo -e "${BOLD}Phone:${NC}    $DISPLAY_PHONE"
+echo -e "${BOLD}Phone ID:${NC} $PHONE_ID"
+echo ""
+
+echo -e "${BOLD}${CYAN}Templates (${TEMPLATE_COUNT} total)${NC}"
+echo -e "  Approved: $APPROVED_COUNT"
+echo -e "  Pending:  $PENDING_COUNT"
+echo ""
+
+echo -e "${BOLD}${CYAN}Template List:${NC}"
+echo "$TEMPLATES" | jq -r '
+  .[0:10] |
+  .[] |
+  "  \(.name) [\(.language)] — \(.status)\(if .category then " (\(.category))" else "" end)"
+'
+if [ "$TEMPLATE_COUNT" -gt 10 ]; then
+  echo "  ... and $((TEMPLATE_COUNT - 10)) more"
+fi
+echo ""
+
+echo -e "${BOLD}${CYAN}Quick Actions:${NC}"
+echo ""
+echo -e "  ${GREEN}# Send a template message${NC}"
+FIRST_TEMPLATE=$(echo "$TEMPLATES" | jq -r '.[0].name // "hello_world"')
+echo -e "  agent-whatsappbot message send-template 15551234567 $FIRST_TEMPLATE"
+echo ""
+echo -e "  ${GREEN}# Send a plain text message${NC}"
+echo -e "  agent-whatsappbot message send 15551234567 \"Hello!\""
+echo ""
+echo -e "  ${GREEN}# List all templates${NC}"
+echo -e "  agent-whatsappbot template list"
+echo ""
+
+echo -e "${BOLD}${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo ""
+
+SUMMARY_FILE="account-summary-$(date +%Y%m%d-%H%M%S).json"
+jq -n \
+  --argjson auth "$AUTH_STATUS" \
+  --argjson templates "$TEMPLATES_RESULT" \
+  '{"auth": $auth, "templates": $templates}' > "$SUMMARY_FILE"
+echo -e "${GREEN}✓ Full data saved to: $SUMMARY_FILE${NC}"
+echo ""

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

@@ -0,0 +1,120 @@
+#!/bin/bash
+#
+# post-message.sh - Send a message via WhatsApp Business Cloud API
+#
+# Usage:
+#   ./post-message.sh <to> <message>
+#
+# Arguments:
+#   to      - Recipient phone number (e.g. 15551234567)
+#   message - Message text to send
+#
+# Example:
+#   ./post-message.sh 15551234567 "Hello from script!"
+#   ./post-message.sh 15551234567 "Deployment completed ✅"
+
+set -euo pipefail
+
+# Check arguments
+if [ $# -lt 2 ]; then
+  echo "Usage: $0 <to> <message>"
+  echo ""
+  echo "Examples:"
+  echo "  $0 15551234567 'Hello world!'"
+  echo "  $0 15551234567 'Build completed'"
+  exit 1
+fi
+
+TO="$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 to=$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-whatsappbot message send "$to" "$message" 2>&1) || true
+
+    # Check if successful
+    if echo "$RESULT" | jq -e '.messages' > /dev/null 2>&1; then
+      echo -e "${GREEN}✓ Message sent successfully!${NC}"
+
+      # Extract message details
+      MSG_ID=$(echo "$RESULT" | jq -r '.messages[0].id // ""')
+
+      echo ""
+      echo "Message details:"
+      echo "  To: $to"
+      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-whatsappbot is installed
+if ! command -v agent-whatsappbot &> /dev/null; then
+  echo -e "${RED}Error: agent-whatsappbot 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-whatsappbot auth status 2>&1) || true
+
+if ! echo "$AUTH_STATUS" | jq -e '.valid' > /dev/null 2>&1; then
+  echo -e "${RED}Not authenticated!${NC}"
+  echo ""
+  echo "Run this to authenticate:"
+  echo "  agent-whatsappbot auth set <phone-number-id> <access-token>"
+  exit 1
+fi
+
+PHONE_ID=$(echo "$AUTH_STATUS" | jq -r '.phone_number_id // "Unknown"')
+echo -e "${GREEN}✓ Authenticated (Phone ID: $PHONE_ID)${NC}"
+echo ""
+
+# Send the message
+echo "Sending message to $TO..."
+echo "Message: $MESSAGE"
+echo ""
+
+send_message "$TO" "$MESSAGE"