WhatsApp Setup

WhatsApp is one of the most popular messaging platforms, and OpenClaw connects to it using WhatsApp Web via the Baileys library. New here? Start with the WhatsApp quickstart (QR login in five steps), then return for groups, media, and Business Platform choices. If you are choosing between this Web-style channel and Meta's official business platform, jump to WhatsApp Business Platform vs this channel below.

Setting up WhatsApp is straightforward:

1. Start your Gateway: openclaw gateway
2. Link WhatsApp: openclaw channels login
3. Scan QR code with your phone
4. Start chatting!

WhatsApp uses QR code pairing (like WhatsApp Web):

Step-by-Step

1. Run: openclaw channels login
2. A QR code will appear in your terminal
3. Open WhatsApp on your phone
4. Go to Settings → Linked Devices
5. Tap "Link a Device"
6. Scan the QR code
7. Wait for connection confirmation

QR Code Display

The QR code appears as:

• ASCII art in terminal (default)
• Or as a URL you can open in browser
• Or displayed in Control UI dashboard

Direct Messages

• Send and receive DMs
• Media support (images, audio, video)
• Voice notes
• Location sharing
• Read receipts

Group Chats

• Join group chats
• Mention-based activation (default)
• Reply threading
• Group allowlists
• Sandboxed execution

Media Support

• Images and photos
• Audio and voice notes
• Video files
• Documents
• Location sharing

Basic Configuration

{
  "channels": {
    "whatsapp": {
      "enabled": true
    }
  }
}

DM Allowlist

Control who can message you:

{
  "channels": {
    "whatsapp": {
      "allowFrom": ["+1234567890", "+0987654321"]
    }
  }
}

Group Configuration

{
  "channels": {
    "whatsapp": {
      "groups": {
        "*": {
          "requireMention": true
        }
      }
    }
  }
}

DM Pairing

By default, unknown senders require pairing:

• Unknown contacts receive a pairing code
• Approve with: openclaw pairing approve whatsapp <code>
• Once approved, added to allowlist

Opening DM Access

To allow public DMs (not recommended):

• Set dmPolicy: "open"
• Include "*" in allowlist
• Warning: Only use with proper security

QR Code Not Appearing

If QR code doesn't show:

1. Check terminal supports QR display
2. Try opening Control UI: http://localhost:18789
3. Check Gateway is running: openclaw status

Connection Drops

If WhatsApp disconnects:

1. Check internet connection
2. Restart Gateway: openclaw gateway
3. Re-link device: openclaw channels login
4. Check WhatsApp Web isn't open elsewhere

Messages Not Received

If messages aren't coming through:

1. Check Gateway is running
2. Verify WhatsApp is connected
3. Check allowlist configuration
4. Review Gateway logs

• Use Allowlists - Control who can message you
• Enable Mention Gating - For group chats
• Keep Gateway Running - Maintains WhatsApp connection
• Monitor Connection - Check status regularly
• Backup Credentials - Save WhatsApp session data

Not legal advice. WhatsApp and Meta policies vary by country and product. Use the following as engineering questions alongside counsel and Meta's own docs.

The steps above use WhatsApp Web-style pairing (QR login, Baileys-class libraries)—similar to WhatsApp Web in a browser. That path suits personal or small-team setups where you accept the operational and ToS risks of unofficial clients.

Organizations that need Meta-supported customer messaging usually adopt the official Business Platform: verified business, approved numbers, template messages, conversation-category pricing, and contact-center tooling. Work shifts to webhooks and Meta dashboards—not QR login on a personal account. If compliance asks for vendor-supported channels or B2C opt-in records, evaluate WABA early; it is a different project than self-hosting this channel.

Both paths get prompt-injection and social engineering from inbound messages. Read Security and tips regardless. WABA adds billing accounts and webhook secrets to rotate. Official product limits: Meta's documentation. OpenClaw behavior: docs.openclaw.ai. Disclosure for how this site is run.