agent-messenger 2.10.1 → 2.11.0

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

@@ -0,0 +1,122 @@
+#!/bin/bash
+#
+# post-message.sh - Send a customer service message via WeChat Official Account API
+#
+# Usage:
+#   ./post-message.sh <openid> <message>
+#
+# Arguments:
+#   openid  - Recipient OpenID (e.g. oABCD1234)
+#   message - Message text to send
+#
+# Example:
+#   ./post-message.sh oABCD1234 "Hello from script!"
+#   ./post-message.sh oABCD1234 "Thanks for your purchase ✅"
+#
+# Note: Customer service messages only work within the 48-hour interaction window.
+# Outside that window, use template messages via send-template.sh.
+
+set -euo pipefail
+
+# Check arguments
+if [ $# -lt 2 ]; then
+  echo "Usage: $0 <openid> <message>"
+  echo ""
+  echo "Examples:"
+  echo "  $0 oABCD1234 'Hello world!'"
+  echo "  $0 oABCD1234 'Build completed'"
+  exit 1
+fi
+
+OPENID="$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 openid=$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-wechatbot message send "$openid" "$message" 2>&1) || true
+
+    # Check if successful (no error field)
+    if ! echo "$RESULT" | jq -e '.error' > /dev/null 2>&1; then
+      echo -e "${GREEN}✓ Message sent successfully!${NC}"
+      echo ""
+      echo "Message details:"
+      echo "  To OpenID: $openid"
+      return 0
+    fi
+
+    # Extract error information
+    ERROR_MSG=$(echo "$RESULT" | jq -r '.error // "Unknown error"')
+    echo -e "${RED}✗ Failed: $ERROR_MSG${NC}"
+
+    # Don't retry on certain errors
+    if echo "$ERROR_MSG" | grep -qE "40164|IP whitelist"; then
+      echo -e "${RED}IP not in WeChat whitelist. Add your server IP in the admin panel.${NC}"
+      return 1
+    fi
+
+    if echo "$ERROR_MSG" | grep -qE "48h|48-hour"; then
+      echo -e "${YELLOW}Outside 48h window. Use a template message instead:${NC}"
+      echo "  ./send-template.sh $openid <template-id> --data '...'"
+      return 1
+    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-wechatbot is installed
+if ! command -v agent-wechatbot &> /dev/null; then
+  echo -e "${RED}Error: agent-wechatbot 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-wechatbot auth status 2>&1) || true
+
+if echo "$AUTH_STATUS" | jq -e '.error' > /dev/null 2>&1; then
+  echo -e "${RED}Not authenticated!${NC}"
+  echo ""
+  echo "Run this to authenticate:"
+  echo "  agent-wechatbot auth set <app-id> <app-secret>"
+  exit 1
+fi
+
+APP_ID=$(echo "$AUTH_STATUS" | jq -r '.app_id // "Unknown"')
+echo -e "${GREEN}✓ Authenticated (App ID: $APP_ID)${NC}"
+echo ""
+
+# Send the message
+echo "Sending message to $OPENID..."
+echo "Message: $MESSAGE"
+echo ""
+
+send_message "$OPENID" "$MESSAGE"

package/skills/agent-wechatbot/templates/send-template.sh

@@ -0,0 +1,152 @@
+#!/bin/bash
+#
+# send-template.sh - Send a WeChat template message via Official Account API
+#
+# Usage:
+#   ./send-template.sh <openid> <template-id> --data <json> [--url <url>]
+#
+# Arguments:
+#   openid       - Recipient follower OpenID (e.g. oABCD1234)
+#   template-id  - Pre-approved template ID (e.g. TM00001)
+#
+# Options:
+#   --data <json>  - Required. JSON object with template parameters.
+#                    Format: {"<param>":{"value":"<text>","color":"<#hex>"}}
+#   --url <url>    - Optional. URL the message links to when tapped.
+#
+# Example:
+#   ./send-template.sh oABCD1234 TM00001 \
+#     --data '{"order_id":{"value":"ORD-9876"},"customer_name":{"value":"Alice"}}'
+#
+#   ./send-template.sh oABCD1234 TM00001 \
+#     --data '{"status":{"value":"shipped","color":"#00AA00"}}' \
+#     --url "https://example.com/orders/9876"
+
+set -euo pipefail
+
+if [ $# -lt 2 ]; then
+  echo "Usage: $0 <openid> <template-id> --data <json> [--url <url>]"
+  echo ""
+  echo "Examples:"
+  echo "  $0 oABCD1234 TM00001 --data '{\"order_id\":{\"value\":\"ORD-001\"}}'"
+  echo "  $0 oABCD1234 TM00001 --data '{...}' --url https://example.com/path"
+  exit 1
+fi
+
+OPENID="$1"
+TEMPLATE_ID="$2"
+shift 2
+
+DATA=""
+URL=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --data)
+      if [ $# -lt 2 ]; then
+        echo "Error: --data requires a JSON value"
+        exit 1
+      fi
+      DATA="$2"
+      shift 2
+      ;;
+    --url)
+      if [ $# -lt 2 ]; then
+        echo "Error: --url requires a value"
+        exit 1
+      fi
+      URL="$2"
+      shift 2
+      ;;
+    *)
+      echo "Unknown option: $1"
+      exit 1
+      ;;
+  esac
+done
+
+if [ -z "$DATA" ]; then
+  echo "Error: --data is required"
+  exit 1
+fi
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+# Check if agent-wechatbot is installed
+if ! command -v agent-wechatbot &> /dev/null; then
+  echo -e "${RED}Error: agent-wechatbot 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-wechatbot auth status 2>&1) || true
+
+if echo "$AUTH_STATUS" | jq -e '.error' > /dev/null 2>&1; then
+  echo -e "${RED}Not authenticated!${NC}"
+  echo ""
+  echo "Run this to authenticate:"
+  echo "  agent-wechatbot auth set <app-id> <app-secret>"
+  exit 1
+fi
+
+APP_ID=$(echo "$AUTH_STATUS" | jq -r '.app_id // "Unknown"')
+echo -e "${GREEN}✓ Authenticated (App ID: $APP_ID)${NC}"
+echo ""
+
+# Send template message with retry
+max_attempts=3
+attempt=1
+
+echo "Sending template '$TEMPLATE_ID' to $OPENID..."
+if [ -n "$URL" ]; then
+  echo "URL: $URL"
+fi
+echo ""
+
+while [ $attempt -le $max_attempts ]; do
+  echo -e "${YELLOW}Attempt $attempt/$max_attempts...${NC}"
+
+  if [ -n "$URL" ]; then
+    RESULT=$(agent-wechatbot template send "$OPENID" "$TEMPLATE_ID" --data "$DATA" --url "$URL" 2>&1) || true
+  else
+    RESULT=$(agent-wechatbot template send "$OPENID" "$TEMPLATE_ID" --data "$DATA" 2>&1) || true
+  fi
+
+  if ! echo "$RESULT" | jq -e '.error' > /dev/null 2>&1; then
+    echo -e "${GREEN}✓ Template message sent successfully!${NC}"
+    echo ""
+    echo "Message details:"
+    echo "  To OpenID:  $OPENID"
+    echo "  Template:   $TEMPLATE_ID"
+    if [ -n "$URL" ]; then
+      echo "  URL:        $URL"
+    fi
+    exit 0
+  fi
+
+  ERROR_MSG=$(echo "$RESULT" | jq -r '.error // "Unknown error"')
+  echo -e "${RED}✗ Failed: $ERROR_MSG${NC}"
+
+  # Don't retry on permanent errors
+  if echo "$ERROR_MSG" | grep -qE "40164|IP whitelist|40125|Invalid App"; then
+    exit 1
+  fi
+
+  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}"
+exit 1

