How to Connect OpenClaw to WhatsApp: Complete Setup Guide

WhatsApp has over 2 billion users worldwide. It's where most people spend their messaging time — and now you can put a powerful AI agent right inside it.

With OpenClaw connected to WhatsApp, you get an AI assistant that remembers your conversations, uses tools (web search, code execution, file management), runs scheduled tasks, and works across your other platforms too. We also have guides for Discord and Telegram if you want to connect there too. This guide walks you through every step.

Fastest path: Ampere.sh handles WhatsApp integration for you — just paste your credentials in the dashboard and you're live. No webhook setup, no server configuration. Free tier available.

What You'll Need

An OpenClaw instance — Ampere.sh (managed) or self-hosted
A WhatsApp account — regular WhatsApp or WhatsApp Business both work
A phone with WhatsApp installed
An LLM API key — Anthropic, OpenAI, Google, or any supported provider

Two Ways to Connect WhatsApp

Recommended

Method 1: WhatsApp Business API (Cloud API)

The official way. Uses Meta's Cloud API for reliable, production-grade messaging. Supports text, images, documents, reactions, and read receipts. Best for serious use.

Official and reliable. Full feature support. Scales to any volume. For business use cases.

Alternative

Method 2: WhatsApp Web Bridge

Uses a WhatsApp Web session to connect. Simpler setup — just scan a QR code. But less reliable for production and may violate WhatsApp ToS.

Quick setup. No Meta Business account needed. Less reliable. May break with updates.

We'll cover Method 1 (Business API) in detail — it's the recommended approach for any real usage.

Step 1: Log in to Your Ampere Dashboard

STEP 1

Go to ampere.sh/dashboard and sign in to your account. If you don't have an account yet, sign up for free.

Once logged in, you'll see your agent dashboard with all available connections.

Step 2: Go to Connections and Select WhatsApp

STEP 2

Navigate to the Meta for Developers portal:

Click "My Apps" → "Create App"
Give it a name (e.g., "My AI Agent")
On the app dashboard, find "WhatsApp" and click "Set up"
Follow the prompts to connect your Meta Business account

Meta will provide you with a test phone number to start with. You can add your own phone number later for production use.

Step 3: Send "Connect WhatsApp" in Dashboard Chat

STEP 3

In the WhatsApp section of your Meta app, you'll need three things:

Phone Number ID — found under WhatsApp → API Setup
WhatsApp Business Account ID — in your business settings
Permanent Access Token — generate one under System Users in Business Settings

Generate a Permanent Access Token

The temporary token from Meta expires in 24 hours. For production, create a permanent one:

Go to Business Settings → System Users
Create a new system user (Admin role)
Click "Generate New Token"
Select your WhatsApp app
Enable these permissions: whatsapp_business_messaging, whatsapp_business_management
Copy the generated token — save it securely

Security: Your WhatsApp access token is a sensitive credential. Never share it publicly, commit it to Git, or post it in chat. Store it securely in your OpenClaw config or environment variables.

Step 4: Scan the QR Code

STEP 4

Add your WhatsApp credentials to your OpenClaw configuration:

Option A: Using Ampere.sh (Easiest)

Log in to your Ampere Dashboard
Navigate to Channels → WhatsApp
Paste your access token, Phone Number ID, and Business Account ID
Ampere automatically provides the webhook URL — copy it for Step 5
Click Save

Option B: Self-Hosted

Edit your openclaw.yaml:

# openclaw.yaml

channels:
  whatsapp:
    accessToken: "YOUR_PERMANENT_ACCESS_TOKEN"
    phoneNumberId: "YOUR_PHONE_NUMBER_ID"
    businessAccountId: "YOUR_BUSINESS_ACCOUNT_ID"
    verifyToken: "any-random-string-you-choose"
    webhookPath: "/webhook/whatsapp"

Tip: The verifyToken is a secret string you create yourself. It's used to verify the webhook connection with Meta — pick something random and secure.

Step 5: Test the Connection

STEP 5

WhatsApp needs a way to send incoming messages to your OpenClaw agent. This is done through a webhook — a URL that Meta calls whenever someone messages your WhatsApp number.

For Ampere.sh Users

Ampere provides your webhook URL automatically. Copy it from the dashboard and paste it in Meta's WhatsApp configuration:

# Your Ampere webhook URL looks like:
https://your-agent.ampere.sh/webhook/whatsapp

For Self-Hosted Users

Your OpenClaw gateway needs to be publicly accessible. If you're behind a firewall or NAT, use a reverse proxy with a domain, or a tunnel service:

# Option 1: Use your domain with nginx
https://openclaw.yourdomain.com/webhook/whatsapp

# Option 2: Use cloudflared tunnel (for testing)
$ cloudflared tunnel --url http://localhost:3000
# Use the generated URL + /webhook/whatsapp

Configure the Webhook in Meta

In Meta for Developers, go to WhatsApp → Configuration
Under Webhook, click "Edit"
Enter your Callback URL (your webhook URL from above)
Enter your Verify Token (the same string you put in openclaw.yaml)
Click "Verify and Save"
Subscribe to the "messages" webhook field

Important: Your OpenClaw gateway must be running before you verify the webhook. Meta sends a verification request that OpenClaw needs to respond to.

Step 6: Start Using Your Agent

STEP 6

Start (or restart) your OpenClaw gateway:

$ openclaw gateway start
✓ Gateway started
✓ WhatsApp channel connected
✓ Webhook listening on /webhook/whatsapp
✓ Agent is live!

