How to Set Up OpenClaw on WhatsApp (Business API + QR Pairing)

Telegram is the easy channel. Create a bot with BotFather, paste a token, done. We wrote a 14-step guide and even that felt long.

WhatsApp is different. It's where 2 billion people actually message every day — including your customers. But connecting an AI agent to WhatsApp requires navigating Meta's Business API, phone number verification, webhook tunneling, and a pairing flow that breaks in new and exciting ways.

This guide covers both approaches: the official WhatsApp Business API (for businesses) and the QR pairing method (faster, more limited). We'll flag the gotchas Meta doesn't document.

Two ways to connect OpenClaw to WhatsApp

Option A: WhatsApp Business API (recommended for production)

This is the official way. You register as a business with Meta, get an API key, and receive messages through webhooks — just like Telegram.

Pros: Reliable, scalable, supports rich messages, Meta-approved Cons: Business verification required (1-7 days), phone number can't be used for personal WhatsApp simultaneously

Option B: QR Pairing (WhatsApp Web protocol)

This connects OpenClaw to WhatsApp the same way WhatsApp Web does — by scanning a QR code. Your personal or business WhatsApp number becomes the bot.

Pros: No Meta approval needed, works immediately, uses your existing number Cons: Less stable (Meta can break it), limited features, phone must stay connected, violates WhatsApp ToS for automation

For anything customer-facing, use Option A. Option B is fine for personal use or testing.

Option A: WhatsApp Business API Setup

Step 1: Create a Meta Business Account

1. Go to business.facebook.com
2. Create a new business account (or use existing)
3. Complete business verification:
   • Business name and address
   • Business registration document (KvK extract, Articles of Incorporation, etc.)
   • This takes 1-7 business days for Meta to approve

Don't skip verification. Without it, you get a test account limited to 5 messages per day.

Step 2: Set up a WhatsApp Business App

1. Go to developers.facebook.com
2. Create a new App → select Business type
3. Add the WhatsApp product
4. In WhatsApp → Getting Started, you'll see:
   • A Phone number ID
   • A WhatsApp Business Account ID
   • A temporary access token (expires in 24h)

Step 3: Register a phone number

You need a phone number that:

