OpenClaw WhatsApp Setup Guide

WhatsApp is the most requested OpenClaw channel by a wide margin. Every week I see the question in the community Discord: "How do I connect my OpenClaw agent to WhatsApp?"

I get it. Telegram is great for tech-savvy users, but WhatsApp has 2.7 billion monthly active users. If you're building an AI agent for customer support, personal assistance, or business automation, WhatsApp is where your users already are.

I've set up WhatsApp connections for over a dozen OpenClaw instances — both for MrDelegate customers and for our own internal agents. This guide covers every step, every gotcha, and every decision point so you can get your agent live on WhatsApp without the trial-and-error I went through.

Try MrDelegate — Get your own OpenClaw assistant, fully hosted and managed. Start free trial →

Prerequisites

Before starting, you need:

1. A running OpenClaw instance — gateway started, at least one agent working (test via CLI or Telegram first)
2. Node.js 22+ installed on your server
3. A Meta Business account — free to create at business.facebook.com
4. A phone number for WhatsApp Business — this can't be a number already registered with regular WhatsApp. Use a new number or migrate an existing one
5. A Meta Developer account — free at developers.facebook.com

If you already have OpenClaw running on Telegram or Discord and just want to add WhatsApp, you're about 20 minutes away from a working setup.

Step 1: Create a Meta App

1. Go to developers.facebook.com/apps
2. Click Create App
3. Select Business as the app type
4. Give it a name (e.g., "My OpenClaw Agent") and select your Meta Business account
5. On the app dashboard, find WhatsApp in the product list and click Set Up

This gives you access to the WhatsApp Business API through Meta's Cloud API — the hosted version that doesn't require you to run your own WhatsApp server.

Get Your Credentials

After setup, you'll see the WhatsApp section in your app dashboard. Note these values:

• Phone Number ID — the ID of the test phone number Meta provides (or your own business number)
• WhatsApp Business Account ID — your WABA ID
• Temporary Access Token — a short-lived token for testing (you'll create a permanent one later)

Step 2: Set Up a Permanent Access Token

The temporary token expires in 24 hours. For a production agent, you need a permanent System User token.

1. Go to business.facebook.com/settings/system-users
2. Click Add to create a new System User
3. Set the role to Admin
4. Click Add Assets, find your app, and grant Full Control
5. Click Generate Token for your app
6. Select the permissions: whatsapp_business_management and whatsapp_business_messaging
7. Copy the token — this is your permanent access token. Store it securely.

This token doesn't expire and has the permissions needed for your agent to send and receive messages.

Step 3: Configure the Webhook

WhatsApp messages arrive at your OpenClaw instance via webhooks. Meta sends an HTTP POST request to your server every time someone messages your WhatsApp number.

Ensure Your Server Is Publicly Accessible

Your OpenClaw gateway needs a public URL that Meta can reach. Options:

• VPS with a domain — point a subdomain like webhook.yourdomain.com to your server's IP
• Cloudflare Tunnel — if you're running OpenClaw on a home server or behind NAT
• Tailscale Funnel — another option for exposing a local server

You need HTTPS. Meta won't send webhooks to HTTP endpoints. If you're using a VPS with nginx, set up a Let's Encrypt certificate:

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d webhook.yourdomain.com
```bash

### Configure the Webhook in Meta Developer Dashboard

1. In your app dashboard, go to **WhatsApp** → **Configuration**
2. Under **Webhook**, click **Edit**
3. Set the **Callback URL** to your OpenClaw webhook endpoint:
   ```bash
   https://webhook.yourdomain.com/webhook/whatsapp
   ```bash
4. Set a **Verify Token** — this is a secret string you choose (e.g., `my-openclaw-verify-token-2026`). You'll add this to your OpenClaw config
5. Click **Verify and Save**

Meta will send a GET request to your URL with a challenge parameter. OpenClaw handles this verification automatically if your webhook config is correct.

6. After verification, subscribe to the **messages** webhook field by checking the box


## Step 4: Configure OpenClaw

Now add the WhatsApp channel to your OpenClaw configuration.

Edit your `openclaw.json` (typically at `~/.openclaw/openclaw.json`):

```json
{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "accessToken": "YOUR_PERMANENT_ACCESS_TOKEN",
      "phoneNumberId": "YOUR_PHONE_NUMBER_ID",
      "businessAccountId": "YOUR_WABA_ID",
      "verifyToken": "my-openclaw-verify-token-2026",
      "webhookPath": "/webhook/whatsapp"
    }
  }
}
```bash

Swap in your actual credentials from Step 1 and Step 2.

### Restart the Gateway

```bash
openclaw gateway restart
```bash

Check the logs to confirm the WhatsApp channel initialized:

```bash
openclaw gateway logs
```bash

You should see a line like:

```bash
[WhatsApp] Channel initialized — listening on /webhook/whatsapp
```bash


## Step 5: Test the Connection

Send a message to your WhatsApp Business number from a personal WhatsApp account.

If everything is configured correctly:

1. Meta receives the message and sends a webhook POST to your server
2. OpenClaw receives the webhook, identifies the sender, creates or resumes a session
3. The agent processes the message and generates a response
4. OpenClaw sends the response back via the WhatsApp Business API
5. The response appears in the WhatsApp conversation

**Troubleshooting if no response arrives:**

- Check OpenClaw logs: `openclaw gateway logs` — look for webhook receipt confirmation
- Verify the webhook URL is correct in the Meta dashboard
- Confirm HTTPS is working: `curl https://webhook.yourdomain.com/webhook/whatsapp` should return a response
- Check that the access token has the correct permissions
- Verify the phone number ID matches your WhatsApp Business number


