Complete Guide to OpenClaw WhatsApp Integration

Pairing codes expire after 1 hour , and pending requests are capped at 3 per channel.

Allowlist Mode

Only phone numbers listed in channels.whatsapp.allowFrom can initiate chats.

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

Open Mode

Requires channels.whatsapp.allowFrom to include "*" .

Note: Your linked WhatsApp number is implicitly trusted — self messages skip dmPolicy and allowFrom checks.

Read Receipts

By default, the gateway marks inbound WhatsApp messages as read (blue ticks) once accepted.

Disable globally:

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

Disable per account:

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

Self-chat mode always skips read receipts.

Group Chat Support

Groups map to dedicated sessions. Configure group behavior with:

• Group policy: channels.whatsapp.groupPolicy — open , disabled , or allowlist (default: allowlist )
• Activation modes:
  • mention (default): requires @mention or regex match
  • always : always triggers a response

Toggle activation with an owner-only command (must be a standalone message):

/activation mention
/activation always

Owner is determined by channels.whatsapp.allowFrom (or your self E.164 if unset).

Group History Context

Recent unprocessed messages (default 50) are automatically injected as context:

[Chat messages since your last reply - for context]
...
[Current message - respond to this]

Each message includes a sender suffix: [from: Name (+E164)] .

Group metadata (subject + participants) is cached for 5 minutes.

Acknowledgment Reactions

WhatsApp can automatically send emoji reactions to incoming messages upon receipt, providing instant feedback before the bot generates a reply.

{
  "whatsapp": {
    "ackReaction": {
      "emoji": "👀",
      "direct": true,
      "group": "mentions"
    }
  }
}

Options:

• emoji : Emoji to react with (e.g., "👀", "✅"). Empty or omitted disables the feature.
• direct (default: true ): Send reactions in DM chats.
• group (default: "mentions" ):
  • "always" : React to all group messages
  • "mentions" : React only when bot is @mentioned
  • "never" : Never react in groups

Per-account override:

{
  "whatsapp": {
    "accounts": {
      "work": {
        "ackReaction": {
          "emoji": "✅",
          "direct": false,
          "group": "always"
        }
      }
    }
  }
}

Reactions are sent immediately upon receipt, before typing indicators or bot replies. Failures are logged but don't prevent the bot from replying.

Message Handling

Inbound Messages

• Messages arrive via Baileys messages.upsert events
• Status/broadcast chats are ignored
• Direct chats use E.164 format; groups use group JID
• Quoted reply context is always appended to provide conversation context
• Media-only messages use placeholders: <media:image|video|audio|document|sticker>

Outbound Messages

• Text is chunked to 4,000 characters by default (configurable via channels.whatsapp.textChunkLimit )
• Optional newline chunking: set channels.whatsapp.chunkMode="newline" to split on paragraph boundaries before length chunking
• Supported media types: image, video, audio, document
• Audio is sent as voice notes (PTT). Best results with OGG/Opus format
• Caption only on first media item
• Animated GIFs: WhatsApp expects MP4 with gifPlayback: true for inline looping

Media Limits

• Inbound media save cap: 50 MB (configurable via channels.whatsapp.mediaMaxMb )
• Outbound media cap: 5 MB per item (configurable via agents.defaults.mediaMaxMb )
• Images are auto-optimized to JPEG when under cap (resize + quality sweep)
• Oversize media results in an error; media reply falls back to text warning

Credentials & Storage

• Credentials stored at: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
• Automatic backup at creds.json.bak (restored on corruption)
• Logout: openclaw channels logout (or --account <id> ) deletes WhatsApp auth state but keeps shared oauth.json

Multi-Account Support

Multiple WhatsApp accounts can run in a single Gateway process. Use account identifiers in the configuration:

{
  channels: {
    whatsapp: {
      accounts: {
        personal: { /* per-account settings */ },
        work: { /* per-account settings */ },
      },
    },
  },
}

Per-account settings support overrides for sendReadReceipts , ackReaction , mediaMaxMb , historyLimit , and more.

Why Not Twilio / WhatsApp Business API?

Early OpenClaw builds supported Twilio's WhatsApp Business integration, but it was removed because:

• WhatsApp Business numbers are a poor fit for a personal assistant
• Meta enforces a 24-hour reply window — if you haven't responded in the last 24 hours, the business number can't initiate new messages
• High-volume or "chatty" usage triggers aggressive blocking, because business accounts aren't designed for personal assistant-style messaging
• Result: unreliable delivery and frequent blocks

Config Quick Reference

| Config Key | Description | |---|---| | channels.whatsapp.dmPolicy | DM policy: pairing / allowlist / open / disabled | | channels.whatsapp.selfChatMode | Enable for personal number setup | | channels.whatsapp.allowFrom | DM allowlist (E.164 phone numbers) | | channels.whatsapp.sendReadReceipts | Auto read receipts (default: true) | | channels.whatsapp.ackReaction | Auto-reaction on message receipt | | channels.whatsapp.groupPolicy | Group policy: open / disabled / allowlist | | channels.whatsapp.textChunkLimit | Outbound text chunk size (default: 4000) | | channels.whatsapp.mediaMaxMb | Inbound media cap (default: 50 MB) | | channels.whatsapp.configWrites | Allow config writes via /config command | | agents.defaults.mediaMaxMb | Outbound media cap (default: 5 MB) |

Troubleshooting

Not Linked / QR Login Required

Symptom: channels status shows linked: false or warns "Not linked".

Fix: Run openclaw channels login on the gateway host and scan the QR code (WhatsApp > Settings > Linked Devices).

Linked but Disconnected / Reconnect Loop

Symptom: channels status shows running, disconnected or warns "Linked but disconnected".

Fix: Run openclaw doctor or restart the gateway. If it persists, relink via openclaw channels login and inspect openclaw logs --follow .

Bun Runtime Issues

Bun is not recommended . WhatsApp (Baileys) and Telegram are unreliable on Bun. Run the gateway with Node.js .

Reconnect Behavior

The gateway uses a backoff policy ( web.reconnect ) with configurable initialMs , maxMs , factor , jitter , and maxAttempts . If max attempts are reached, web monitoring stops (degraded mode). A logged-out socket stops and requires re-linking.

Next Steps

• Telegram integration guide
• Discord integration guide
• Official WhatsApp documentation