WhatsApp

​

Install

openclaw plugins install clawhub:@openclaw/whatsapp

​

Quick setup

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      allowFrom: ["+15551234567"],
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
}

openclaw channels login --channel whatsapp

openclaw channels login --channel whatsapp --account work

openclaw channels add --channel whatsapp --account work --auth-dir /path/to/wa-auth
openclaw channels login --channel whatsapp --account work

openclaw gateway

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

​

Deployment patterns

{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567"],
    },
  },
}

​

Runtime model

• The gateway owns the WhatsApp socket and reconnect loop.
• A watchdog tracks two signals independently: raw WhatsApp Web transport activity and application-message activity. A quiet-but-connected session is not restarted just because no message arrived recently; it forces reconnect only when transport frames stop arriving for a fixed internal window (not user-configurable) or application messages stay silent past 4x the normal message timeout. Right after a reconnect for a recently active session, that first window uses the shorter normal message timeout instead of the 4x window. OpenClaw can auto-reply to offline messages that Baileys delivers early in that reconnect, bounded by the inbound message-ID dedupe lifetime; initial startup keeps the short stale-history guard.
• Baileys socket timings are explicit under web.whatsapp.*: keepAliveIntervalMs (application ping interval), connectTimeoutMs (opening handshake timeout), defaultQueryTimeoutMs (Baileys query waits, plus OpenClaw’s outbound send/presence and inbound read-receipt timeouts).
• Outbound sends require an active WhatsApp listener for the target account; sends fail fast otherwise.
• Group sends attach native mention metadata for @+<digits> and @<digits> tokens (in text and media captions) when the token matches current participant metadata, including LID-backed groups.
• Status and broadcast chats (@status, @broadcast) are ignored.
• Direct chats use DM session rules (session.dmScope; default main collapses DMs into the agent main session). Group sessions are isolated per JID (agent:<agentId>:whatsapp:group:<jid>).
• WhatsApp Channels/Newsletters can be explicit outbound targets via their native @newsletter JID, using channel session metadata (agent:<agentId>:whatsapp:channel:<jid>) rather than DM semantics.
• WhatsApp Web transport honors standard proxy environment variables on the gateway host (HTTPS_PROXY, HTTP_PROXY, NO_PROXY, lowercase variants). Prefer host-level proxy config over per-channel settings.
• With messages.removeAckAfterReply enabled, OpenClaw clears the ack reaction once a visible reply is delivered.

​

Call the current requester with MeowCaller (experimental)

{
  "channels": {
    "whatsapp": {
      "actions": {
        "calls": true
      }
    }
  }
}

git clone --branch feat/send-only-notify https://github.com/steipete/meowcaller.git
cd meowcaller
git checkout 752050471fc2bf7a8cdfbf7dbd3cd4e865d85d3f
mkdir -p "$HOME/.local/bin"
go build -o "$HOME/.local/bin/meowcaller" ./cmd/meowcaller

state_dir="$HOME/.openclaw/credentials/whatsapp-calls/default"
mkdir -p "$state_dir"
chmod 700 "$state_dir"
meowcaller pair --store "$state_dir/wa-voip.db"

​

Approval prompts

{
  approvals: {
    exec: {
      enabled: true,
      mode: "session",
    },
    plugin: {
      enabled: true,
      mode: "targets",
      targets: [{ channel: "whatsapp", to: "+15551234567" }],
    },
  },
}

​

Plugin hooks and privacy

{
  channels: {
    whatsapp: {
      pluginHooks: {
        messageReceived: true,
      },
    },
  },
}

​

Access control and activation

​

Configured ACP bindings

{
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "whatsapp",
        accountId: "work",
        peer: { kind: "direct", id: "+15555550123" },
      },
    },
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "whatsapp",
        accountId: "work",
        peer: { kind: "group", id: "120363424282127706@g.us" },
      },
    },
  ],
}

​

Personal-number and self-chat behavior

​

Message normalization and context

[Replying to <sender> id:<stanzaId>]
<quoted body or media placeholder>
[/Replying]