## Step 6: Register Your Business Phone Number (Production)

Meta provides a test phone number for development, but for production use you'll want your own business number.

1. In the Meta Business Suite, go to **WhatsApp Manager** → **Phone Numbers**
2. Click **Add Phone Number**
3. Enter your business phone number (must not be registered on regular WhatsApp)
4. Verify via SMS or voice call
5. Set your **Business Profile**: name, description, category, website
6. Update the `phoneNumberId` in your `openclaw.json` with the new number's ID

### Message Templates (Required for Business-Initiated Messages)

WhatsApp requires pre-approved message templates for business-initiated messages (messages you send first, not replies). For agent-initiated outreach like daily briefings or proactive alerts:

1. Go to **WhatsApp Manager** → **Message Templates**
2. Create templates for your use cases:
   - Daily summary template
   - Alert/notification template
   - Follow-up template
3. Submit for approval (usually takes 1-24 hours)

**Important:** Replies to user-initiated messages don't require templates. If someone messages your agent first, you can reply freely for 24 hours. After 24 hours of inactivity, you need a template to re-initiate.


## Step 7: Configure Agent Behavior for WhatsApp

WhatsApp has specific formatting and behavior constraints that differ from Telegram or Discord. Add these guidelines to your agent's `AGENTS.md` or `SOUL.md`:

```markdown
## WhatsApp Channel Rules
- No markdown tables — use bullet lists or numbered lists
- No headers (# syntax) — use **bold** or CAPS for emphasis
- Keep messages under 4096 characters (WhatsApp limit)
- Use emoji naturally but don't overdo it
- No code blocks for non-technical users
- Links don't auto-preview — include a brief description with each URL
```bash

### Handling Media

OpenClaw supports sending and receiving media on WhatsApp:

- **Images** — agents can send images using the media upload API
- **Documents** — PDFs, spreadsheets, and other files
- **Voice messages** — if you have TTS configured, agents can send voice notes
- **Location** — agents can send location pins

To enable media handling, ensure your skill files include instructions for WhatsApp-specific formatting.


## Step 8: Set Up Proactive Messaging

One of OpenClaw's killer features is proactive behavior — the agent does things without being asked. On WhatsApp, this means:

### Daily Briefings

Set up a cron job in OpenClaw to send morning briefings:

```json
{
  "crons": {
    "morning-brief": {
      "schedule": "0 7 * * *",
      "channel": "whatsapp",
      "recipient": "YOUR_PHONE_NUMBER",
      "task": "Check email, calendar, and news. Send a morning briefing.",
      "template": "daily_summary"
    }
  }
}
```bash

### Alerts and Notifications

Configure the agent to send WhatsApp messages when specific events occur:

