Complete WhatsApp AI Bot Setup Tutorial

Target keywords: WhatsApp bot tutorial, WhatsApp automation, OpenClaw WhatsApp, AI WhatsApp bot

Introduction

This tutorial will walk you through building a full-featured WhatsApp AI bot from scratch using OpenClaw. No programming experience is required, and you can complete it in about 30 minutes.

What you will learn:

How to apply for the WhatsApp Business API
OpenClaw configuration
AI Agent creation
Automated message handling

Estimated time: 30-45 minutes
Difficulty: Beginner

Prerequisites

What You Need

A WhatsApp Business account
- A phone number not linked to personal WhatsApp
- A business Facebook account
A server/host
- A publicly accessible server (VPS or cloud host)
- A domain name (for the webhook)
- An SSL certificate (Let's Encrypt is free)
An OpenClaw environment
- OpenClaw already installed (installation guide)
- A basic configuration file

Step 1: Apply for the WhatsApp Business API

1.1 Create a Meta Developer Account

Visit developers.facebook.com
Log in with your Facebook account
Complete developer registration

1.2 Create an App

Click "Create App"
Choose the "Business" type
Enter an app name, such as "MyWhatsAppBot"
Link a Business Account

1.3 Add the WhatsApp Product

Find "Add Product" in the app dashboard
Select "WhatsApp"
Click "Set Up"

1.4 Get API Credentials

After creating the app, you will see:

Phone Number ID: 123456789012345
WhatsApp Business Account ID: 123456789012345

Important: Save these IDs. You will need them later.

1.5 Generate an Access Token

Go to "Getting Started"
Click "Add phone number" (to use a test number)
Or add a real business number
Generate a Permanent Access Token:
- Go to Business Settings
- System Users → Add
- Generate a token and select WhatsApp Business Management

Save the token: EAAxxxxxxxx...

Step 2: Configure OpenClaw

2.1 Install the WhatsApp Skill

# Install the official WhatsApp skill
openclaw skill install whatsapp

# Verify the installation
openclaw skill list | grep whatsapp

2.2 Configure the WhatsApp Connection

Edit the OpenClaw config file:

openclaw config edit

Add the WhatsApp configuration:

# ~/.openclaw/config.yaml
skills:
  whatsapp:
    enabled: true
    provider: meta
    config:
      phone_number_id: "123456789012345"  # Your Phone Number ID
      business_account_id: "123456789012345"  # Your Business Account ID
      access_token: "${WHATSAPP_TOKEN}"  # Environment variable
      webhook_verify_token: "your_random_string"  # Custom verification string
      
    webhook:
      path: "/webhook/whatsapp"
      port: 8080

2.3 Set Environment Variables

# Add to `~/.bashrc` or `~/.zshrc`
export WHATSAPP_TOKEN="EAAxxxxxxxx..."

# Reload the configuration
source ~/.bashrc

2.4 Configure the Webhook URL

In the Meta developer console:

Go to WhatsApp → Configuration
Edit the Webhook
Enter:
- Callback URL: https://your-domain.com/webhook/whatsapp
- Verify Token: your_random_string (must match the config)
Click "Verify and Save"
Subscribe to these fields:
- ✅ messages
- ✅ message_deliveries
- ✅ message_reads

Step 3: Create an AI Agent

3.1 Basic Agent Configuration

# Create a new agent
openclaw agent create whatsapp-assistant

Edit the agent configuration:

openclaw agent edit whatsapp-assistant

Add this configuration:

# ~/.openclaw/agents/whatsapp-assistant.yaml
agent:
  name: "WhatsApp Assistant"
  description: "AI assistant for WhatsApp"
  
  model:
    provider: openai
    model: gpt-4o-mini
    api_key: "${OPENAI_API_KEY}"
    temperature: 0.7
    
  system_prompt: |
    You are a helpful WhatsApp assistant. Keep responses:
    - Concise (under 200 words)
    - Friendly and conversational
    - Formatted for mobile reading
    
    If you don't know something, say so honestly.
    
  memory:
    enabled: true
    max_messages: 10
    
  tools:
    - name: get_weather
      description: "Get weather for a location"
    - name: search_web
      description: "Search the web for information"

3.2 Connect WhatsApp to the Agent

Edit the main OpenClaw config:

# ~/.openclaw/config.yaml
routes:
  whatsapp:
    - pattern: "*"  # Match all messages
      agent: whatsapp-assistant
      # Optional: route by condition
      # condition: "message.text.startswith('/ai')"

Step 4: Start and Test

4.1 Start OpenClaw

# Run in the foreground (testing)
openclaw start

# You should see:
# ✓ WhatsApp skill loaded
# ✓ Webhook server started on :8080
# ✓ Agent 'whatsapp-assistant' ready

4.2 Test the Connection

Method 1: Use Meta's testing tools

Go to the Meta developer console
WhatsApp → API Setup
Send a test message
Check the OpenClaw logs

Method 2: Test with a real number

Send a message to your WhatsApp Business number
Check whether you receive an AI reply

4.3 View Logs

# View live logs
openclaw logs -f

# Or view the file
tail -f ~/.openclaw/logs/openclaw.log

Step 5: Advanced Features

5.1 Add Custom Tools

Create a weather lookup tool:

# ~/.openclaw/skills/weather.py
import requests
from openclaw import tool

@tool
def get_weather(location: str) -> str:
    """Get current weather for a location"""
    api_key = "${WEATHER_API_KEY}"
    url = f"https://api.weather.com/v1/current?location={location}&apiKey={api_key}"
    
    response = requests.get(url)
    data = response.json()
    
    return f"Weather in {location}: {data['temperature']}°C, {data['condition']}"

5.2 Message Templates

For notification-style messages, use WhatsApp templates:

# Add to the agent configuration
templates:
  welcome:
    name: "welcome_message"
    language: "zh_CN"
    components:
      - type: "body"
        parameters:
          - type: "text"
            text: "{{user_name}}"

5.3 Group Chat Support

routes:
  whatsapp:
    - pattern: "*"
      agent: whatsapp-assistant
      options:
        group_chat: true
        mention_only: true  # Reply only when mentioned

Step 6: Production Deployment

6.1 Use systemd (Linux)

# Create the service file
sudo tee /etc/systemd/system/openclaw-whatsapp.service > /dev/null <<EOF
[Unit]
Description=OpenClaw WhatsApp Bot
After=network.target

[Service]
Type=simple
User=openclaw
WorkingDirectory=/home/openclaw
ExecStart=/home/openclaw/.openclaw/bin/openclaw start
Restart=always
RestartSec=10
Environment=WHATSAPP_TOKEN=${WHATSAPP_TOKEN}
Environment=OPENAI_API_KEY=${OPENAI_API_KEY}

[Install]
WantedBy=multi-user.target
EOF

# Enable the service
sudo systemctl daemon-reload
sudo systemctl enable openclaw-whatsapp
sudo systemctl start openclaw-whatsapp

6.2 Use Docker

# docker-compose.yml
version: '3.8'

services:
  openclaw:
    image: openclaw/openclaw:latest
    ports:
      - "8080:8080"
    environment:
      - WHATSAPP_TOKEN=${WHATSAPP_TOKEN}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    volumes:
      - ./config:/root/.openclaw
    restart: unless-stopped

6.3 Use Nginx as a Reverse Proxy

# /etc/nginx/sites-available/whatsapp-bot
server {
    listen 443 ssl http2;
    server_name bot.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;

    location /webhook/whatsapp {
        proxy_pass http://localhost:8080;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Troubleshooting

Issue 1: Webhook verification failed

Symptom: Meta shows "Unable to verify"

Fix:

# 1. Check that the URL is reachable
curl https://your-domain.com/webhook/whatsapp

# 2. Confirm `verify_token` matches
# 3. Check the firewall/security group
# 4. Make sure the SSL certificate is valid

Issue 2: Messages are not delivered

Symptom: Users do not receive replies

Fix:

# 1. Check logs
openclaw logs | grep -i error

# 2. Confirm the agent is running normally
openclaw agent status whatsapp-assistant

# 3. Check the API quota
# Meta Developer Dashboard > Usage

Issue 3: Responses are too slow

Symptom: Reply latency is greater than 5 seconds

Fix:

# Enable streaming responses
agent:
  model:
    stream: true  # Display the reply token by token
    
# Or use a faster model
    model: gpt-4o-mini  # 3x faster than gpt-4o

Issue 4: 24-hour limit

Symptom: Messages cannot be sent

Cause: The WhatsApp Business API has a 24-hour session window

Fix:

Use message templates (Template Messages)
Wait for the user to send a message first

Best Practices

1. Security

✅ Use environment variables to store secrets
✅ Enable HTTPS
✅ Verify webhook signatures
✅ Restrict IP access

2. Performance

✅ Use streaming responses
✅ Enable caching
✅ Monitor API quotas
✅ Set up retry mechanisms

3. User Experience

✅ Set a welcome message
✅ Provide a /help command
✅ Handle errors gracefully
✅ Limit reply length

Extensions

Add More Platforms

The same agent can serve multiple platforms at the same time:

routes:
  whatsapp:
    - pattern: "*"
      agent: whatsapp-assistant
  telegram:
    - pattern: "*"
      agent: whatsapp-assistant
  discord:
    - pattern: "*"
      agent: whatsapp-assistant

Multilingual Support

agent:
  system_prompt: |
    Detect the user's language and respond in the same language.
    Supported: English, 中文, Español, Français

User Management

# Add a user database
from openclaw import memory

@tool
def get_user_profile(phone_number: str):
    """Get user preferences"""
    return memory.get(f"user:{phone_number}")

Next Steps

Now that you have a working WhatsApp AI bot, you can:

Resources

Get Help

Running into issues?

📧 Email: support@howtoclaw.xyz
💬 Discord: Join the community
🐛 GitHub: Open an Issue

Get more tutorials for free:

[Email subscription form]

Get OpenClaw tips, tutorials, and case studies every week.

Last updated: March 2026

WhatsApp Bot Tutorial

Complete WhatsApp AI Bot Setup Tutorial

Introduction

Prerequisites

What You Need

Step 1: Apply for the WhatsApp Business API

1.1 Create a Meta Developer Account

1.2 Create an App

1.3 Add the WhatsApp Product

1.4 Get API Credentials

1.5 Generate an Access Token

Step 2: Configure OpenClaw

2.1 Install the WhatsApp Skill

2.2 Configure the WhatsApp Connection

2.3 Set Environment Variables

2.4 Configure the Webhook URL

Step 3: Create an AI Agent

3.1 Basic Agent Configuration

3.2 Connect WhatsApp to the Agent

Step 4: Start and Test

4.1 Start OpenClaw

4.2 Test the Connection

4.3 View Logs

Step 5: Advanced Features

5.1 Add Custom Tools

5.2 Message Templates

5.3 Group Chat Support

Step 6: Production Deployment

6.1 Use systemd (Linux)

6.2 Use Docker

6.3 Use Nginx as a Reverse Proxy

Troubleshooting

Issue 1: Webhook verification failed

Issue 2: Messages are not delivered

Issue 3: Responses are too slow

Issue 4: 24-hour limit

Best Practices

1. Security

2. Performance

3. User Experience

Extensions

Add More Platforms

Multilingual Support

User Management

Next Steps

Resources

Get Help