OpenClaw Manual OpenClaw

OpenClaw WhatsApp Channel

Messaging
Medium

Connect OpenClaw to WhatsApp using the Baileys protocol. This integration allows your AI assistant to send and receive messages on WhatsApp without requiring a business API — just scan a QR code with your phone and you're ready to go. A dedicated phone number is recommended for clean routing.

Quick Info
Difficulty Medium
Category Messaging
Features Supported 5 / 6

WhatsApp Supported Features

Text Messages

Supported

Media & Files

Supported

Reactions

Supported

Threads

Not Supported

Voice Messages

Supported

Group Chat

Supported

WhatsApp Prerequisites

  • A dedicated phone number for WhatsApp (recommended, separate from personal)
  • Node.js 18+ installed on your server (Bun is not recommended)
  • OpenClaw Gateway running and configured

WhatsApp Quick Setup

1

Add WhatsApp channel config

Add the WhatsApp channel configuration to ~/.openclaw/openclaw.json. Set the dmPolicy (allowlist, pairing, or open) and allowFrom list to control who can message your assistant.

2

Run login command and scan QR code

Run 'openclaw channels login' in your terminal. A QR code will appear. Scan it with WhatsApp on your phone (Settings > Linked Devices > Link a Device). Credentials are saved to ~/.openclaw/credentials/whatsapp/.

3

Send a test message

Send a direct message to your WhatsApp number from another phone. If using allowlist policy, make sure the sender's number is in the allowFrom list. If using the default pairing policy, approve the sender via 'openclaw pairing approve whatsapp <code>'.

WhatsApp Configuration Example

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

WhatsApp Deep Dive

Architecture Overview

OpenClaw connects to WhatsApp through the Baileys library — a reverse-engineered, open-source implementation of the WhatsApp Web multi-device protocol. Unlike the official WhatsApp Business API (which requires Meta approval and charges per conversation), Baileys connects directly by emulating a linked device. The architecture is straightforward: your phone stays the primary device, and the Gateway acts as a linked companion. Messages flow through WhatsApp's servers as usual — OpenClaw simply intercepts inbound messages, processes them with your AI, and sends responses back.
Because the connection is phone-based, your phone must remain online. If your phone is off for more than ~14 days, WhatsApp will unlink the session.
Baileys supports multi-device natively — you can have up to 4 linked devices per phone number, and the Gateway counts as one of them.

Phone Number Setup

A dedicated phone number is strongly recommended. While you can use your personal number, mixing personal and bot conversations creates routing confusion and may annoy your contacts. You need a real phone number that can receive SMS or voice calls for initial WhatsApp registration. Once registered, the number only needs to stay active on a phone with WhatsApp installed.
openclaw.json 
{
  "channels": {
    "whatsapp": {
      "accounts": {
        "default": {
          "phone": "+15551234567"
        }
      }
    }
  }
}
Avoid VoIP numbers (e.g., TextNow, Google Voice, free SMS services) — WhatsApp frequently bans VoIP-registered accounts. Use a real SIM card, prepaid SIM, or a dedicated eSIM for best reliability.

Login & Credentials

After configuring your channel, you need to pair your phone with the Gateway. Run the login command and a QR code will appear in your terminal. Scan it with WhatsApp on your phone (Settings → Linked Devices → Link a Device). Credentials are automatically saved to ~/.openclaw/credentials/whatsapp/<accountId>/creds.json and will persist across restarts. A backup (creds.json.bak) is automatically created for recovery in case of corruption. You only need to scan the QR code once unless the session expires or is manually revoked.
terminal 
openclaw channels login whatsapp
If you're running headless (no display), use the --qr-terminal flag to render the QR code as ASCII art directly in your terminal.

DM Policies

DM (Direct Message) policies control who can interact with your AI assistant. OpenClaw supports four policies: • pairing (default) — New contacts must go through a pairing flow. They send a message, receive a pairing code, and you approve or deny via the CLI. Once approved, they can chat freely. • allowlist — Only phone numbers explicitly listed in allowFrom can message the bot. Everyone else is silently ignored. • open — Anyone who messages the number gets a response. Use with caution in production. • disabled — DM handling is completely turned off. The bot will not respond to any direct messages.
openclaw.json 
{
  "channels": {
    "whatsapp": {
      "dmPolicy": "pairing",
      "allowFrom": ["+15551234567", "+15559876543"]
    }
  }
}

Group Chat Management

OpenClaw can participate in WhatsApp group chats. By default, group support is disabled to prevent unwanted AI responses in shared conversations. When enabled, the bot responds only when mentioned by name or triggered by a configured keyword. You can control which groups are active and how the bot is activated.
openclaw.json 
{
  "channels": {
    "whatsapp": {
      "groupPolicy": "allowlist",
      "groupActivation": "mention",
      "groupAllowList": ["group-jid-1", "group-jid-2"]
    }
  }
}
Group JIDs can be found in the Gateway logs when a group message is received. Look for the 'from' field in the message payload.

Read Receipts

You can configure whether OpenClaw sends read receipts (blue ticks) when it processes a message. By default, read receipts are sent to maintain a natural conversation feel. Disabling read receipts can be useful if you want the bot to appear less "active" or if you're processing messages asynchronously.
openclaw.json 
{
  "channels": {
    "whatsapp": {
      "sendReadReceipts": true
    }
  }
}

