name: openclaw-wa-bridge description: "WhatsApp bridge for OpenClaw — send/receive messages, search chats, manage contacts via REST API + CLI. Incoming messages trigger OpenClaw webhooks for real-time agent responses. Use when the user wants to send WhatsApp messages, check WhatsApp chats, search message history, or manage WhatsApp monitoring." homepage: https://github.com/andrepaim/openclaw-wa-bridge metadata: { "openclaw": { "emoji": "📱", "requires": { "bins": ["node"] } } }

WhatsApp Bridge

Send and receive WhatsApp messages via a REST API service + CLI.

Architecture

• Service ({baseDir}/service/index.js): Express REST API + whatsapp-web.js client. Runs as a background service (systemd). Incoming messages trigger OpenClaw agent webhooks automatically.
• CLI (wa-cli): Talks to the running service over HTTP. Quick commands for sending, searching, listing chats.

Prerequisites

• Node.js 18+
• npm install in {baseDir}
• One-time QR scan: start the service, visit /qr endpoint, scan with WhatsApp
• Configure hook-rules.json from hook-rules.json.example

When to Use

✅ USE this skill when:

• "Send a WhatsApp message to [person]"
• "Check my WhatsApp messages"
• "Search WhatsApp for [query]"
• "Who messaged me on WhatsApp?"
• "List my WhatsApp groups"
• "Monitor WhatsApp contact [number]"

When NOT to Use

❌ DON'T use this skill when:

• User wants to use Telegram, Signal, or other messengers
• Real-time video/voice calls
• WhatsApp Business API features (catalogs, payments)

CLI Commands

The CLI connects to the running service. Set WA_BRIDGE_URL (default: http://127.0.0.1:3100) and optionally WA_BRIDGE_TOKEN.

# Connection
wa-cli status                              # Check connection status

# Messaging
wa-cli send <number> <message>             # Send to number (auto-appends @c.us)
wa-cli send-group <groupId> <message>      # Send to group

# Chats & Messages
wa-cli chats [--limit N]                   # List recent chats
wa-cli messages <chatId> [--limit N]       # Get messages from a chat
wa-cli search <query> [--chat id] [--limit N]  # Search messages

# Contacts & Groups
wa-cli contacts [--search query]           # List or search contacts
wa-cli groups [--search query]             # List or search groups

# Events (incoming message queue)
wa-cli events                              # Get and flush pending events
wa-cli events --peek                       # Peek without flushing

# Monitors
wa-cli monitor                             # List active monitors
wa-cli monitor add <contactId>             # Add monitor
wa-cli monitor remove <contactId>          # Remove monitor

REST API (for direct HTTP calls)

If the CLI isn't available, use curl:

BASE="http://127.0.0.1:3100"

# Send message
curl -s -X POST $BASE/send -H 'Content-Type: application/json' \
  -d '{"to":"5511999999999","message":"Hello!"}'

# Send to group
curl -s -X POST $BASE/send-group -H 'Content-Type: application/json' \
  -d '{"groupId":"[email protected]","message":"Hello group!"}'

# Get status
curl -s $BASE/status

# List chats
curl -s $BASE/chats

# Search messages
curl -s "$BASE/search?q=meeting&limit=10"

# Get events (flushes queue)
curl -s $BASE/events

# Peek events (no flush)
curl -s $BASE/events/peek

OpenClaw Integration

The service automatically sends webhooks to OpenClaw when messages arrive. Configure in hook-rules.json:

• hookUrl: OpenClaw agent hook endpoint (default: http://127.0.0.1:18789/hooks/agent)
• hookToken: Authentication token for the hook
• contacts.categories: Define who gets auto-replies vs notifications
• contacts.defaults: How to handle groups and unknown senders

Each incoming message creates an agent session with full context (sender info, routing rules, reply instructions).

Service Management

# Start directly
node {baseDir}/service/index.js

# Or via systemd (edit wa-bridge.service with your paths first)
sudo cp {baseDir}/service/wa-bridge.service /etc/systemd/system/
sudo systemctl enable wa-bridge
sudo systemctl start wa-bridge

Monitoring (Cron)

For periodic inbox checks (backup to real-time webhooks):

{
  "name": "WA Bridge Inbox Check",
  "schedule": { "kind": "every", "everyMs": 120000 },
  "payload": { "kind": "agentTurn", "message": "Check for new WhatsApp messages: wa-cli events. If empty, reply NO_REPLY. If messages exist, notify on Telegram with summary." },
  "sessionTarget": "isolated"
}

Error Handling

• Service not running → CLI returns connection error; start the service
• QR expired → Restart service, scan new QR at /qr
• 503 responses → WhatsApp client not ready; check /status
• Auth failure → Delete auth/ directory and re-scan QR