WhatsApp Integration

OpenClaw integrates with WhatsApp via the WhatsApp Web protocol using the Baileys library. This allows you to send and receive messages, handle media, and manage group chats through your OpenClaw gateway.

Quick Setup

Prerequisites

A separate phone number (recommended)
WhatsApp installed on your phone
OpenClaw gateway running

Basic Configuration

Add WhatsApp to your config (~/.openclaw/openclaw.json):

{
  channels: {
    whatsapp: {
      enabled: true,
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567"]
    }
  }
}

Login and scan QR code:

openclaw channels login whatsapp

Start the gateway:

openclaw gateway

Configuration Options

Basic Settings

{
  channels: {
    whatsapp: {
      // Enable/disable WhatsApp
      enabled: true,

      // Direct message policy
      dmPolicy: "allowlist", // "allowlist", "denylist", "all"
      allowFrom: ["+15551234567", "+15559876543"],
      blockFrom: ["+15551112233"],

      // Group chat settings
      groups: {
        "*": { // All groups
          requireMention: true,
          mentionPatterns: ["@openclaw", "@ai"],
          allowedCommands: ["help", "status"]
        },
        "family-group@g.us": {
          requireMention: false,
          autoRespond: true
        }
      },

      // Message handling
      messages: {
        maxMessageLength: 4096,
        mediaEnabled: true,
        voiceTranscription: true,
        typingIndicator: true,
        readReceipts: true
      }
    }
  }
}

Advanced Settings

{
  channels: {
    whatsapp: {
      // Connection settings
      connection: {
        timeout: 60000,
        reconnectInterval: 5000,
        maxReconnectAttempts: 10,
        heartbeatInterval: 25000
      },

      // Session management
      session: {
        savePath: "~/.openclaw/sessions/whatsapp",
        autoSave: true,
        encryption: true,
        backup: true
      },

      // Media settings
      media: {
        downloadPath: "~/.openclaw/media/whatsapp",
        maxSize: "16MB",
        autoDownload: false,
        supportedTypes: ["image", "audio", "video", "document"]
      },

      // Voice message handling
      voice: {
        transcription: {
          enabled: true,
          service: "openai", // "openai", "google", "local"
          language: "en"
        },
        autoTranscribe: true
      },

      // Command permissions
      commands: {
        enabled: true,
        prefix: "/",
        allowConfigWrites: true, // Allow /config commands
        allowedCommands: [
          "help", "status", "ping", "config", "restart"
        ]
      }
    }
  }
}

Features

Direct Messages

Allowlist/Denylist: Control who can message your OpenClaw
Auto-reply: Configure automatic responses
Rich media: Send and receive images, audio, video, documents
Voice notes: Automatic transcription support

Group Chats

Mention-based activation: Only respond when mentioned
Custom mention patterns: Configure trigger words
Group-specific settings: Different behavior per group
Admin commands: Special commands for group admins

Media Handling

Automatic download: Configure auto-download settings
Size limits: Set maximum file size limits
Type filtering: Allow/block specific media types
Storage management: Automatic cleanup of old media

Usage Examples

Basic Commands

# Login to WhatsApp
openclaw channels login whatsapp

# Check WhatsApp status
openclaw channels status whatsapp

# Send a test message
openclaw message send --channel whatsapp --target +15551234567 --message "Hello from OpenClaw!"

# Send media
openclaw message send --channel whatsapp --target +15551234567 --file ./image.jpg

# View recent messages
openclaw channels logs whatsapp --limit 10

Interactive Usage

Once configured, you can interact with OpenClaw directly through WhatsApp:

You: @openclaw help
OpenClaw: Available commands:
- /help - Show this help message
- /status - Check gateway status
- /ping - Test connectivity
- /config set key=value - Update configuration

You: @openclaw Write a Python script to calculate fibonacci
OpenClaw: Here's a Python script that calculates Fibonacci numbers:

```python
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

# Test the function
for i in range(10):
    print(f"F({i}) = {fibonacci(i)}")

You: @openclaw /status OpenClaw: Gateway Status:

Status: Running
Uptime: 2h 34m
WhatsApp: Connected
Messages processed: 47
Active chats: 3

## Security Considerations

### Phone Number Privacy
- **Use a separate number**: Recommended for privacy
- **Number masking**: OpenClaw doesn't expose your number to agents
- **Contact filtering**: Strict allowlist for direct messages

### Session Security
- **Encrypted sessions**: WhatsApp sessions are encrypted
- **Local storage**: Sessions stored locally on your machine
- **Backup encryption**: Session backups are encrypted

### Content Security
- **Media scanning**: Optional virus scanning for received media
- **Link filtering**: Block malicious links
- **Content moderation**: Filter inappropriate content

## Troubleshooting

### Common Issues

**QR Code Not Appearing**
```bash
# Check if WhatsApp is already active elsewhere
openclaw channels status whatsapp

