OpenClaw WhatsApp Integration: Build an AI Agent for WhatsApp

Meta Business Account

Create one at business.facebook.com. This is your organization-level account that owns the WhatsApp Business API access. You do not need a Facebook page, but you do need to verify your business with Meta (usually takes 1-3 business days).

A Phone Number

You need a phone number that is not currently registered on WhatsApp or WhatsApp Business app. Meta provides a free test number during development, but for production you need your own number. A virtual number from Twilio, MessageBird, or similar providers works fine.

OpenClaw Installed

You need OpenClaw installed locally or on a server. The gateway must be running and accessible. If you have not installed OpenClaw yet, follow the OpenClaw Setup Guide first.

A Public URL or Tunnel

WhatsApp sends webhook events to your server. Meta needs a publicly accessible HTTPS URL. For local development, use ngrok or Cloudflare Tunnel. For production, your server needs a domain with SSL.

1.1 Create a Meta App

Go to developers.facebook.com/apps. Click "Create App." Select "Business" as the app type. Give it a name like "OpenClaw WhatsApp Agent" and link it to your Meta Business Account.

1.2 Add WhatsApp Product

In your app dashboard, find "Add Products to Your App" and click "Set Up" on the WhatsApp card. This gives you access to the WhatsApp Business API, a test phone number, and the API playground for sending test messages.

1.3 Generate a Permanent Access Token

The temporary token from the API playground expires in 24 hours. For production, you need a permanent token. Go to Business Settings > System Users. Create a system user, assign it admin access to your WhatsApp Business Account, and generate a token with the whatsapp_business_messaging and whatsapp_business_management permissions.

5.1 Navigate to Webhook Settings

In the Meta Developer Portal, go to your app > WhatsApp > Configuration. Find the "Webhook" section and click "Edit."

5.2 Enter Callback URL and Verify Token

Callback URL: https://your-domain.com/webhook/whatsapp. Verify Token: the same string you set in channels.whatsapp.verifyToken. Click "Verify and Save." Meta sends a GET request to your URL with the verify token. The OpenClaw gateway responds automatically.

5.3 Subscribe to Webhook Fields

After verification, you need to subscribe to the messages field. This tells Meta to send incoming message events to your webhook. Without this subscription, your webhook is verified but receives no messages. Also subscribe to message_deliveries and message_reads if you want delivery and read receipt tracking.

6.1 Send a Test Message

Open WhatsApp on your phone. Send a message to your WhatsApp Business API number (or the test number from Meta). You should see the message appear in the OpenClaw gateway logs within 1-2 seconds.

6.2 Check Gateway Logs

# Watch logs in real-time
openclaw gateway logs --follow | grep whatsapp

# You should see:
# [channel:whatsapp] message received from +1234567890: "Hi there"
# [agent] generating response...
# [channel:whatsapp] response sent to +1234567890 (247 chars, 1.3s)

6.3 Verify the Response in WhatsApp

Check your WhatsApp app. The agent's response should appear as a reply. If you enabled sendTypingIndicator, you will see the typing dots before the response arrives. Test multiple scenarios from your SOUL.md to make sure the agent handles different types of questions correctly.

6.4 Test Edge Cases

Send an image, a voice note, a location, and a contact card. Verify that the agent either handles them or responds with a helpful fallback message. Test rapid consecutive messages to check that the agent processes them in order and does not send overlapping responses.

Customer Support

Handle the 80% of support questions that have standard answers: business hours, return policies, shipping status, pricing, account issues. The agent resolves these instantly without a human touching the ticket. Complex issues get escalated to a human agent with the full conversation context.

# Example SOUL.md snippet for support
## Escalation Rules
escalate_to_human:
  - payment disputes over $100
  - legal or compliance questions
  - customer explicitly requests human
  - three failed resolution attempts

escalation_message: |
  I want to make sure you get the best help.
  Let me connect you with a team member who
  can assist further. One moment please.

Appointment Booking

Clinics, salons, repair shops, and consultants can let customers book appointments directly through WhatsApp. The agent checks availability, confirms the booking, and sends a reminder 24 hours before. No app download, no website visit, no phone call required.

# Example SOUL.md snippet for booking
## Booking Flow
1. Customer sends: "I want to book an appointment"
2. Ask: service type, preferred date, preferred time
3. Check calendar API for availability
4. Confirm slot: "*Tuesday, March 15 at 2:00 PM*"
5. Send confirmation with calendar link

## Skills
- calendar_check: GET /api/availability?date={date}
- calendar_book: POST /api/appointments
- send_reminder: scheduled 24h before appointment

Order Tracking

E-commerce businesses can let customers check order status by sending their order number on WhatsApp. The agent queries the order management system, returns the current status, expected delivery date, and tracking link. Proactive notifications can be sent when the order ships or is out for delivery.

# Example SOUL.md snippet for order tracking
## Order Lookup
When customer provides order number (format: ORD-XXXXX):
1. Query: GET /api/orders/{order_id}
2. Return: status, items, tracking URL, ETA
3. If delayed: apologize, provide updated ETA

## Proactive Notifications (via templates)
- order_shipped: "Your order {order_id} has shipped! Track: {url}"
- out_for_delivery: "Your order is out for delivery today."
- delivered: "Your order was delivered. How was everything?"

Webhook Verification Fails

Meta sends a GET request with a hub.verify_token parameter. If it does not match your configured channels.whatsapp.verifyToken, verification fails.

# Check your configured verify token
openclaw config get channels.whatsapp.verifyToken

# Make sure it matches exactly what you entered in Meta Portal
# No trailing spaces, no quotes wrapping the value

# Test locally with curl:
curl "http://localhost:18789/webhook/whatsapp?hub.mode=subscribe&hub.verify_token=my-openclaw-webhook-secret&hub.challenge=test123"

# Should return: test123

Messages Received but No Response Sent

The webhook receives the message (you see it in logs) but the agent does not respond. Common causes: the access token expired (if using a temporary token), the phone number ID is wrong, or the agent is throwing an error during processing.

# Check for errors in the full logs
openclaw gateway logs --lines 50

# Test sending a message directly via API
curl -X POST "https://graph.facebook.com/v21.0/YOUR_PHONE_ID/messages" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"messaging_product":"whatsapp","to":"YOUR_NUMBER","type":"text","text":{"body":"Test"}}'

# If this fails with 401: your token is expired or invalid
# If this fails with 400: check the phone number format (include country code, no +)

24-Hour Window Expired

If a customer has not messaged in 24 hours, you cannot send free-form messages. You will see a 400 error with "outside allowed window." Use pre-approved message templates instead.

# Configure message templates in OpenClaw
openclaw config set channels.whatsapp.templates '{
  "follow_up": {
    "name": "customer_followup",
    "language": "en",
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "{{customer_name}}" }
        ]
      }
    ]
  }
}'

# Templates must be pre-approved in Meta Business Manager
# Go to: WhatsApp Manager > Message Templates > Create Template
# Approval usually takes 1-24 hours

Rate Limiting (Error 429 or 131056)

WhatsApp has tiered rate limits based on your phone number quality rating and messaging tier. New numbers start at Tier 1 (1,000 unique customers per 24 hours). If you hit the limit, messages return error code 131056. Increase your tier by maintaining a high quality rating over time. In OpenClaw, set channels.whatsapp.rateLimitDelay 1000 to add a 1-second delay between outgoing messages and avoid bursting.