package/skills/agent-whatsapp/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-whatsapp
 description: Interact with WhatsApp - send messages, read chats, manage conversations
-version: 2.10.1
+version: 2.11.0
 allowed-tools: Bash(agent-whatsapp:*)
 metadata:
   openclaw:

package/skills/agent-whatsappbot/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agent-whatsappbot
 description: Interact with WhatsApp using Cloud API credentials - send messages, manage templates
-version: 2.10.1
+version: 2.11.0
 allowed-tools: Bash(agent-whatsappbot:*)
 metadata:
   openclaw:
@@ -245,6 +245,8 @@ agent-whatsappbot template list --pretty
 
 ## Common Patterns
 
+See `references/common-patterns.md` for additional workflows.
+
 ### 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:
@@ -286,6 +288,14 @@ agent-whatsappbot message send-template 15559876543 deployment_alert \
   --components '[{"type":"body","parameters":[{"type":"text","text":"v2.1.0"},{"type":"text","text":"production"},{"type":"text","text":"success"}]}]'
 ```
 
+## Templates
+
+See `templates/` directory for runnable examples:
+
+- `post-message.sh` - Send messages with error handling and retries
+- `account-summary.sh` - Generate account and template summary
+- `send-template.sh` - Send a template message with parameters
+
 ## Error Handling
 
 All commands return consistent error format:
@@ -318,6 +328,20 @@ Config format:
 }
 ```
 
