agent-messenger 1.15.0 → 2.1.0

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

@@ -0,0 +1,336 @@
+# Common Patterns
+
+## Overview
+
+This guide covers typical workflows for AI agents interacting with WhatsApp using agent-whatsapp.
+
+## Pattern 1: Send a Simple Message
+
+**Use case**: Send a message to a contact or group
+
+```bash
+#!/bin/bash
+
+# By phone number (simplest)
+agent-whatsapp message send +1234567890 "Deployment completed successfully!"
+
+# By JID
+agent-whatsapp message send 1234567890@s.whatsapp.net "Deployment completed!"
+
+# To a group
+agent-whatsapp message send 123456789-123345@g.us "Hello team!"
+
+# With error handling
+RESULT=$(agent-whatsapp message send +1234567890 "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!"
+```
+
+**When to use**: Simple one-off messages where you know the recipient.
+
+## Pattern 2: Discover Chats
+
+**Use case**: Find the right chat to send a message to
+
+```bash
+#!/bin/bash
+
+# List all chats sorted by recent activity
+CHATS=$(agent-whatsapp chat list)
+
+# Find a specific chat by name
+TARGET=$(echo "$CHATS" | jq -r '.[] | select(.name | contains("Alice")) | .id')
+
+if [ -z "$TARGET" ]; then
+  echo "Chat not found"
+  exit 1
+fi
+
+echo "Found chat: $TARGET"
+agent-whatsapp message send "$TARGET" "Hey Alice!"
+```
+
+**When to use**: First time interacting with a chat, or when the user references a chat by name.
+
+## Pattern 3: Search for a Chat
+
+**Use case**: Find a chat by keyword
+
+```bash
+#!/bin/bash
+
+# Search by name
+RESULTS=$(agent-whatsapp chat search "Project Team")
+
+# Pick the first match
+TARGET=$(echo "$RESULTS" | jq -r '.[0].id // empty')
+
+if [ -z "$TARGET" ]; then
+  echo "No matching chats found"
+  exit 1
+fi
+
+agent-whatsapp message send "$TARGET" "Status update: all tests passing."
+```
+
+**When to use**: When you know part of the chat name but not the exact JID.
+
+## Pattern 4: Read Recent Chat History
+
+**Use case**: Catch up on what happened in a chat
+
+```bash
+#!/bin/bash
+
+CHAT="+1234567890"
+
+# Get last 50 messages
+MESSAGES=$(agent-whatsapp message list "$CHAT" --limit 50)
+
+# Display summary
+MSG_COUNT=$(echo "$MESSAGES" | jq 'length')
+echo "Found $MSG_COUNT messages"
+
+# Show messages
+echo "$MESSAGES" | jq -r '.[] | "\(.from // "unknown"): \(.text // "[non-text]")"'
+```
+
+**When to use**: Context gathering, summarizing conversations, catching up on missed messages.
+
+## Pattern 5: Check Unread Messages
+
+**Use case**: See which chats have unread messages
+
+```bash
+#!/bin/bash
+
+# Get all chats
+CHATS=$(agent-whatsapp chat list)
+
+# Filter chats with unread messages
+UNREAD=$(echo "$CHATS" | jq '[.[] | select(.unread_count > 0)]')
+UNREAD_COUNT=$(echo "$UNREAD" | jq 'length')
+
+echo "You have unread messages in $UNREAD_COUNT chats:"
+echo ""
+
+echo "$UNREAD" | jq -r '.[] | "  \(.name // "Unknown") - \(.unread_count) unread"'
+```
+
+**When to use**: Morning catch-up, checking for urgent messages, triage.
+
+## Pattern 6: React to the Latest Message
+
+**Use case**: Acknowledge a message with a reaction
+
+```bash
+#!/bin/bash
+
+CHAT="+1234567890"
+
+# Get the latest message
+MESSAGES=$(agent-whatsapp message list "$CHAT" --limit 1)
+MSG_ID=$(echo "$MESSAGES" | jq -r '.[0].id // empty')
+
+if [ -z "$MSG_ID" ]; then
+  echo "No messages found"
+  exit 1
+fi
+
+# React to it
+agent-whatsapp message react "$CHAT" "$MSG_ID" "👍"
+
+# React to your own outgoing message
+agent-whatsapp message react "$CHAT" "$MSG_ID" "✅" --from-me
+```
+
+**When to use**: Acknowledging messages, confirming receipt, quick responses.
+
+## Pattern 7: Multi-Chat Broadcast
+
+**Use case**: Send the same message to multiple chats
+
+```bash
+#!/bin/bash
+
+MESSAGE="Team meeting in 10 minutes!"
+CHATS=("+1234567890" "+9876543210" "123456789-123345@g.us")
+
+for chat in "${CHATS[@]}"; do
+  echo "Sending to $chat..."
+  RESULT=$(agent-whatsapp message send "$chat" "$MESSAGE")
+
+  if echo "$RESULT" | jq -e '.error' > /dev/null 2>&1; then
+    echo "  Failed: $(echo "$RESULT" | jq -r '.error')"
+  else
+    echo "  Sent"
+  fi
+
+  # Rate limit: be gentle with WhatsApp
+  sleep 3
+done
+```
+
+**When to use**: Announcements, notifications across multiple chats.
+
+**Warning**: WhatsApp monitors for automated behavior. Space out messages and avoid bulk operations.
+
+## Pattern 8: Multi-Account Workflow
+
+**Use case**: Send messages from different WhatsApp accounts
+
+```bash
+#!/bin/bash
+
+# Send from personal account
+agent-whatsapp message send +1234567890 "Personal message" --account 1111111111
+
+# Send from work account
+agent-whatsapp message send +9876543210 "Work update" --account 2222222222
+```
+
+**When to use**: Managing multiple WhatsApp numbers (personal, work, etc.).
+
+## Pattern 9: Error Handling and Retry
+
+**Use case**: Robust message sending with retries
+
+```bash
+#!/bin/bash
+
+send_with_retry() {
+  local chat=$1
+  local message=$2
+  local max_attempts=3
+  local attempt=1
+
+  while [ $attempt -le $max_attempts ]; do
+    echo "Attempt $attempt/$max_attempts..."
+
+    RESULT=$(agent-whatsapp message send "$chat" "$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 WhatsApp account linked"; then
+      echo "Not authenticated. Run: agent-whatsapp auth login --phone <number>"
+      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 "+1234567890" "Important message!"
+```
+
+**When to use**: Production scripts, critical notifications, unreliable networks.
+
+## Best Practices
+
+### 1. Cache Chat JIDs
+
+```bash
+# Good: discover once, reuse
+CHATS=$(agent-whatsapp chat list)
+WORK_CHAT=$(echo "$CHATS" | jq -r '.[] | select(.name | contains("Work")) | .id')
+agent-whatsapp message send "$WORK_CHAT" "Hello"
+agent-whatsapp message send "$WORK_CHAT" "Another message"
+
+# Bad: list chats before every send
+agent-whatsapp chat list  # Wasteful
+agent-whatsapp message send "..." "Hello"
+agent-whatsapp chat list  # Wasteful
+agent-whatsapp message send "..." "Another"
+```
+
+### 2. Use Memory for Known JIDs
+
+Store frequently used chat JIDs in `~/.config/agent-messenger/MEMORY.md` to skip `chat list` calls in future sessions.
+
+### 3. Respect Rate Limits
+
+```bash
+# Good: pause between operations
+for chat in "${CHATS[@]}"; do
+  agent-whatsapp message send "$chat" "$MSG"
+  sleep 3
+done
+
+# Bad: rapid-fire
+for chat in "${CHATS[@]}"; do
+  agent-whatsapp message send "$chat" "$MSG"
+done
+```
+
+### 4. Check Auth Before Multi-Step Workflows
+
+```bash
+# Good: verify auth upfront
+STATUS=$(agent-whatsapp auth status)
+if echo "$STATUS" | jq -e '.error' > /dev/null 2>&1; then
+  echo "Not authenticated"
+  exit 1
+fi
+
+# Proceed with workflow
+agent-whatsapp chat list
+agent-whatsapp message send ...
+```
+
+## Anti-Patterns
+
+### Don't Poll Too Frequently
+
+```bash
+# Bad: WebSocket connection per poll
+while true; do
+  agent-whatsapp message list "$CHAT" --limit 1
+  sleep 1  # Too aggressive, risk of ban
+done
+
+# Good: reasonable interval
+while true; do
+  agent-whatsapp message list "$CHAT" --limit 1
+  sleep 15
+done
+```
+
+### Don't Spam Chats
+
+```bash
+# Bad: sends 100 separate messages
+for i in {1..100}; do
+  agent-whatsapp message send "$CHAT" "Item $i"
+done
+
+# Good: batch into single message
+MESSAGE="Updates:"
+for i in {1..100}; do
+  MESSAGE="${MESSAGE}"$'\n'"$i. Item $i"
+done
+agent-whatsapp message send "$CHAT" "$MESSAGE"
+```
+
+## See Also
+
+- [Authentication Guide](authentication.md) - Setting up credentials

