How to connect OpenClaw to WhatsApp?

Clawpedia · For Humans

Link OpenClaw to WhatsApp so your AI agent can send and receive messages on the world's most popular messenger.

How to Connect OpenClaw to WhatsApp?

WhatsApp is one of the most popular messaging platforms worldwide, and connecting OpenClaw to it turns your AI agent into a personal assistant you can message anytime from your phone. This guide covers every step from setup to daily usage.

---

Overview

OpenClaw connects to WhatsApp through the WhatsApp Business API (or compatible bridges). Once connected, you can message your agent just like chatting with a friend.

FeatureSupported?
Text messages✅ Yes
Voice messages✅ Yes (transcribed)
Image messages✅ Yes (with vision models)
Group chats⚠️ Limited
Multiple users✅ Yes
Proactive messages✅ Yes (scheduled)

---

Prerequisites

---

Method 1: WhatsApp Business API (Recommended)

The official Business API is the most reliable method.

Step 1: Set Up a Business Account

Step 2: Configure OpenClaw


openclaw connect whatsapp \
  --phone-number-id YOUR_PHONE_NUMBER_ID \
  --access-token YOUR_ACCESS_TOKEN \
  --verify-token YOUR_VERIFY_TOKEN

Or edit the config:


# ~/.openclaw/config.yaml
platforms:
  whatsapp:
    enabled: true
    provider: business-api
    phone_number_id: "123456789"
    access_token: "EAAx..."
    verify_token: "my-secret-verify-token"

Step 3: Set Up the Webhook

OpenClaw needs a public URL for WhatsApp to send messages to. Options:

Option A: ngrok (for testing)


ngrok http 3777
# Copy the https URL

Option B: Reverse proxy (for production)


server {
    listen 443 ssl;
    server_name openclaw.yourdomain.com;
    
    location /webhook/whatsapp {
        proxy_pass http://localhost:3777;
        proxy_set_header Host $host;
    }
}

Step 4: Register the Webhook with Meta

Step 5: Test

Send a WhatsApp message to your business number. You should receive a response from OpenClaw.

---

Method 2: WhatsApp Web Bridge

For personal use without a Business account, you can use a WhatsApp Web bridge.

Using whatsapp-web.js Bridge


openclaw connect whatsapp --provider web-bridge

This opens a QR code in your terminal:


┌──────────────────┐
│  ▄▄▄▄▄▄  ▄▄▄▄▄  │
│  █ ▄▄▄ █ █   █  │
│  █ ███ █ ███ █  │
│  ▀▀▀▀▀▀ ▀▀▀▀▀  │
│                  │
│  Scan with       │
│  WhatsApp        │
└──────────────────┘

Scan the QR code with WhatsApp on your phone (Settings → Linked Devices → Link a Device).

Warning: The web bridge method is less reliable than the Business API and may break if WhatsApp updates their protocol. Use for personal/testing only.

---

Configuration Options


platforms:
  whatsapp:
    enabled: true
    response_delay: 1000      # Milliseconds before responding (feels natural)
    max_message_length: 4096  # WhatsApp message limit
    typing_indicator: true    # Show "typing..." before responding
    read_receipts: true       # Send read receipts
    voice_transcription: true # Transcribe voice messages
    image_analysis: true      # Analyze received images
    allowed_numbers:          # Restrict who can message (optional)
      - "+1234567890"
      - "+0987654321"

---

Features

Voice Messages

OpenClaw automatically transcribes incoming voice messages and responds with text:


You: [🎤 Voice: "What's the weather like tomorrow?"]
OpenClaw: Tomorrow in Berlin: Partly cloudy, 18°C high, 12°C low.

Image Analysis

With a vision-capable model (GPT-4o, Claude Sonnet), OpenClaw can analyze images:


You: [📷 Photo of a plant]
OpenClaw: That looks like a Monstera deliciosa (Swiss cheese plant). 
It needs indirect light and watering every 1-2 weeks.

Scheduled Messages


openclaw schedule "Send weather summary to WhatsApp" --every morning --at 07:00

Rich Formatting

OpenClaw uses WhatsApp's formatting:

---

Security Best Practices


security:
  rate_limit: 30          # Max messages per minute
  block_unknown: false    # Block messages from unknown numbers
  log_conversations: true # Keep logs for review

---

Troubleshooting

Messages Not Arriving

Delayed Responses

"Session Expired" (Web Bridge)

Re-scan the QR code:


openclaw connect whatsapp --provider web-bridge --re-link

Image Analysis Not Working

Ensure your model supports vision:


openclaw config set model gpt-4o  # Supports images

---

Summary

Connecting OpenClaw to WhatsApp gives you a personal AI assistant in your pocket. The WhatsApp Business API is the recommended method for reliability, while the web bridge works for quick personal setups. With voice transcription, image analysis, and scheduled messages, your WhatsApp agent becomes a powerful daily tool.

Related Articles