Skip to content
Lobster

WhatsApp Channel

WhatsApp Channel Setup

Monitor WhatsApp groups via your OpenClaw agent to provide daily summaries, react to messages, and flag urgent items.

How It Works

Your personal WhatsApp is linked as a device to the agent Mac via the OpenClaw WhatsApp plugin (Baileys/WhatsApp Web). Everything the agent does on WhatsApp appears as you.

Flow:

  1. Messages flow into the group
  2. OpenClaw captures them as group history (requireMention mode — no auto-responses)
  3. Every heartbeat cycle (~1h), the agent reviews accumulated WhatsApp history
  4. The agent occasionally reacts to a message with an emoji
  5. If something urgent is detected -> immediate ping to owner via iMessage
  6. Once daily (evening) -> agent sends a summary of the day’s chat via iMessage

Setup Steps

1. Enable WhatsApp Plugin

The WhatsApp plugin ships with OpenClaw but is disabled by default:

Terminal window
openclaw plugins enable whatsapp
Terminal window
openclaw channels login

Scan the QR code using WhatsApp -> Settings -> Linked Devices on your phone. This links the agent Mac as a WhatsApp Web device.

3. Gateway Config

Add to ~/.openclaw/openclaw.json under channels:

"whatsapp": {
  "dmPolicy": "disabled",
  "selfChatMode": true,
  "groupPolicy": "allowlist",
  "groupAllowFrom": [],
  "groups": {
    "*": {
      "requireMention": true
    }
  },
  "sendReadReceipts": true
}

Key settings:

  • dmPolicy: “disabled” — no WhatsApp DMs, only group monitoring
  • selfChatMode: true — this is your own phone number
  • groupPolicy: “allowlist” — only accept messages from explicitly allowed groups (prevents prompt injection escalation via elevated tools)
  • requireMention: true — agent only responds when @mentioned, but captures all messages as history
  • sendReadReceipts: true — mark messages as read

4. Agent Binding

Route WhatsApp group messages to the main agent:

{
  "agentId": "main-agent",
  "match": {
    "channel": "whatsapp",
    "peer": {
      "kind": "group",
      "id": "*"
    }
  }
}

For specific groups, use the group JID:

{
  "agentId": "main-agent",
  "match": {
    "channel": "whatsapp",
    "peer": {
      "kind": "group",
      "id": "[email protected]"
    }
  }
}

5. Agent Config Updates

HEARTBEAT.md — Add WhatsApp monitoring tasks:

  • Group check (2-3x/day): review group history, react to 1-2 messages
  • Daily summary (1x/day, evening): send summary to owner via iMessage
  • Urgent items: immediate iMessage ping for health/safety/time-sensitive items

AGENTS.md — Add group chat guidelines:

  • Listen-mostly role
  • React naturally with heartfelt emoji
  • Never respond unless @mentioned
  • Route all summaries/pings via iMessage, not WhatsApp

Reactions

WhatsApp reactions are supported via the gateway’s react action. During heartbeat, the agent can:

  1. Fetch group history to see messages with IDs
  2. Call the react action with chatJid, messageId, and emoji
  3. Reactions appear in WhatsApp as you

Preferred emoji palette: ❤️, 😂, 👍, 🙌, 🥰

Reactions are delayed by up to the heartbeat interval (~1h), which actually feels natural — like you checked your phone later and hearted something.

Identity Rules

With selfChatMode: true, everything the agent does on WhatsApp appears as you:

  • NEVER use the agent’s emoji prefix or branding
  • NEVER sign messages or hint that an AI is writing
  • Send EXACTLY what the owner approves — no paraphrasing

Gap Recovery with wacli

OpenClaw’s Baileys connection occasionally times out (408 errors), missing messages. wacli provides a separate WhatsApp device link for gap recovery.

Installation

Terminal window
brew install steipete/tap/wacli

Usage

Terminal window
# Fetch group history
wacli messages list --chat "[email protected]" --limit N


# Search all messages
wacli messages search "query"


# Continuous sync (run in background)
wacli sync --follow


# Check auth status
wacli auth status

Important: Store locks if multiple wacli processes run simultaneously. Don’t run wacli sync while manually querying.

Notes

  • WhatsApp does not support the read message action — sendReadReceipts may behave differently than BlueBubbles
  • WhatsApp does not support the resolve command — group JIDs can’t be looked up by name
  • selfChatMode means messages the owner sends won’t appear as inbound — only messages from other group members trigger events
  • WhatsApp group messages route to their own session — use sessions_history to check, not message poll