OpenClaw WhatsApp: Run AI Agents From the World's Biggest Chat

Most agent deployments fail at distribution. The agent is capable, the logic is solid, but users have to go somewhere new to access it. WhatsApp solves that problem permanently. When your OpenClaw agent lives inside an app users already open 30 times a day, adoption is not a concern — it's automatic.

Two Ways to Connect WhatsApp to OpenClaw

WhatsApp integration for OpenClaw comes in two flavors, and choosing the wrong one wastes weeks. Here's what separates them.

The WhatsApp Business API is the official, Meta-sanctioned path. You register a business, verify a phone number, create an app in Meta's developer portal, and connect it to OpenClaw via webhook. This is the path for anything customer-facing, high-volume, or where compliance matters. It's slower to set up but stable, scalable, and within Meta's Terms of Service.

The QR bridge method uses an open-source WhatsApp bridge (such as whatsmeow or Baileys-based bridges) that you run locally or on a server. You scan a QR code from your phone to link the session, and the bridge forwards messages to OpenClaw. This works on personal numbers, takes under 30 minutes, and is perfect for personal use or internal team bots — but it's not sanctioned by Meta for automation at scale.

WhatsApp Business API Setup

Start at the Meta for Developers portal. You need a Meta Business account — if you don't have one, create it at business.facebook.com first. Business verification can take 24–48 hours, so start this process before you touch any OpenClaw config.

1. Create a Meta developer app and add the "WhatsApp Business" product to it
2. Add a phone number to your WhatsApp Business Account (WABA) — this must be a number not already on WhatsApp
3. Verify the number via SMS or voice call
4. In the app settings, find your Phone Number ID and WhatsApp Business Account ID
5. Generate a System User access token from your Business Manager with the whatsapp_business_messaging permission
6. Set up a webhook URL pointing to your OpenClaw gateway's WhatsApp webhook endpoint

Your OpenClaw gateway receives incoming messages at a webhook URL in this format: https://your-gateway.com/webhooks/whatsapp. Configure this URL in the Meta developer console under your app's WhatsApp webhook settings. Set the verify token to match what you configure in OpenClaw's channel YAML.

# channels/whatsapp-business.yaml
type: whatsapp_business
phone_number_id: "1234567890"
waba_id: "0987654321"
access_token: "${WA_ACCESS_TOKEN}"
verify_token: "${WA_VERIFY_TOKEN}"
webhook_path: /webhooks/whatsapp
agent_id: customer-support

QR Pairing Method

For personal or internal use, the QR bridge is dramatically faster. You'll need a WhatsApp bridge server running alongside OpenClaw. Several open-source options exist — the most commonly used with OpenClaw is the go-whatsapp bridge.

Deploy the bridge on the same server as your OpenClaw gateway, or on a separate machine with network access. Start the bridge and watch the logs for the QR code output. Open WhatsApp on your phone, go to Linked Devices, and scan the QR code. The bridge stores the session credentials so you won't need to re-scan unless the session expires.

# channels/whatsapp-personal.yaml
type: whatsapp_bridge
bridge_url: http://localhost:8765
session_file: /data/wa-session.json
agent_id: personal-assistant
reconnect_on_failure: true

Once connected, test immediately. Send a message from your phone to the linked number and watch OpenClaw's logs. You should see the incoming message logged within 2–3 seconds. If nothing appears, check that the bridge is running and the session is active — the bridge logs will tell you.

Message Types and Handling

WhatsApp supports more than text. Your OpenClaw agent can receive and respond with the full range of WhatsApp message types — and configuring which ones your agent handles changes the quality of the experience dramatically.

Text messages are the default and require no special configuration. They pass directly to your agent's LLM as user input.

Voice notes arrive as audio files. If you have a speech-to-text model configured in OpenClaw (Whisper works well here), the audio is automatically transcribed and passed to the agent as text. Users who prefer speaking over typing — particularly common in WhatsApp-heavy markets — will use this heavily.

Sound familiar? The "just reply to a voice note" pattern is one of the highest-engagement interaction modes we see in WhatsApp deployments. Don't skip STT setup.