+## Key Differences from agent-whatsapp
+
+| Feature           | agent-whatsapp                       | agent-whatsappbot                  |
+| ----------------- | ------------------------------------ | ---------------------------------- |
+| Auth type         | User account (Baileys, QR/pairing)   | Cloud API (Phone Number ID + Token) |
+| Token source      | Pairing flow with phone number       | Meta Business Manager              |
+| Read messages     | Yes                                  | No (webhook-only inbound)          |
+| Group chats       | Yes                                  | No                                 |
+| Template messages | No                                   | Yes (required outside 24h window)  |
+| Free-form text    | Anytime                              | Only within 24h customer window    |
+| Media uploads     | Direct (local files)                 | URL only                           |
+| Multi-account     | Multi-phone, single CLI session      | Multi-account by Phone Number ID   |
+| CI/CD friendly    | Requires phone, pairing flow         | Yes (just set token)               |
+
 ## Limitations
 
 - **Cannot list or read received messages** — WhatsApp Cloud API delivers inbound messages via webhooks only. This CLI is send-only.
@@ -378,3 +402,8 @@ WhatsApp enforces rate limits based on your business tier. The CLI automatically
 - 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
+
+## References
+
+- [Authentication Guide](references/authentication.md)
+- [Common Patterns](references/common-patterns.md)

package/src/platforms/channeltalk/client.test.ts

@@ -1,4 +1,4 @@
-import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
 
 import { ChannelClient } from './client'
 import { ChannelError } from './types'
