WhatsApp

Complete Guide to OpenClaw WhatsApp Integration

WhatsApp is the world's most popular messaging app with over 2 billion active users. With the OpenClaw WhatsApp integration, your AI assistant lives right where you already spend your time. No new apps to install, no interfaces to learn. Just message your assistant like you'd message a friend.

This comprehensive guide covers everything you need to know about setting up and using OpenClaw with WhatsApp, including two different integration methods, detailed troubleshooting, and best practices for getting the most out of your AI assistant.

Two Ways to Connect: Choose Your Path

OpenClaw supports two distinct methods for WhatsApp integration, each with its own advantages:

Method 1: wacli (Recommended for Personal Use)

The wacli method uses the WhatsApp Web protocol to connect your personal or business WhatsApp account directly to OpenClaw. This is the easiest and fastest way to get started with OpenClaw WhatsApp integration.

Advantages of wacli:

• Quick setup in under 15 minutes
• Works with any WhatsApp account (personal or business)
• No approval process or business verification required
• Free to use with no per-message costs
• Full access to all WhatsApp features including groups
• Perfect for personal assistants and small teams

How wacli works:

wacli connects to WhatsApp using the same protocol as WhatsApp Web. When you scan the QR code, you're linking OpenClaw to your WhatsApp account just like you would link a browser session. Your messages are received in real-time, processed by your AI assistant, and responses are sent back through the same connection.

The connection uses WhatsApp's end-to-end encryption, so your messages remain private. OpenClaw processes everything locally on your machine or server — nothing goes through third-party services.

Method 2: WhatsApp Business API (Official Method)

The WhatsApp Business API is Meta's official solution for businesses to integrate WhatsApp into their systems. This method requires business verification but provides an officially supported integration path.

Advantages of Business API:

• Officially supported by Meta
• Higher message limits for large-scale use
• Business profile with verified badge
• Template messages for proactive outreach
• Better suited for commercial applications
• Compliant with WhatsApp's terms of service

Business API considerations:

• Requires Meta Business verification (can take days to weeks)
• Per-conversation pricing applies
• More complex initial setup
• Needs a dedicated phone number not used elsewhere

Understanding QR Code Pairing

Both methods involve QR code pairing, but they work slightly differently:

wacli QR Code Pairing

When you start OpenClaw with the wacli integration for the first time, it generates a QR code in your terminal or logs. Here's what happens:

1. QR Code Generation: OpenClaw generates a unique QR code containing encrypted session information
2. Phone Scanning: You open WhatsApp on your phone, go to Linked Devices, and scan the QR code
3. Session Establishment: WhatsApp creates a linked session, similar to WhatsApp Web
4. Persistent Connection: The session remains active until you explicitly log out or it expires

Important notes about QR pairing:

• The QR code expires after about 60 seconds — if it times out, restart to get a new one
• You can have up to 4 linked devices per WhatsApp account
• If you log out from your phone's Linked Devices menu, OpenClaw will need to re-pair
• Session data is stored locally and persists across restarts

Business API Authentication

The Business API uses a different flow involving Meta Business Manager and API credentials rather than QR codes. You'll configure API tokens directly in your OpenClaw configuration.

Detailed Setup: wacli Method

Prerequisites

• A smartphone with WhatsApp installed and activated
• OpenClaw installed and running on macOS, Linux, or a server
• A terminal or SSH access to view the QR code
• Stable internet connection on both phone and server

Step-by-Step wacli Setup

Step 1: Configure OpenClaw

Add the WhatsApp configuration to your OpenClaw config file (usually ~/.openclaw/config.yaml):

channels:  whatsapp:    enabled: true    method: wacli    allowedUsers:      - "1234567890@s.whatsapp.net"  # Your WhatsApp number    # Optional: specific number to use as assistant    # assistantNumber: "0987654321@s.whatsapp.net"

The allowedUsers list uses the format phonenumber@s.whatsapp.net where the phone number includes the country code without the + sign.

Step 2: Start OpenClaw

Run OpenClaw in a terminal where you can see the output:

openclaw gateway start

Watch the terminal for the QR code to appear. It will display as ASCII art that your phone can scan.

Step 3: Scan the QR Code

On your phone:

1. Open WhatsApp
2. Tap the three dots menu (Android) or Settings (iOS)
3. Select "Linked Devices"
4. Tap "Link a Device"
5. Scan the QR code displayed in your terminal

Step 4: Verify Connection

Once paired, you'll see a confirmation message in the terminal. Send a test message to verify:

1. Open a chat with the WhatsApp account you paired
2. Send any message like "Hello"
3. Your AI assistant should respond

Detailed Setup: WhatsApp Business API

Prerequisites

• A Meta Business account
• A verified business (Facebook Business Verification)
• A phone number not currently used with WhatsApp
• A Business Solution Provider (BSP) or direct API access

Step-by-Step Business API Setup

Step 1: Create Meta Business Account

1. Go to business.facebook.com
2. Create a new Business account or use an existing one
3. Complete the business verification process (may require documents)

Step 2: Set Up WhatsApp Business Account

1. In Meta Business Suite, go to Business Settings
2. Find WhatsApp Accounts under Accounts
3. Add a new WhatsApp Business Account
4. Provide your business information and display name

Step 3: Register Your Phone Number

1. Add a phone number to your WhatsApp Business Account
2. Verify the number via SMS or voice call
3. Wait for Meta to approve your number (usually 24-48 hours)

Step 4: Generate API Credentials

1. Create a System User in Business Settings
2. Generate an access token with WhatsApp permissions
3. Note your Phone Number ID and WhatsApp Business Account ID