package/skills/agent-whatsapp/templates/chat-summary.sh

@@ -0,0 +1,122 @@
+#!/bin/bash
+#
+# chat-summary.sh - Generate a summary of WhatsApp chats
+#
+# Usage:
+#   ./chat-summary.sh [--json]
+#
+# Options:
+#   --json  Output raw JSON instead of formatted text
+#
+# Example:
+#   ./chat-summary.sh
+#   ./chat-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-whatsapp &> /dev/null; then
+  echo -e "${RED}Error: agent-whatsapp not found${NC}" >&2
+  echo "" >&2
+  echo "Install it with:" >&2
+  echo "  npm install -g agent-messenger" >&2
+  exit 1
+fi
+
+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}" >&2
+  echo "" >&2
+  echo "Run this to authenticate:" >&2
+  echo "  agent-whatsapp auth login" >&2
+  exit 1
+fi
+
+echo -e "${YELLOW}Fetching chat list...${NC}" >&2
+CHATS_RESULT=$(agent-whatsapp chat list 2>&1) || true
+
+if ! echo "$CHATS_RESULT" | jq -e 'type == "array"' > /dev/null 2>&1; then
+  echo -e "${RED}Failed to get chat list${NC}" >&2
+  if echo "$CHATS_RESULT" | jq -e '.error' > /dev/null 2>&1; then
+    ERROR_MSG=$(echo "$CHATS_RESULT" | jq -r '.error // "Unknown error"')
+  else
+    ERROR_MSG="$CHATS_RESULT"
+  fi
+  echo -e "${RED}Error: $ERROR_MSG${NC}" >&2
+  exit 1
+fi
+
+if [ "$OUTPUT_JSON" = true ]; then
+  echo "$CHATS_RESULT"
+  exit 0
+fi
+
+PHONE=$(echo "$AUTH_STATUS" | jq -r '.phone_number // "Unknown"')
+NAME=$(echo "$AUTH_STATUS" | jq -r '.name // "Unknown"')
+
+CHATS="$CHATS_RESULT"
+CHAT_COUNT=$(echo "$CHATS" | jq 'length')
+UNREAD_COUNT=$(echo "$CHATS" | jq '[.[] | select(.unread_count > 0)] | length')
+
+echo ""
+echo -e "${BOLD}${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo -e "${BOLD}${BLUE}  WhatsApp Chat Summary${NC}"
+echo -e "${BOLD}${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo ""
+echo -e "${BOLD}Account:${NC} $NAME"
+echo -e "${BOLD}Phone:${NC}   $PHONE"
+echo ""
+
+echo -e "${BOLD}${CYAN}Chats (${CHAT_COUNT} total, ${UNREAD_COUNT} with unread)${NC}"
+echo ""
+
+echo -e "${BOLD}${CYAN}Chat List:${NC}"
+echo "$CHATS" | jq -r '
+  .[0:10] |
+  .[] |
+  "  \(.name // .id) (\(.id))\(if .unread_count > 0 then " [" + (.unread_count | tostring) + " unread]" else "" end)"
+'
+if [ "$CHAT_COUNT" -gt 10 ]; then
+  echo "  ... and $((CHAT_COUNT - 10)) more"
+fi
+echo ""
+
+echo -e "${BOLD}${CYAN}Recent Messages:${NC}"
+echo "$CHATS" | jq -r '
+  .[0:5] |
+  .[] |
+  select(.last_message != null) |
+  "  [\(.name // .id)] \(.last_message.text[0:60] // "(media)")\(if ((.last_message.text // "") | length) > 60 then "..." else "" end)"
+'
+echo ""
+
+echo -e "${BOLD}${CYAN}Quick Actions:${NC}"
+echo ""
+echo -e "  ${GREEN}# Send message to a chat${NC}"
+FIRST_CHAT=$(echo "$CHATS" | jq -r '.[0].id // "15551234567"')
+echo -e "  agent-whatsapp message send $FIRST_CHAT \"Hello!\""
+echo ""
+echo -e "  ${GREEN}# List recent messages in a chat${NC}"
+echo -e "  agent-whatsapp message list $FIRST_CHAT --limit 10"
+echo ""
+
+echo -e "${BOLD}${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo ""
+
+SUMMARY_FILE="chat-summary-$(date +%Y%m%d-%H%M%S).json"
+echo "$CHATS_RESULT" > "$SUMMARY_FILE"
+echo -e "${GREEN}✓ Full data saved to: $SUMMARY_FILE${NC}"
+echo ""