@@ -51,7 +51,7 @@ describe('ChannelClient', () => {
   const getJsonBody = (callIndex = 0) =>
     JSON.parse(String(fetchCalls[callIndex]?.options?.body)) as Record<string, unknown>
 
-  test('login() requires account cookie', async () => {
+  it('login() requires account cookie', async () => {
     await expect(new ChannelClient().login({ accountCookie: '' })).rejects.toThrow(ChannelError)
     await expect(new ChannelClient().login({ accountCookie: '', sessionCookie: 'session-cookie' })).rejects.toThrow(
       ChannelError,
@@ -62,7 +62,7 @@ describe('ChannelClient', () => {
     expect(client2).toBeInstanceOf(ChannelClient)
   })
 
-  test('successful GET request returns unwrapped JSON', async () => {
+  it('successful GET request returns unwrapped JSON', async () => {
     mockResponse({
       account: {
         id: 'acc-1',
@@ -82,7 +82,7 @@ describe('ChannelClient', () => {
     expect(fetchCalls[0].url).toBe('https://desk-api.channel.io/desk/account')
   })
 
-  test('cookie auth headers are set on every request', async () => {
+  it('cookie auth headers are set on every request', async () => {
     mockResponse({
       account: {
         id: 'acc-1',
@@ -108,7 +108,7 @@ describe('ChannelClient', () => {
     }
   })
 
-  test('429 response triggers retry with Retry-After wait', async () => {
+  it('429 response triggers retry with Retry-After wait', async () => {
     mockResponse({ errors: [{ message: 'Rate limited' }] }, 429, { 'Retry-After': '0.05' })
     mockResponse({
       account: {
@@ -132,7 +132,7 @@ describe('ChannelClient', () => {
     expect(elapsed).toBeGreaterThanOrEqual(40)
   })
 
-  test('500 response triggers retry with exponential backoff for GET requests', async () => {
+  it('500 response triggers retry with exponential backoff for GET requests', async () => {
     mockResponse({ errors: [{ message: 'Server error' }] }, 500)
     mockResponse({ errors: [{ message: 'Server error' }] }, 500)
     mockResponse({
@@ -157,7 +157,7 @@ describe('ChannelClient', () => {
     expect(elapsed).toBeGreaterThanOrEqual(280)
   })
 
-  test('4xx non-429 throws immediately without retry', async () => {
+  it('4xx non-429 throws immediately without retry', async () => {
     mockResponse({ type: 'forbidden', errors: [{ message: 'Forbidden' }] }, 403)
 
     const client = await new ChannelClient().login({ accountCookie: 'account-cookie', sessionCookie: 'session-cookie' })
@@ -165,7 +165,7 @@ describe('ChannelClient', () => {
     expect(fetchCalls).toHaveLength(1)
   })
 
-  test('network error retries then throws ChannelError with code network_error', async () => {
+  it('network error retries then throws ChannelError with code network_error', async () => {
     ;(globalThis as Record<string, unknown>).fetch = async (
       url: string | URL | Request,
       options?: RequestInit,
@@ -186,7 +186,7 @@ describe('ChannelClient', () => {
     }
   })
 
-  test('204 response returns undefined', async () => {
+  it('204 response returns undefined', async () => {
     mockResponse(null, 204)
 
     const client = await new ChannelClient().login({ accountCookie: 'account-cookie', sessionCookie: 'session-cookie' })
@@ -197,7 +197,7 @@ describe('ChannelClient', () => {
     expect(result).toBeUndefined()
   })
 
-  test('wrapTextInBlocks returns a single text block and extractText joins block and plain text', () => {
+  it('wrapTextInBlocks returns a single text block and extractText joins block and plain text', () => {
     expect(ChannelClient.wrapTextInBlocks('Hello world')).toEqual([{ type: 'text', value: 'Hello world' }])
 
     expect(
@@ -212,7 +212,7 @@ describe('ChannelClient', () => {
     ).toBe('hello\nworld\nfallback')
   })
 
-  test('listChannels includes query params', async () => {
+  it('listChannels includes query params', async () => {
     mockResponse({ channels: [{ id: 'ch-1', name: 'Support' }] })
 
     const client = await new ChannelClient().login({ accountCookie: 'account-cookie', sessionCookie: 'session-cookie' })
@@ -222,7 +222,7 @@ describe('ChannelClient', () => {
     expect(fetchCalls[0].url).toBe('https://desk-api.channel.io/desk/channels?limit=500')
   })
 
-  test('getChannel uses the channel detail endpoint', async () => {
+  it('getChannel uses the channel detail endpoint', async () => {
     mockResponse({ channel: { id: 'ch-1', name: 'Support' } })
 
     const client = await new ChannelClient().login({ accountCookie: 'account-cookie', sessionCookie: 'session-cookie' })
@@ -231,7 +231,7 @@ describe('ChannelClient', () => {
     expect(fetchCalls[0].url).toBe('https://desk-api.channel.io/desk/channels/ch-1')
   })
 
-  test('listManagers uses the managers endpoint', async () => {
+  it('listManagers uses the managers endpoint', async () => {
     mockResponse({ managers: [{ id: 'mgr-1', channelId: 'ch-1', accountId: 'acc-1', name: 'Alex' }] })
 
     const client = await new ChannelClient().login({ accountCookie: 'account-cookie', sessionCookie: 'session-cookie' })
@@ -241,7 +241,7 @@ describe('ChannelClient', () => {
     expect(fetchCalls[0].url).toBe('https://desk-api.channel.io/desk/channels/ch-1/managers?limit=200')
   })
 
-  test('getManagerRole unwraps the role response', async () => {
+  it('getManagerRole unwraps the role response', async () => {
     mockResponse({ role: { permissions: ['read'] } })
 
     const client = await new ChannelClient().login({ accountCookie: 'account-cookie', sessionCookie: 'session-cookie' })
@@ -251,7 +251,7 @@ describe('ChannelClient', () => {
     expect(fetchCalls[0].url).toBe('https://desk-api.channel.io/desk/channels/ch-1/managers/me/role')
   })
 
-  test('group endpoints build the expected URLs', async () => {
+  it('group endpoints build the expected URLs', async () => {
     mockResponse({ groups: [{ id: 'grp-1', channelId: 'ch-1', name: 'ops' }] })
     mockResponse({ group: { id: 'grp-1', channelId: 'ch-1', name: 'ops' } })
     mockResponse({ messages: [{ id: 'msg-1' }] })
@@ -273,7 +273,7 @@ describe('ChannelClient', () => {
     expect(messagesUrl.searchParams.get('since')).toBe('cursor-1')
   })
 
-  test('sendGroupMessage includes requestId in the body', async () => {
+  it('sendGroupMessage includes requestId in the body', async () => {
     mockResponse({ message: { id: 'msg-1', requestId: 'req-123' } })
 
     const client = await new ChannelClient().login({ accountCookie: 'account-cookie', sessionCookie: 'session-cookie' })
@@ -285,7 +285,7 @@ describe('ChannelClient', () => {
     expect(getJsonBody()).toEqual({ blocks, requestId: 'req-123' })
   })
 
-  test('direct chat endpoints build the expected URLs', async () => {
+  it('direct chat endpoints build the expected URLs', async () => {
     mockResponse({ directChats: [{ id: 'dm-1', channelId: 'ch-1' }] })
     mockResponse({ messages: [{ id: 'msg-1' }] })
     mockResponse({ message: { id: 'msg-2', requestId: 'req-234' } })
@@ -305,7 +305,7 @@ describe('ChannelClient', () => {
     expect(getJsonBody(2)).toEqual({ blocks, requestId: 'req-234' })
   })
 
-  test('user chat endpoints build the expected URLs', async () => {
+  it('user chat endpoints build the expected URLs', async () => {
     mockResponse({ userChats: [{ id: 'uc-1', channelId: 'ch-1', state: 'opened' }] })
     mockResponse({ userChat: { id: 'uc-1', channelId: 'ch-1', state: 'opened' } })
     mockResponse({ messages: [{ id: 'msg-1' }] })
@@ -330,7 +330,7 @@ describe('ChannelClient', () => {
     expect(getJsonBody(3)).toEqual({ blocks, requestId: 'req-345' })
   })
 
-  test('listBots uses the bots endpoint', async () => {
+  it('listBots uses the bots endpoint', async () => {
     mockResponse({ bots: [{ id: 'bot-1', channelId: 'ch-1', name: 'DeskBot' }] })
 
     const client = await new ChannelClient().login({ accountCookie: 'account-cookie', sessionCookie: 'session-cookie' })
@@ -340,7 +340,7 @@ describe('ChannelClient', () => {
     expect(fetchCalls[0].url).toBe('https://desk-api.channel.io/desk/channels/ch-1/bots?limit=1000')
   })
 
-  test('5xx on POST does not retry', async () => {
+  it('5xx on POST does not retry', async () => {
     mockResponse({ type: 'server_error', errors: [{ message: 'Server error' }] }, 500)
 
     const client = await new ChannelClient().login({ accountCookie: 'account-cookie', sessionCookie: 'session-cookie' })
@@ -350,7 +350,7 @@ describe('ChannelClient', () => {
     expect(fetchCalls).toHaveLength(1)
   })
 
-  test('error responses use desk API error fields', async () => {
+  it('error responses use desk API error fields', async () => {
     mockResponse({ type: 'not_found', status: 404, errors: [{ message: 'Missing resource' }], language: 'en' }, 404)
 
     const client = await new ChannelClient().login({ accountCookie: 'account-cookie', sessionCookie: 'session-cookie' })
@@ -365,7 +365,7 @@ describe('ChannelClient', () => {
     }
   })
 
-  test('rate limit headers delay the next request when remaining is zero', async () => {
+  it('rate limit headers delay the next request when remaining is zero', async () => {
     mockResponse(
       {
         account: {
@@ -407,7 +407,7 @@ describe('ChannelClient', () => {
     expect(fetchCalls).toHaveLength(2)
   })
 
-  test('generated requests still include the cookie header on post endpoints', async () => {
+  it('generated requests still include the cookie header on post endpoints', async () => {
     mockResponse({ message: { id: 'msg-1' } })
 
     const client = await new ChannelClient().login({ accountCookie: 'account-cookie', sessionCookie: 'session-cookie' })
@@ -416,7 +416,7 @@ describe('ChannelClient', () => {
     expect(getHeaders().Cookie).toBe('x-account=account-cookie; ch-session-1=session-cookie')
   })
 
-  test('searchTeamChatMessages builds correct URL with query and limit', async () => {
+  it('searchTeamChatMessages builds correct URL with query and limit', async () => {
     const searchResponse = {
       hits: [
         {
@@ -443,7 +443,7 @@ describe('ChannelClient', () => {
     expect(result.hits).toHaveLength(1)
   })
 
-  test('searchUserChatMessages builds correct URL with query', async () => {
+  it('searchUserChatMessages builds correct URL with query', async () => {
     const searchResponse = {
       hits: [],
       bots: [],
@@ -461,7 +461,7 @@ describe('ChannelClient', () => {
     expect(result.hits).toHaveLength(0)
   })
 
-  test('searchTeamChatMessages works without limit parameter', async () => {
+  it('searchTeamChatMessages works without limit parameter', async () => {
     mockResponse({ hits: [], bots: [], sessions: [] })
 
     const client = await new ChannelClient().login({ accountCookie: 'account-cookie', sessionCookie: 'session-cookie' })