- Server health issues detected
- Important email received
- Calendar reminder (30 minutes before meetings)
- Task completion notifications

Remember: business-initiated messages require approved templates. Design your templates during setup to cover your common notification types.


## Common Issues and Solutions

### "Webhook Verification Failed"

Your server isn't returning the correct challenge response. Check:
- The `verifyToken` in `openclaw.json` matches exactly what you entered in the Meta dashboard
- Your server is accessible via HTTPS at the callback URL
- No firewall blocking incoming requests on port 443

### "Messages Send But Agent Doesn't Reply"

The webhook is receiving messages but the agent isn't processing them:
- Check OpenClaw logs for errors in message processing
- Verify the WhatsApp channel is enabled in `openclaw.json`
- Ensure the AI model API key is valid and has credits

### "Reply Arrives But Is Empty"

The agent generated a response but WhatsApp rejected it:
- Check for markdown formatting that WhatsApp doesn't support
- Ensure the response is under 4096 characters
- Look for special characters that might break the API call

### "Messages Work for 24 Hours Then Stop"

WhatsApp's 24-hour conversation window expired. For ongoing communication:
- Use message templates for business-initiated messages
- Prompt users to message the agent first (keeps the 24-hour window open)
- Set up re-engagement templates that comply with WhatsApp's policies

### Rate Limits

WhatsApp Business API has sending limits based on your business verification status:
- **Unverified:** 250 business-initiated conversations per 24 hours
- **Verified (Tier 1):** 1,000 per 24 hours
- **Verified (Tier 2):** 10,000 per 24 hours
- **Verified (Tier 3):** 100,000 per 24 hours

For a personal AI assistant handling one user, the unverified limit is more than enough. For business use with multiple users, verify your business through Meta.


## Advanced: Multi-User WhatsApp Setup

If you're running an AI assistant service where multiple people interact with your WhatsApp agent:

### Session Management

OpenClaw creates separate sessions for each unique WhatsApp number. Each user gets their own memory context — Person A's conversations don't leak into Person B's responses.

### User Identification

WhatsApp provides the sender's phone number with each message. You can use this to:
- Look up user records in a database
- Apply different permissions or personalities per user
- Route specific users to specialized agents

### Group Chat Support

OpenClaw supports WhatsApp group messages. The agent participates in group conversations and can:
- Respond to @mentions
- Answer questions addressed to it
- Stay silent during casual conversation
- Provide summaries on request

Configure group behavior in your agent's instructions to avoid the agent responding to every message in a busy group.


## WhatsApp vs. Telegram for OpenClaw

I get asked this constantly. Here's my honest take:

**Telegram is better for technical users and developers.** It has richer formatting, inline buttons, thread management, and no template requirements. Bot setup is simpler (just talk to BotFather). If you're the only person using your agent and you're comfortable with Telegram, use Telegram.

**WhatsApp is better for reaching normal people.** Your mom is on WhatsApp. Your clients are on WhatsApp. Your team might be on WhatsApp. If the agent needs to interact with people who aren't going to download a new app, WhatsApp is the right choice.

**You can run both simultaneously.** OpenClaw supports multiple channels connected to the same agent with shared memory. Messages from WhatsApp and Telegram are handled by the same agent with the same context. This is what we do at MrDelegate — customers choose their preferred channel, and the agent works across all of them.


## MrDelegate: WhatsApp Already Configured

If this setup process feels like more than you want to deal with, MrDelegate includes WhatsApp configuration as part of every plan. We handle the Meta Business account setup, webhook configuration, phone number registration, and template approvals. You get a working WhatsApp AI agent without touching the Meta developer dashboard.

Plans start at $29/month at [mrdelegate.ai](https://mrdelegate.ai).

For everyone doing it themselves — the setup above covers everything you need. The initial configuration takes 20-30 minutes, and once it's running, WhatsApp becomes one of the most convenient channels for interacting with your OpenClaw agent. It's always in your pocket, notifications work perfectly, and the conversation feels natural.

Get it set up. You won't go back to checking things manually.

## Ready to get started?

[Start your free trial](https://mrdelegate.ai/start) and experience the power of OpenClaw, hosted by MrDelegate.