Deployment patterns

Runtime model

• Gateway owns the WhatsApp socket and reconnect loop.
• The reconnect watchdog uses WhatsApp Web transport activity, not only inbound app-message volume, so a quiet linked-device session is not restarted solely because nobody has sent a message recently. A longer application-silence cap still forces a reconnect if transport frames keep arriving but no application messages are handled for the watchdog window; after a transient reconnect for a recently active session, that application-silence check uses the normal message timeout for the first recovery window.
• Baileys socket timings are explicit under
  text

  Copy

  web.whatsapp.*
  :
  text

  Copy

  keepAliveIntervalMs
  controls WhatsApp Web application pings,
  text

  Copy

  connectTimeoutMs
  controls the opening handshake timeout, and
  text

  Copy

  defaultQueryTimeoutMs
  controls Baileys query timeouts.
• Outbound sends require an active WhatsApp listener for the target account.
• Status and broadcast chats are ignored (
  text

  Copy

  @status
  ,
  text

  Copy

  @broadcast
  ).
• The reconnect watchdog follows WhatsApp Web transport activity, not only inbound app-message volume: quiet linked-device sessions stay up while transport frames continue, but a transport stall forces reconnect well before the later remote disconnect path.
• Direct chats use DM session rules (
  text

  Copy

  session.dmScope
  ; default
  text

  Copy

  main
  collapses DMs to the agent main session).
• Group sessions are isolated (
  text

  Copy

  agent:<agentId>:whatsapp:group:<jid>
  ).
• WhatsApp Web transport honors standard proxy environment variables on the gateway host (
  text

  Copy

  HTTPS_PROXY
  ,
  text

  Copy

  HTTP_PROXY
  ,
  text

  Copy

  NO_PROXY
  / lowercase variants). Prefer host-level proxy config over channel-specific WhatsApp proxy settings.
• When
  text

  Copy

  messages.removeAckAfterReply
  is enabled, OpenClaw clears the WhatsApp ack reaction after a visible reply is delivered.

Plugin hooks and privacy

WhatsApp inbound messages can contain personal message content, phone numbers, group identifiers, sender names, and session correlation fields. For that reason, WhatsApp does not broadcast inbound

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

You can scope the opt-in to one account:

json5
Copy
{
  channels: {
    whatsapp: {
      accounts: {
        work: {
          pluginHooks: {
            messageReceived: true,
          },
        },
      },
    },
  },
}

Only enable this for plugins you trust to receive inbound WhatsApp message content and identifiers.

Access control and activation

text
Copy
* `pairing` (default)
* `allowlist`
* `open` (requires `allowFrom` to include `"*"`)
* `disabled`

`allowFrom` accepts E.164-style numbers (normalized internally).

Multi-account override: `channels.whatsapp.accounts.<id>.dmPolicy` (and `allowFrom`) take precedence over channel-level defaults for that account.

Runtime behavior details:

* pairings are persisted in channel allow-store and merged with configured `allowFrom`
* if no allowlist is configured, the linked self number is allowed by default
* OpenClaw never auto-pairs outbound `fromMe` DMs (messages you send to yourself from the linked device)

text
Copy
1. **Group membership allowlist** (`channels.whatsapp.groups`)
   * if `groups` is omitted, all groups are eligible
   * if `groups` is present, it acts as a group allowlist (`"*"` allowed)

2. **Group sender policy** (`channels.whatsapp.groupPolicy` + `groupAllowFrom`)
   * `open`: sender allowlist bypassed
   * `allowlist`: sender must match `groupAllowFrom` (or `*`)
   * `disabled`: block all group inbound

Sender allowlist fallback:

* if `groupAllowFrom` is unset, runtime falls back to `allowFrom` when available
* sender allowlists are evaluated before mention/reply activation

Note: if no `channels.whatsapp` block exists at all, runtime group-policy fallback is `allowlist` (with a warning log), even if `channels.defaults.groupPolicy` is set.

text
Copy
Mention detection includes:

* explicit WhatsApp mentions of the bot identity
* configured mention regex patterns (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`)
* inbound voice-note transcripts for authorized group messages
* implicit reply-to-bot detection (reply sender matches bot identity)

Security note:

* quote/reply only satisfies mention gating; it does **not** grant sender authorization
* with `groupPolicy: "allowlist"`, non-allowlisted senders are still blocked even if they reply to an allowlisted user's message

Session-level activation command:

* `/activation mention`
* `/activation always`

`activation` updates session state (not global config). It is owner-gated.

Personal-number and self-chat behavior

When the linked self number is also present in

• skip read receipts for self-chat turns
• ignore mention-JID auto-trigger behavior that would otherwise ping yourself
• if
  text

  Copy

  messages.responsePrefix
  is unset, self-chat replies default to
  text

  Copy

  [{identity.name}]
  or
  text

  Copy

  [openclaw]

Message normalization and context

Delivery, chunking, and media

Reply quoting

WhatsApp supports native reply quoting, where outbound replies visibly quote the inbound message. Control it with

Default is

json5
Copy
{
  channels: {
    whatsapp: {
      replyToMode: "first",
    },
  },
}

Reaction level

Default:

Per-account overrides use

json5
Copy
{
  channels: {
    whatsapp: {
      reactionLevel: "ack",
    },
  },
}

Acknowledgment reactions

WhatsApp supports immediate ack reactions on inbound receipt via

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

Behavior notes:

• sent immediately after inbound is accepted (pre-reply)
• failures are logged but do not block normal reply delivery
• group mode
  text

  Copy

  mentions
  reacts on mention-triggered turns; group activation
  text

  Copy

  always
  acts as bypass for this check
• WhatsApp uses
  text

  Copy

  channels.whatsapp.ackReaction
  (legacy
  text

  Copy

  messages.ackReaction
  is not used here)

Multi-account and credentials

Tools, actions, and config writes

• Agent tool support includes WhatsApp reaction action (
  text

  Copy

  react
  ).
• Action gates:
  • text

    Copy

    channels.whatsapp.actions.reactions
  • text

    Copy

    channels.whatsapp.actions.polls
• Channel-initiated config writes are enabled by default (disable via
  text

  Copy

  channels.whatsapp.configWrites=false
  ).

Troubleshooting

System prompts

WhatsApp supports Telegram-style system prompts for groups and direct chats via the

Resolution hierarchy for group messages:

The effective

1. Group-specific system prompt (
   text

   Copy

   groups["<groupId>"].systemPrompt
   ): used when the specific group entry exists in the map and its
   text

   Copy

   systemPrompt
   key is defined. If
   text

   Copy

   systemPrompt
   is an empty string (
   text

   Copy

   ""
   ), the wildcard is suppressed and no system prompt is applied.
2. Group wildcard system prompt (
   text

   Copy

   groups["*"].systemPrompt
   ): used when the specific group entry is absent from the map entirely, or when it exists but defines no
   text

   Copy

   systemPrompt
   key.

Resolution hierarchy for direct messages:

The effective

1. Direct-specific system prompt (
   text

   Copy

   direct["<peerId>"].systemPrompt
   ): used when the specific peer entry exists in the map and its
   text

   Copy

   systemPrompt
   key is defined. If
   text

   Copy

   systemPrompt
   is an empty string (
   text

   Copy

   ""
   ), the wildcard is suppressed and no system prompt is applied.
2. Direct wildcard system prompt (
   text

   Copy

   direct["*"].systemPrompt
   ): used when the specific peer entry is absent from the map entirely, or when it exists but defines no
   text

   Copy

   systemPrompt
   key.

Difference from Telegram multi-account behavior: In Telegram, root

Important behavior:

• text

  Copy

  channels.whatsapp.groups
  is both a per-group config map and the chat-level group allowlist. At either the root or account scope,
  text

  Copy

  groups["*"]
  means "all groups are admitted" for that scope.
• Only add a wildcard group
  text

  Copy

  systemPrompt
  when you already want that scope to admit all groups. If you still want only a fixed set of group IDs to be eligible, do not use
  text

  Copy

  groups["*"]
  for the prompt default. Instead, repeat the prompt on each explicitly allowlisted group entry.
• Group admission and sender authorization are separate checks.
  text

  Copy

  groups["*"]
  widens the set of groups that can reach group handling, but it does not by itself authorize every sender in those groups. Sender access is still controlled separately by
  text

  Copy

  channels.whatsapp.groupPolicy
  and
  text

  Copy

  channels.whatsapp.groupAllowFrom
  .
• text

  Copy

  channels.whatsapp.direct
  does not have the same side effect for DMs.
  text

  Copy

  direct["*"]
  only provides a default direct-chat config after a DM is already admitted by
  text

  Copy

  dmPolicy
  plus
  text

  Copy

  allowFrom
  or pairing-store rules.

Example:

json5
Copy
{
  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

Primary reference:

• Configuration reference - WhatsApp

High-signal WhatsApp fields:

• access:
  text

  Copy

  dmPolicy
  ,
  text

  Copy

  allowFrom
  ,
  text

  Copy

  groupPolicy
  ,
  text

  Copy

  groupAllowFrom
  ,
  text

  Copy

  groups
• delivery:
  text

  Copy

  textChunkLimit
  ,
  text

  Copy

  chunkMode
  ,
  text

  Copy

  mediaMaxMb
  ,
  text

  Copy

  sendReadReceipts
  ,
  text

  Copy

  ackReaction
  ,
  text

  Copy

  reactionLevel
• multi-account:
  text

  Copy

  accounts.<id>.enabled
  ,
  text

  Copy

  accounts.<id>.authDir
  , account-level overrides
• operations:
  text

  Copy

  configWrites
  ,
  text

  Copy

  debounceMs
  ,
  text

  Copy

  web.enabled
  ,
  text

  Copy

  web.heartbeatSeconds
  ,
  text

  Copy

  web.reconnect.*
  ,
  text

  Copy

  web.whatsapp.*
• session behavior:
  text

  Copy

  session.dmScope
  ,
  text

  Copy

  historyLimit
  ,
  text

  Copy

  dmHistoryLimit
  ,
  text

  Copy

  dms.<id>.historyLimit
• prompts:
  text

  Copy

  groups.<id>.systemPrompt
  ,
  text

  Copy

  groups["*"].systemPrompt
  ,
  text

  Copy

  direct.<id>.systemPrompt
  ,
  text

  Copy

  direct["*"].systemPrompt

Related

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