# Force re-login
openclaw channels logout whatsapp
openclaw channels login whatsapp

Connection Drops

# Check network connectivity
ping web.whatsapp.com

# Check gateway logs
openclaw gateway logs --filter whatsapp

# Test connection
openclaw channels test whatsapp

Messages Not Sending

# Check rate limits
openclaw channels status whatsapp

# Verify recipient number
openclaw message validate --channel whatsapp --target +15551234567

# Check message queue
openclaw gateway queue --channel whatsapp

Media Download Issues

# Check media directory permissions
ls -la ~/.openclaw/media/whatsapp/

# Clear media cache
openclaw channels clear-cache whatsapp --media

# Test media download
openclaw channels test whatsapp --media

Debug Mode

Enable detailed logging for WhatsApp:

# Enable debug logging
openclaw config set logging.components.whatsapp debug

# Restart gateway with debug
openclaw gateway restart --debug

# View WhatsApp logs
openclaw gateway logs --follow --filter whatsapp

Advanced Features

Multi-Account Support

Configure multiple WhatsApp accounts:

{
  channels: {
    whatsapp: {
      accounts: {
        personal: {
          phoneNumber: "+15551234567",
          allowFrom: ["family", "friends"]
        },
        business: {
          phoneNumber: "+15559876543",
          allowFrom: ["customers", "team"]
        }
      }
    }
  }
}

Custom Handlers

Create custom message handlers:

module.exports = {
  onMessage: async (message, context) => {
    if (message.type === 'image') {
      // Custom image processing
      await processImage(message);
    }
  },

  onCommand: async (command, args, context) => {
    if (command === 'custom') {
      return "Custom command response";
    }
  }
};

Webhook Integration

Configure webhooks for external processing:

{
  channels: {
    whatsapp: {
      webhooks: {
        onMessage: {
          url: "https://your-api.com/webhook/whatsapp",
          secret: "webhook-secret",
          timeout: 5000
        },
        onStatus: {
          url: "https://your-api.com/webhook/status",
          events: ["connected", "disconnected", "error"]
        }
      }
    }
  }
}

Best Practices

Number Management
- Use a dedicated number for OpenClaw
- Keep personal and business separate
- Regular backup of contacts
Message Handling
- Set appropriate rate limits
- Use mention-based activation in groups
- Configure proper content filtering
Security
- Enable session encryption
- Use strong allowlist policies
- Regular security audits
Performance
- Monitor message queue size
- Optimize media handling
- Regular cleanup of old sessions

API Reference

Channel Commands

# Channel management
openclaw channels login whatsapp [--account name]
openclaw channels logout whatsapp [--account name]
openclaw channels status whatsapp [--detailed]

# Message operations
openclaw message send --channel whatsapp --target number --message text
openclaw message send --channel whatsapp --target number --file path
openclaw message history --channel whatsapp --target number --limit 50

# Configuration
openclaw config set channels.whatsapp.allowFrom '["+15551234567"]'
openclaw config get channels.whatsapp
openclaw config unset channels.whatsapp.blockFrom

Configuration Schema

interface WhatsAppConfig {
  enabled: boolean;
  dmPolicy: "allowlist" | "denylist" | "all";
  allowFrom?: string[];
  blockFrom?: string[];
  groups?: {
    [groupId: string]: {
      requireMention?: boolean;
      mentionPatterns?: string[];
      allowedCommands?: string[];
      autoRespond?: boolean;
    };
  };
  messages?: {
    maxMessageLength?: number;
    mediaEnabled?: boolean;
    voiceTranscription?: boolean;
    typingIndicator?: boolean;
    readReceipts?: boolean;
  };
  connection?: {
    timeout?: number;
    reconnectInterval?: number;
    maxReconnectAttempts?: number;
    heartbeatInterval?: number;
  };
  session?: {
    savePath?: string;
    autoSave?: boolean;
    encryption?: boolean;
    backup?: boolean;
  };
  media?: {
    downloadPath?: string;
    maxSize?: string;
    autoDownload?: boolean;
    supportedTypes?: string[];
  };
}

Your WhatsApp integration is now ready! You can start receiving and sending messages through OpenClaw. 📱