Images and documents can be forwarded to your agent's vision model or file-processing pipeline. Configure the media types your agent accepts in the channel YAML and set size limits to avoid processing large files that would blow your token budget.

Location messages arrive as latitude/longitude pairs. If your agent does anything location-aware — local search, delivery tracking, store finders — this unlocks a native interaction pattern that feels much smoother than asking users to type an address.

Automation Patterns That Actually Work

The most effective WhatsApp agent patterns we've seen across deployments share a few characteristics: they respond fast, they stay in character, and they know when to hand off.

Customer support triage is the highest-ROI pattern. The agent handles Tier 1 queries — order status, FAQs, basic troubleshooting — and escalates complex cases to a human agent via a handoff keyword or confidence threshold. Response time drops from hours to seconds. Customer satisfaction scores typically improve alongside it.

Here's where most teams stop — they set up the agent, celebrate fast responses, and never build the escalation path. Then a frustrated customer asks something the agent can't handle and gets stuck in a loop. Build the handoff before you launch.

Appointment booking works exceptionally well via WhatsApp. The agent collects the user's preferred date and time through a conversational flow, checks availability via a calendar API tool, and confirms the booking — all without the user leaving WhatsApp. Fewer steps than a booking form. Higher completion rates.

Broadcast + reply is a pattern unique to WhatsApp's business messaging. Send a template message to a list of opted-in contacts, then let the agent handle the replies. The agent personalizes responses based on the individual's history. This works for follow-up sequences, reorder reminders, and post-purchase check-ins.

Common Mistakes to Avoid

• Not setting a system prompt that establishes context — WhatsApp users don't know they're talking to an AI unless you tell them. Decide whether to disclose upfront and set your system prompt accordingly. Ambiguity leads to confused users and negative experiences.
• Ignoring message status callbacks — WhatsApp sends delivery and read receipts. Use these to track whether the agent's responses are being delivered. A pattern of undelivered messages signals a number quality issue.
• Sending too many messages in quick succession — WhatsApp rate limits aggressive senders and can temporarily ban numbers. If your agent generates multiple responses, concatenate them into a single message or add short delays between sends.
• No opt-out mechanism — Any WhatsApp automation targeting multiple users needs a clear opt-out path. "STOP" or "Unsubscribe" should immediately halt all automated messages. This is legally required in many jurisdictions.
• Using a personal number for business volume — Personal numbers get flagged and banned much faster than registered Business API numbers. As soon as volume exceeds a few hundred messages per day, migrate to the Business API.

Frequently Asked Questions

Does OpenClaw WhatsApp require a Business API account?

No — QR code pairing with a personal number works via the WhatsApp Web bridge. The Business API is more stable and the right choice for production deployments. It requires Meta Business verification, which takes 2–5 days, but unlocks higher message limits and official compliance.

How many messages can an OpenClaw WhatsApp agent handle per day?

Personal number connections share WhatsApp's standard limits — Meta restricts high-volume personal accounts. Business API accounts start at 1,000 conversations per day and scale with verification tier. For production, always use the Business API to avoid account restrictions.

Can the WhatsApp agent send images, documents, and voice notes?

Yes. OpenClaw's WhatsApp integration supports all standard media types — images, documents, audio, video, and location. Configure media-handling capability in the channel config. Voice notes are transcribed automatically if you have an STT model configured.

What happens if the QR code connection drops?

The bridge attempts automatic reconnection on drops. If the session expires — after extended inactivity or a phone restart — you need to re-scan the QR code. Monitor the bridge logs and set up an alert on session drops so you catch outages before users do.

Can I use one OpenClaw instance with multiple WhatsApp numbers?

Yes. Register each number as a separate channel in OpenClaw with its own channel ID. Route different numbers to different agents — for example, a support number to a helpdesk agent and a sales number to a lead qualification agent.

Is the WhatsApp integration compliant with Meta's Terms of Service?

Business API use with proper Meta registration is fully compliant. QR-code-based automation is a grey area — Meta prohibits automation on personal accounts. For anything customer-facing or at scale, use the official Business API to stay within Meta's policies and avoid account bans.