package/skills/agent-whatsapp/templates/monitor-chat.sh

@@ -0,0 +1,157 @@
+#!/bin/bash
+#
+# monitor-chat.sh - Monitor a WhatsApp chat for new messages
+#
+# Usage:
+#   ./monitor-chat.sh <chat> [interval]
+#
+# Arguments:
+#   chat     - Phone number or JID to monitor
+#   interval - Polling interval in seconds (default: 10)
+#
+# Example:
+#   ./monitor-chat.sh 15551234567
+#   ./monitor-chat.sh 15551234567@s.whatsapp.net 5
+
+set -euo pipefail
+
+# Check arguments
+if [ $# -lt 1 ]; then
+  echo "Usage: $0 <chat> [interval]"
+  echo ""
+  echo "Examples:"
+  echo "  $0 15551234567          # Monitor chat, poll every 10s"
+  echo "  $0 15551234567 5        # Monitor chat, poll every 5s"
+  exit 1
+fi
+
+CHAT="$1"
+INTERVAL="${2:-10}"  # Default 10 seconds
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# State tracking
+LAST_ID=""
+FIRST_RUN=true
+
+# Function to truncate text
+truncate_text() {
+  local text=$1
+  local max_length=100
+
+  if [ ${#text} -gt $max_length ]; then
+    echo "${text:0:$max_length}..."
+  else
+    echo "$text"
+  fi
+}
+
+# Function to check for new messages
+check_messages() {
+  # Get latest message
+  MESSAGES=$(agent-whatsapp message list "$CHAT" --limit 1 2>&1) || true
+
+  # Check if successful (must be a JSON array)
+  if ! echo "$MESSAGES" | jq -e 'type == "array"' > /dev/null 2>&1; then
+    if echo "$MESSAGES" | jq -e '.error' > /dev/null 2>&1; then
+      ERROR_MSG=$(echo "$MESSAGES" | jq -r '.error // "Unknown error"')
+      echo -e "${RED}Error: $ERROR_MSG${NC}"
+    else
+      echo -e "${RED}Error: $MESSAGES${NC}"
+    fi
+    return 1
+  fi
+
+  # Extract latest message (may be empty array)
+  LATEST_ID=$(echo "$MESSAGES" | jq -r '.[0].id // ""')
+
+  # No messages in chat
+  if [ -z "$LATEST_ID" ]; then
+    if [ "$FIRST_RUN" = true ]; then
+      echo -e "${YELLOW}No messages in chat yet${NC}"
+    fi
+    return 0
+  fi
+
+  # Check if new message
+  if [ "$LATEST_ID" != "$LAST_ID" ]; then
+    # Skip notification on first run (just initialize)
+    if [ "$FIRST_RUN" = false ] && [ -n "$LAST_ID" ]; then
+      # Extract message details
+      TEXT=$(echo "$MESSAGES" | jq -r '.[0].text // ""')
+      SENDER=$(echo "$MESSAGES" | jq -r '.[0].from_name // .[0].from // ""')
+      TIMESTAMP=$(echo "$MESSAGES" | jq -r '.[0].timestamp // ""')
+
+      # Format time
+      TIME=""
+      if [ -n "$TIMESTAMP" ]; then
+        TIME=$(date -r "$TIMESTAMP" "+%Y-%m-%d %H:%M:%S" 2>/dev/null || echo "$TIMESTAMP")
+      fi
+
+      # Display new message
+      echo ""
+      echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+      echo -e "${BLUE}New message in $CHAT${NC}"
+      echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+      if [ -n "$TIME" ]; then
+        echo -e "Time:    $TIME"
+      fi
+      if [ -n "$SENDER" ]; then
+        echo -e "From:    $SENDER"
+      fi
+      echo -e "Message: $(truncate_text "$TEXT")"
+      echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+    fi
+
+    LAST_ID="$LATEST_ID"
+  fi
+
+  FIRST_RUN=false
+  return 0
+}
+
+# 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 ""
+
+# Start monitoring
+echo -e "${GREEN}✓ Monitoring: $CHAT${NC}"
+echo ""
+echo -e "${YELLOW}Monitoring for new messages (polling every ${INTERVAL}s)...${NC}"
+echo -e "${YELLOW}Press Ctrl+C to stop${NC}"
+echo ""
+
+# Trap Ctrl+C for clean exit
+trap 'echo -e "\n${YELLOW}Monitoring stopped${NC}"; exit 0' INT
+
+# Main monitoring loop
+while true; do
+  check_messages || true
+  sleep "$INTERVAL"
+done