{ channels: { whatsapp: { sendReadReceipts: false } } }

​

Delivery, chunking, and media

​

Reply quoting

{ channels: { whatsapp: { replyToMode: "first" } } }

​

Reaction level

{ channels: { whatsapp: { reactionLevel: "ack" } } }

​

Acknowledgment reactions

{
  channels: {
    whatsapp: {
      ackReaction: {
        emoji: "👀",
        direct: true,
        group: "mentions", // always | mentions | never
      },
    },
  },
}

​

Lifecycle status reactions

{
  messages: {
    statusReactions: {
      enabled: true,
      emojis: {
        deploy: "🛫",
        build: "🏗️",
        concierge: "💁",
      },
    },
  },
}

​

Multi-account and credentials

​

Tools, actions, and config writes

• Agent tool support includes the WhatsApp reaction action (react).
• Action gates: channels.whatsapp.actions.reactions, channels.whatsapp.actions.polls (existing actions default to true), channels.whatsapp.actions.calls (default false, see MeowCaller above).
• Channel-initiated config writes are enabled by default; disable via channels.whatsapp.configWrites: false.

​

Troubleshooting

openclaw channels login --channel whatsapp
openclaw channels status

{
  web: {
    whatsapp: {
      keepAliveIntervalMs: 15000,
      connectTimeoutMs: 60000,
      defaultQueryTimeoutMs: 60000,
    },
  },
}

openclaw channels status --probe
openclaw doctor
openclaw logs --follow
openclaw gateway status

cp -a ~/.openclaw/credentials/whatsapp/<accountId> \
  ~/.openclaw/credentials/whatsapp/<accountId>.bak
openclaw channels logout --channel whatsapp --account <accountId>
openclaw channels login --channel whatsapp --account <accountId>

​

System prompts

1. Group-specific prompt (groups["<groupId>"].systemPrompt): used when the group entry exists and its systemPrompt key is defined. An empty string ("") suppresses the wildcard and applies no prompt.
2. Group wildcard prompt (groups["*"].systemPrompt): used when the specific group entry is absent, or exists without a systemPrompt key.

• channels.whatsapp.groups is both a per-group config map and the chat-level group allowlist. At either root or account scope, groups["*"] means “all groups are admitted” for that scope.
• Only add a wildcard systemPrompt when you already want that scope to admit all groups. To keep only a fixed set of group IDs eligible, repeat the prompt on each explicitly allowlisted entry instead of using groups["*"].
• Group admission and sender authorization are separate checks. groups["*"] widens which groups reach group handling; it does not authorize every sender in those groups — that stays controlled by groupPolicy/groupAllowFrom.
• channels.whatsapp.direct has no equivalent side effect for DMs: direct["*"] only supplies a default config after a DM is already admitted by dmPolicy plus allowFrom or pairing-store rules.

{
  channels: {
    whatsapp: {
      groups: {
        // Use only if all groups should be admitted at the root scope.
        // Applies to all accounts that do not define their own groups map.
        "*": { systemPrompt: "Default prompt for all groups." },
      },
      direct: {
        // Applies to all accounts that do not define their own direct map.
        "*": { systemPrompt: "Default prompt for all direct chats." },
      },
      accounts: {
        work: {
          groups: {
            // This account defines its own groups, so root groups are fully
            // replaced. To keep a wildcard, define "*" explicitly here too.
            "120363406415684625@g.us": {
              requireMention: false,
              systemPrompt: "Focus on project management.",
            },
            // Use only if all groups should be admitted in this account.
            "*": { systemPrompt: "Default prompt for work groups." },
          },
          direct: {
            // This account defines its own direct map, so root direct entries are
            // fully replaced. To keep a wildcard, define "*" explicitly here too.
            "+15551234567": { systemPrompt: "Prompt for a specific work direct chat." },
            "*": { systemPrompt: "Default prompt for work direct chats." },
          },
        },
      },
    },
  },
}

​

Configuration reference pointers

​

Related

• Pairing
• Groups
• Security
• Channel routing
• Multi-agent routing
• Troubleshooting