What Your WhatsApp Agent Can Do

Remember Everything

Unlike regular chatbots, your agent remembers past conversations. "What did I ask about last week?" — it knows.

Search the Web

"What's the latest news about AI?" — your agent searches the web and gives you a summary, right in WhatsApp.

Scheduled Messages

Set up morning briefings, reminders, or daily check-ins that arrive automatically on WhatsApp.

Image Analysis

Send a photo and ask about it. "What plant is this?" or "Translate this menu" — the agent analyzes images.

Run Code

Ask it to calculate something, process data, or write a script — it can execute code and send you the results.

Multi-Platform

Same agent on WhatsApp, Discord, and Telegram. Start a chat on WhatsApp, continue on Discord — context carries over.

WhatsApp-Specific Tips

WhatsApp has some formatting differences from other platforms. OpenClaw handles most of this automatically, but here are things to know:

No markdown tables — WhatsApp doesn't render tables. Your agent uses bullet lists instead
No headers — WhatsApp doesn't support # headers. The agent uses bold or CAPS for emphasis
Bold/italic work — *bold*, _italic_, ~strikethrough~, and ```code``` all render in WhatsApp
Link previews — WhatsApp auto-generates link previews, so your agent doesn't need to describe URLs
Voice messages — if TTS is configured, your agent can send voice notes (great for hands-free use)

Using the Agent in WhatsApp Groups

Your OpenClaw agent can participate in WhatsApp group chats too. Add the business number to a group, and it can:

Answer questions when mentioned or directly addressed
Stay silent during casual conversations (smart group chat behavior)
Summarize long discussions on request
Remember group-specific context and decisions

Group behavior: OpenClaw agents are configured to participate naturally in group chats — they respond when it's useful and stay quiet when the conversation is flowing fine without them. No spamming every message.

Troubleshooting

Webhook verification fails

Gateway must be running — start OpenClaw before verifying the webhook in Meta
Check the verify token — it must match exactly between Meta and your openclaw.yaml
URL must be HTTPS — Meta requires a valid SSL certificate on your webhook endpoint
Firewall/port — make sure port 443 is open and your domain resolves correctly

Messages sent but no response

Check the access token — if using the temporary token, it expires in 24 hours. Generate a permanent one
Check webhook subscriptions — make sure you subscribed to the "messages" field
Test number limitations — Meta's test number can only message numbers you've added to the "allowed list" in the API setup. Add your number there
Check OpenClaw logs — run openclaw gateway status for error details

Messages are delayed

LLM response time is usually the bottleneck — faster models (Claude Haiku, GPT-4o-mini) respond quicker
WhatsApp's Cloud API has minor latency (~1-2 seconds) — this is normal
If using a tunnel for self-hosting, latency may be higher. A proper domain/VPS is better for production

"24-hour messaging window" issue

WhatsApp Business API has a rule: you can only send messages to someone within 24 hours of their last message to you. After that, you need to use a pre-approved message template.

This means your agent can always reply to incoming messages, but proactive outreach (like scheduled briefings) requires template approval from Meta. OpenClaw handles this by sending templates when needed.

Privacy & Security on WhatsApp

Important security considerations when using an AI agent on WhatsApp:

End-to-end encryption — WhatsApp Business API messages are not end-to-end encrypted (unlike regular WhatsApp). Messages pass through Meta's servers
Your agent's memory is private — MEMORY.md and daily notes stay on your server, not on WhatsApp/Meta
LLM processing — messages are sent to your LLM provider (Anthropic, OpenAI) for processing. API data is not used for training
SOUL.md boundaries — configure your agent's personality file with clear rules about handling sensitive information

For maximum privacy, self-host OpenClaw and use local models via Ollama. Only the WhatsApp message routing passes through Meta — everything else stays on your hardware.

Frequently Asked Questions

Is the WhatsApp Business API free?

Meta provides a generous free tier — 1,000 messages per month at no cost. After that, pricing is very affordable (~$0.005-0.01 per message depending on the country). For most personal use cases, you'll stay within the free tier.

Can I use my personal WhatsApp number?

No, WhatsApp Business API requires a separate phone number from your personal WhatsApp. You can get a second number from your carrier, use a VoIP service, or Meta can provide a test number to start with.

Can the agent send images and files?

Yes! The Business API supports images, documents, PDFs, audio, and even videos. Your agent can send files it generates (charts, reports, etc.) or forward files from other sources.

Does the agent work in WhatsApp groups?

Yes, your agent can participate in group chats. It responds when mentioned or addressed directly, and stays quiet during normal conversation. Perfect for team collaboration.

Can I connect both WhatsApp and Discord to the same agent?

Absolutely! OpenClaw supports multiple channels simultaneously. Same agent, same memory, but available on WhatsApp, Discord, Telegram, Slack, and more. Context carries across platforms.

What about the WhatsApp Web bridge method?

We mention it as an alternative, but don't recommend it for production use. It's less reliable, breaks with WhatsApp updates, and may violate WhatsApp's Terms of Service. The Business API is the proper way.

Can the agent handle voice messages?

Yes, if you enable text-to-speech (TTS) in your OpenClaw config. The agent can send voice replies to WhatsApp. Voice message recognition (speech-to-text) is also supported with the right configuration.

Ready to put AI on WhatsApp?

Get your OpenClaw agent connected to WhatsApp in minutes with Ampere's managed platform.

Start Free Trial