WhatsApp

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Install (on demand)

• Onboarding (openclaw onboard) and openclaw channels add --channel whatsapp prompt to install the WhatsApp plugin the first time you select it.
• openclaw channels login --channel whatsapp also offers the install flow when the plugin is not present yet.
• Dev channel + git checkout: defaults to the local plugin path.
• Stable/Beta: defaults to the npm package @openclaw/whatsapp.

openclaw plugins install @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

• 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.
• Baileys socket timings are explicit under web.whatsapp.*: keepAliveIntervalMs controls WhatsApp Web application pings, connectTimeoutMs controls the opening handshake timeout, and defaultQueryTimeoutMs controls Baileys query timeouts.
• Outbound sends require an active WhatsApp listener for the target account.
• Status and broadcast chats are ignored (@status, @broadcast).
• Direct chats use DM session rules (session.dmScope; default main collapses DMs to the agent main session).
• Group sessions are isolated (agent:<agentId>:whatsapp:group:<jid>).
• 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 channel-specific WhatsApp proxy settings.
• When messages.removeAckAfterReply is enabled, OpenClaw clears the WhatsApp ack reaction after a visible reply is delivered.

​

Plugin hooks and privacy

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

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

​

Access control and activation

​

Personal-number and self-chat behavior

• skip read receipts for self-chat turns
• ignore mention-JID auto-trigger behavior that would otherwise ping yourself
• if messages.responsePrefix is unset, self-chat replies default to [{identity.name}] or [openclaw]

​

Message normalization and context

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

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

{
  channels: {
    whatsapp: {
      accounts: {
        work: {
          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
      },
    },
  },
}

• sent immediately after inbound is accepted (pre-reply)
• failures are logged but do not block normal reply delivery
• group mode mentions reacts on mention-triggered turns; group activation always acts as bypass for this check
• WhatsApp uses channels.whatsapp.ackReaction (legacy messages.ackReaction is not used here)

​

Multi-account and credentials

​

Tools, actions, and config writes

• Agent tool support includes WhatsApp reaction action (react).
• Action gates:
  • channels.whatsapp.actions.reactions
  • channels.whatsapp.actions.polls
• 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 doctor
openclaw logs --follow

​

System prompts

1. Group-specific system prompt (groups["<groupId>"].systemPrompt): used when the specific group entry exists in the map and its systemPrompt key is defined. If systemPrompt is an empty string (""), the wildcard is suppressed and no system prompt is applied.
2. Group wildcard system prompt (groups["*"].systemPrompt): used when the specific group entry is absent from the map entirely, or when it exists but defines no systemPrompt key.

1. Direct-specific system prompt (direct["<peerId>"].systemPrompt): used when the specific peer entry exists in the map and its systemPrompt key is defined. If systemPrompt is an empty string (""), the wildcard is suppressed and no system prompt is applied.
2. Direct wildcard system prompt (direct["*"].systemPrompt): used when the specific peer entry is absent from the map entirely, or when it exists but defines no systemPrompt key.

• channels.whatsapp.groups is both a per-group config map and the chat-level group allowlist. At either the root or account scope, groups["*"] means “all groups are admitted” for that scope.
• Only add a wildcard group 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 groups["*"] for the prompt default. Instead, repeat the prompt on each explicitly allowlisted group entry.
• Group admission and sender authorization are separate checks. 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 channels.whatsapp.groupPolicy and channels.whatsapp.groupAllowFrom.
• channels.whatsapp.direct does not have the same side effect for DMs. direct["*"] only provides a default direct-chat 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

• Configuration reference - WhatsApp

• access: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
• delivery: textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction, reactionLevel
• multi-account: accounts.<id>.enabled, accounts.<id>.authDir, account-level overrides
• operations: configWrites, debounceMs, web.enabled, web.heartbeatSeconds, web.reconnect.*, web.whatsapp.*
• session behavior: session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit
• prompts: groups.<id>.systemPrompt, groups["*"].systemPrompt, direct.<id>.systemPrompt, direct["*"].systemPrompt

​

Related

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