WhatsApp

WhatsApp integration uses Baileys, an unofficial WhatsApp Web API library. It works by emulating a web session — the same way WhatsApp Web works in your browser. This means it's more fragile than official integrations and will occasionally require re-authentication.

If stability is a priority, use Telegram or iMessage instead. If WhatsApp is where you actually communicate, here's how to set it up. WhatsApp works on any supported OpenClaw host (Mac, Linux, Windows, or a VPS) and adds no cost on top of your normal AI API spend — typically $1–10/month.

mkdir -p ~/.openclaw/sessions/whatsapp

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "library": "baileys",
      "dmPolicy": "allowlist",
      "allowedContacts": [
        "+15551234567"
      ],
      "groupPolicy": "mention",
      "requireMention": true,
      "sessionPath": "~/.openclaw/sessions/whatsapp"
    }
  }
}

openclaw gateway restart
openclaw logs --filter whatsapp

openclaw logs --filter whatsapp

Phone Number Formatting

Same rule as iMessage: use E.164 format with no spaces.

Formatting errors are the leading cause of allowlist failures.

Key Configuration Options

Group Chats

Group echo suppression is now smarter: OpenClaw tracks recent gateway-sent message IDs and only suppresses matching echoes. Owner commands like /status, /new, and /activation from linked-account traffic are preserved and no longer incorrectly filtered.

Reply-to-bot detection in groups also works reliably with linked accounts. OpenClaw unwraps botInvokeMessage payloads and reads selfLid from creds.json, so reply-based mentions reach the bot in linked-account group chats.

Message Reactions

As of v2026.4.12, message reactions are now properly routed through the gateway-owned action path. This means:

• Reactions work in both direct messages and group chats
• The live WhatsApp listener is used in both contexts
• Reaction handling matches the reliability of standard message sending (message send)
• Reply-based polling and sentiment reactions work consistently

The gateway now routes message react through the same reliable path as message send and message poll, ensuring reactions stay synchronized with your live WhatsApp session.

CLI Media Sends (v2026.4.12)

Sending files via the CLI with --media is now fixed. Gateway-mode outbound sends route through the correct channel sendMedia path and preserve media access context — previously, WhatsApp document and attachment sends would silently drop the file while still delivering the caption.

openclaw send --channel whatsapp --to "+15551234567" --media /path/to/file.pdf "Here's the doc"

Auto-Reply and Media Attachments (v2026.4.12)

Image attachment notes are now preserved after media understanding, so image edits keep the real saved media path instead of hallucinating a missing local path. This means:

• Your agent can understand image content in auto-reply rules
• Edits and modifications to images maintain proper file references
• Media understanding doesn't break downstream file operations

Reconnection Stability

As of v2026.4.12, WhatsApp reconnection has been significantly improved:

• The blockStreaming setting has been restored and controls streaming behavior
• Watchdog timeouts are now reset after reconnect, so quiet chats no longer fall into reconnect loops
• Per-account connection ownership is centralized, so reconnects and login recovery stay attached to the live socket
• Disconnection and reconnection are more graceful overall

Enable streaming control if needed:

{
  "channels": {
    "whatsapp": {
      "blockStreaming": false
    }
  }
}

Large Media Sends (v2026.4.15)

Packaged QuickStart Setup (v2026.4.23)

Prompt-Injection Hardening (v2026.4.23)

Related channels

Want an official API instead of an unofficial one? Telegram uses Telegram's official Bot API — no QR codes, no session expiry, more reliable.

Privacy-critical communications? Signal keeps messages end-to-end encrypted with no unofficial protocol emulation.

Comparing OpenClaw to alternatives? See OpenClaw vs ChatGPT — WhatsApp integration is a key reason users choose OpenClaw over hosted AI services.

Important Limitations

Unofficial API. WhatsApp doesn't provide an official API for this type of integration. Baileys reverse-engineers the web protocol, which means:

• WhatsApp updates can break the integration until Baileys updates
• Occasional disconnections are normal
• Your account could theoretically be flagged (rare, but possible)

Session file security. The session files in sessionPath contain authentication credentials equivalent to being logged into WhatsApp. Never commit them to version control, never back them up to unencrypted cloud storage.

Multi-device limits. WhatsApp limits linked devices. If you hit the limit, you'll need to unlink another device before the integration works.

Phone offline. Extended periods with your phone offline can cause the session to invalidate, requiring re-authentication.

Re-Authentication

openclaw channels login --channel whatsapp

When the session expires, delete the session files and repeat the QR code scan:

rm -rf ~/.openclaw/sessions/whatsapp/*
openclaw gateway restart
# Watch logs for QR code
openclaw logs --filter whatsapp