Acknowledgment Reactions

OpenClaw can react to incoming messages with an emoji to acknowledge receipt before the AI response is ready. This is useful because AI responses can take several seconds, and the reaction lets the sender know their message was received. You can configure different reactions for direct messages and group chats, or disable the feature entirely.
openclaw.json 
{
  "channels": {
    "whatsapp": {
      "ackReaction": {
        "emoji": "👀",
        "direct": true,
        "group": true
      }
    }
  }
}

Outbound Messaging & Media

OpenClaw supports sending text, images, documents, audio, and video through WhatsApp. Media files are automatically handled — the Gateway uploads them to WhatsApp's servers and sends the appropriate message type. For long AI responses, the text is automatically chunked to stay within WhatsApp's message size limits. You can configure the chunk size and behavior.
The default inbound media size limit is 50 MB (mediaMaxMb). The outbound media limit is 5 MB (agents.defaults.mediaMaxMb), with automatic JPEG optimization and resize for oversized images.

Rate Limits & Sending Limits

WhatsApp enforces rate limits on linked devices. While there are no official published limits for personal accounts, sending too many messages too quickly can trigger temporary bans or account restrictions. OpenClaw includes built-in rate limiting to protect your account. The default settings are conservative and suitable for most use cases.
openclaw.json 
{
  "channels": {
    "whatsapp": {
      "textChunkLimit": 5,
      "mediaMaxMb": 50
    }
  }
}

Why Not Twilio / WhatsApp Business API?

You might wonder why OpenClaw uses Baileys instead of the official WhatsApp Business API (via Twilio, MessageBird, etc.). Here's the reasoning: • Cost — The Business API charges per conversation (roughly $0.005–$0.08 per message depending on region). For personal or small-team use, this adds up quickly. Baileys is free. • Approval — The Business API requires Meta verification, a registered business, and approval for message templates. Baileys works with any personal WhatsApp account. • Flexibility — The Business API has strict template requirements for outbound messages and a 24-hour conversation window. Baileys has no such restrictions. • Self-hosted — With Baileys, everything runs on your server. No third-party API providers see your messages. The tradeoff is reliability: the Business API is officially supported, while Baileys relies on reverse engineering and could break if WhatsApp changes their protocol. For most self-hosted use cases, this tradeoff is worth it.

WhatsApp Configuration Reference

dmPolicy
Type: string Default: "pairing"

Controls who can DM the bot. Options: pairing, allowlist, open, disabled

selfChatMode
Type: string Default: "disabled"

How to handle messages you send to yourself. Options: disabled, ai, note

allowFrom
Type: string[] Default: []

Phone numbers allowed to message the bot (when dmPolicy is allowlist)

sendReadReceipts
Type: boolean Default: true

Whether to send blue-tick read receipts when processing messages

ackReaction.emoji
Type: string Default: "👀"

Emoji used to react to messages as acknowledgment

ackReaction.direct
Type: boolean Default: true

Send ack reaction in direct messages

ackReaction.group
Type: boolean Default: true

Send ack reaction in group messages

textChunkLimit
Type: number Default: 5

Maximum number of text chunks per AI response

mediaMaxMb
Type: number Default: 50

Maximum inbound media file size in megabytes. Outbound limit is controlled by agents.defaults.mediaMaxMb (default 5 MB)

groupPolicy
Type: string Default: "disabled"

Group chat policy. Options: disabled, allowlist, open

groupActivation
Type: string Default: "mention"

How the bot is triggered in groups. Options: mention, always

historyLimit
Type: number Default: 50

Number of recent messages to include as AI context

chunkMode
Type: string Default: "split"

How to handle long responses. Options: split, newline, truncate

messagePrefix
Type: string Default: ""

Optional prefix added to all outgoing messages

accounts.<id>.*
Type: object Default: {}

Per-account settings (phone, credentials path, overrides)

WhatsApp Frequently Asked Questions

WhatsApp Troubleshooting

WhatsApp shows 'Not Linked' or the QR code won't scan

The session credentials may have expired, or the phone's WhatsApp app was updated and invalidated the linked session.

Delete the credentials folder at ~/.openclaw/credentials/whatsapp/ and run 'openclaw channels login whatsapp' again to re-pair. Make sure your phone has a stable internet connection during the QR scan.
Bot connects but keeps disconnecting repeatedly

This usually happens when the phone goes offline for extended periods, or when another linked device conflicts with the Gateway session.

Ensure your phone stays connected to the internet. Check that you haven't exceeded the 4-device limit for linked devices. Remove unused linked devices from WhatsApp Settings → Linked Devices, then re-login.
Messages fail to send (timeout or delivery failure)

Rate limiting, network issues, or the recipient has blocked your number.

Check the Gateway logs for specific error codes. If you see rate-limit errors, reduce your sending frequency. For network issues, verify your server has stable internet. Try sending a manual message from your phone to confirm the number isn't restricted.
View Full Documentation Back to All Channels

Related Channels

Telegram

Easy

OpenClaw bot via Telegram grammY Bot API

Setup Guide

Discord

Easy

OpenClaw bot integration using discord.js

Setup Guide

Signal

Hard

OpenClaw privacy-focused connection via signal-cli

Setup Guide