• Can receive SMS or voice calls (for verification)
• Is NOT currently registered on WhatsApp (or you'll lose personal access)
• Is a real number (VoIP numbers often don't work)

Tip: Buy a cheap prepaid SIM for your bot. Don't use your personal number unless you're okay with losing WhatsApp on that number.

In the Meta dashboard:

1. Go to WhatsApp → Phone Numbers
2. Click Add Phone Number
3. Enter the number and verify via SMS
4. Choose a display name (this is what users see)

Step 4: Generate a permanent access token

The temporary token expires in 24 hours. For production, create a System User token:

1. Go to Business Settings → System Users
2. Create a new system user (Admin role)
3. Click Generate New Token
4. Select your WhatsApp app
5. Grant these permissions:
   • whatsapp_business_management
   • whatsapp_business_messaging
6. Copy the token — this one doesn't expire

Step 5: Configure OpenClaw

Add the WhatsApp channel to your OpenClaw config:

{
  "channels": [
    {
      "type": "whatsapp",
      "agentSlug": "main",
      "config": {
        "accessToken": "EAAxxxxxxx...",
        "phoneNumberId": "123456789012345",
        "verifyToken": "my-secret-verify-token",
        "appSecret": "abcdef123456"
      }
    }
  ]
}

The verifyToken is a string you make up — Meta uses it to verify your webhook endpoint.

The appSecret is found in your Meta App Dashboard under Settings → Basic.

Step 6: Set up the webhook

Meta needs to reach your server to deliver messages. This means:

1. Your server needs a public HTTPS URL
2. You need to expose the WhatsApp webhook endpoint through your reverse proxy

In your Caddy/nginx config, add the WhatsApp webhook path:

handle /api/whatsapp/webhook {
    reverse_proxy 127.0.0.1:19001
}

Restart your reverse proxy, then in the Meta dashboard:

1. Go to WhatsApp → Configuration
2. Set Callback URL to https://bot.yourdomain.com/api/whatsapp/webhook
3. Set Verify Token to the same value you put in the OpenClaw config
4. Subscribe to these webhook fields:
   • messages
   • messaging_postbacks

Click Verify and Save. Meta will send a GET request to your webhook with the verify token. If OpenClaw is running and configured correctly, it'll respond and Meta will confirm the subscription.

Step 7: Set up a message template

WhatsApp has a 24-hour messaging window. After a user messages your bot, you can reply freely for 24 hours. After that, you can only send pre-approved message templates.

Create at least one template for re-engaging users:

1. Go to WhatsApp → Message Templates
2. Create a template:
   • Name: welcome_back
   • Category: Utility
   • Language: English
   • Body: "Hi {{1}}! I'm here if you have any questions. Just reply to start chatting."
3. Submit for approval (usually takes minutes to hours)

Step 8: Test

Send a WhatsApp message to your bot's phone number.

You: Hello
Bot: Hi there! How can I help you today?

Common issues:

Step 9: Go live

By default, your WhatsApp Business API is in development mode — only pre-registered test numbers can message your bot.

To go live:

1. Complete business verification (Step 1)
2. Request production access in the Meta dashboard
3. Wait for approval (1-3 days)

Once approved, anyone can message your bot's number.

---

Option B: QR Pairing Setup

If you don't want to deal with Meta's Business API, QR pairing connects OpenClaw to WhatsApp the same way your browser connects to WhatsApp Web.

How it works

1. OpenClaw starts a WhatsApp Web session
2. It generates a QR code
3. You scan the QR code with your phone's WhatsApp
4. Your phone bridges messages to OpenClaw

Configuration

{
  "channels": [
    {
      "type": "whatsapp-web",
      "agentSlug": "main",
      "config": {
        "pairingMode": "qr"
      }
    }
  ]
}

Pairing process

After starting OpenClaw, check the logs for the QR code:

docker logs openclaw-main

You'll see a QR code rendered in ASCII. Scan it with WhatsApp on your phone:

1. Open WhatsApp → Settings → Linked Devices
2. Tap Link a Device
3. Scan the QR code from the logs

If the QR code expires before you scan it, restart the container to generate a new one.

Limitations of QR pairing

• Phone must stay online — if your phone loses connection, the bot stops responding
• Session expires — WhatsApp disconnects linked devices periodically (every ~14 days). You'll need to re-scan.
• No message templates — you can't send proactive messages
• Terms of Service — Meta doesn't officially support automation via WhatsApp Web. They can ban your number.
• Single device — you can't use WhatsApp Web on your browser AND OpenClaw simultaneously

For testing and personal use, this works. For a business serving customers, use the Business API.

---

WhatsApp-specific considerations for OpenClaw

Message formatting

WhatsApp supports a subset of formatting:

• *bold*
• _italic_
• ~strikethrough~
• ```code blocks```

But NOT Markdown headers, links, or bullet points. Your agent's responses will look different on WhatsApp than on Telegram. Consider adding a note to your SOUL.md:

## Channel-specific behavior
When responding on WhatsApp, keep messages short (under 500 characters when possible).
Use *bold* for emphasis. Don't use Markdown headers or bullet lists — they don't render.

Media handling

WhatsApp supports sending and receiving:

• Images (JPEG, PNG)
• Videos (MP4)
• Audio messages (OGG, M4A)
• Documents (PDF, DOCX)
• Location pins

OpenClaw can receive these and pass them to the AI model (if the model supports vision/audio). Sending media back requires the Business API — QR pairing mode has limited media support.

Rate limits

WhatsApp imposes rate limits based on your business tier:

You start at 250 messages/day. That's fine for a small business. Tier upgrades happen automatically based on message quality and volume.

Privacy considerations

WhatsApp messages are end-to-end encrypted between users and your bot's phone number. But once the message reaches your server, it's decrypted and processed by OpenClaw.

If you're handling customer data, make sure your OpenClaw deployment has:

• logging.redactSensitive: true in config
• Docker volumes on encrypted storage (if required by regulations)
• A data processing agreement with your hosting provider
• session.dmScope: per-channel-peer to isolate conversations

---

The full WhatsApp setup checklist

Business API route

• Meta Business Account created and verified (1-7 days)
• WhatsApp Business App created on developers.facebook.com
• Phone number registered and verified
• System User created with permanent access token
• OpenClaw configured with WhatsApp channel
• Webhook endpoint exposed via reverse proxy with SSL
• Webhook verified in Meta dashboard
• Message template created and approved
• Bot tested with real WhatsApp messages
• Production access requested and approved

QR pairing route

• OpenClaw configured with whatsapp-web channel
• QR code scanned from logs
• Bot tested
• Reminder set to re-pair every 2 weeks

That's 10 steps for Business API (plus 1-7 days of waiting for Meta), or 3 steps for QR pairing (with ongoing maintenance).

Compare this to Telegram's setup: create bot with BotFather, paste token, set webhook. Done.

---

On ClawPort, WhatsApp Business API setup is guided — paste your access token, enter your phone number ID, and we handle the webhook, SSL, and verification automatically. QR pairing? We show the QR code in your dashboard — scan and go. Try it →