Step 5: Configure OpenClaw

Add the Business API configuration:

channels:  whatsapp:    enabled: true    method: business_api    accessToken: "your-long-lived-access-token"    phoneNumberId: "your-phone-number-id"    businessAccountId: "your-business-account-id"    webhookVerifyToken: "a-secret-string-you-create"    allowedUsers:      - "1234567890"  # Phone numbers that can interact

Step 6: Set Up Webhook

The Business API requires a webhook to receive messages:

1. OpenClaw provides a webhook endpoint at /webhooks/whatsapp
2. Configure this URL in your Meta App settings
3. Use the webhookVerifyToken you set in your config
4. Subscribe to the messages webhook field

Rate Limits and Best Practices

wacli Rate Limits

While wacli doesn't have official rate limits, WhatsApp monitors for unusual activity:

• Recommended limits: No more than 200-300 messages per day to avoid detection
• Burst sending: Avoid sending many messages in quick succession
• Group messages: Be especially careful with group messaging frequency
• Media: Large file transfers may be slower than text

Best practices for wacli:

• Add natural delays between messages (OpenClaw does this automatically)
• Don't spam groups or send unsolicited messages
• Keep your phone connected to the internet
• Monitor for any warnings from WhatsApp

Business API Rate Limits

The Business API has tiered rate limits based on your quality rating:

Best practices for Business API:

• Start with the template message for first contact (required)
• Respond within 24 hours to keep the conversation window open
• Monitor your quality rating in Meta Business Manager
• Use message templates for notifications and proactive messages

Troubleshooting Guide

Common wacli Issues

QR Code Not Appearing

• Check that OpenClaw has permission to write to the terminal
• Try running in a different terminal emulator
• Check the logs for any error messages
• Ensure no other wacli instance is running

QR Code Times Out

• QR codes expire after ~60 seconds
• Restart OpenClaw to generate a new QR code
• Have your phone ready before starting

Connection Drops Frequently

• Ensure your server has stable internet
• Check if your phone's WhatsApp is updated
• Look for "Linked Devices" errors on your phone
• Consider using a dedicated phone for better stability

"Session Logged Out" Errors

• WhatsApp may disconnect sessions for security
• Re-scan the QR code to re-establish connection
• Check if you accidentally logged out from your phone

Messages Not Sending

• Verify the recipient number format is correct
• Check your allowedUsers configuration
• Look for rate limiting warnings in logs
• Ensure the recipient hasn't blocked your number

Common Business API Issues

Webhook Not Receiving Messages

• Verify your webhook URL is publicly accessible
• Check SSL certificate is valid
• Confirm webhook verification token matches
• Review Meta's webhook delivery logs

401 Unauthorized Errors

• Access token may have expired
• Regenerate token in Meta Business Settings
• Verify token has correct permissions

Template Message Rejected

• Review template for policy violations
• Ensure template is approved before using
• Check template parameters are correctly formatted

Low Quality Rating

• Too many users blocking or reporting
• Review message content for spam-like patterns
• Reduce message frequency
• Improve message relevance

Security Considerations

End-to-End Encryption

WhatsApp uses the Signal protocol for end-to-end encryption. When using wacli:

• Messages are encrypted between your phone and contacts
• OpenClaw receives decrypted messages through the linked session
• Processing happens locally on your server
• No messages pass through Meta's servers in plaintext

Data Privacy

• All message processing happens on your OpenClaw instance
• No data is sent to third-party AI services unless you configure them
• Session credentials are stored locally
• You control data retention and deletion

Recommendations

• Use a dedicated WhatsApp number for your assistant
• Regularly review linked devices on your phone
• Keep OpenClaw and dependencies updated
• Use strong authentication for your server
• Consider VPN if connecting from restricted regions

Advanced Configuration

Multiple Account Support

You can run multiple WhatsApp accounts by using separate OpenClaw instances or configuring multiple numbers:

channels:  whatsapp:    enabled: true    method: wacli    instances:      personal:        sessionName: "personal"        allowedUsers: ["1234567890@s.whatsapp.net"]      work:        sessionName: "work"        allowedUsers: ["0987654321@s.whatsapp.net"]

Custom Response Formatting

Configure how your assistant formats responses:

channels:  whatsapp:    formatting:      maxLength: 4096  # WhatsApp's message limit      splitLongMessages: true      useMarkdown: true  # WhatsApp supports basic markdown

Voice Message Handling

OpenClaw automatically transcribes voice messages:

channels:  whatsapp:    voice:      transcribe: true      transcriptionModel: whisper      respondWithVoice: false  # Set true to reply with audio

Comparison: wacli vs Business API

Getting Help

If you encounter issues with your OpenClaw WhatsApp integration:

1. Check the logs: openclaw gateway logs
2. Review this troubleshooting guide
3. Search existing issues on GitHub
4. Join the OpenClaw community Discord for real-time help
5. Open a GitHub issue with detailed information

When reporting issues, include:

• Your OpenClaw version
• Which method you're using (wacli or Business API)
• Relevant error messages from logs
• Steps to reproduce the issue

Conclusion

The OpenClaw WhatsApp integration brings your AI assistant to the messaging app you already use daily. Whether you choose the quick wacli setup for personal use or the official Business API for commercial applications, you'll have a powerful AI assistant just a message away.

Start with wacli if you want to get running quickly, and consider migrating to the Business API if you need higher volumes or official support. Either way, you're getting the full power of OpenClaw delivered through WhatsApp's familiar interface.