WhatsApp Channel Setup

Set up WhatsApp to interact with OpenClaw via WhatsApp messages.

WhatsApp uses web login (like WhatsApp Web) - no API keys or business account needed!

Prerequisites

A phone number with WhatsApp installed
Recommended: Use a dedicated phone/number for OpenClaw
Alternative: Use your personal number (requires selfChatMode)

Add WhatsApp Configuration

Update ~/.openclaw/openclaw.json:

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "dmPolicy": "allowlist",
      "allowFrom": ["+1234567890"],
      "sendReadReceipts": true,
      "mediaMaxMb": 16,
      "debounceMs": 1000
    }
  },
  "plugins": {
    "entries": {
      "whatsapp": {
        "enabled": true
      }
    }
  }
}

CRITICAL: Replace +1234567890 with your WhatsApp phone number in E.164 format (e.g., +919047527108).

Format: +[country code][number] (no spaces, dashes, or parentheses)

cd /path/to/aiq-openclaw
pnpm openclaw channels login

Scan QR code with your phone:

Open WhatsApp → Settings → Linked Devices
Tap Link a Device
Scan the QR code from terminal
Wait for "Connected successfully"

Verify Connection

pnpm openclaw channels status --probe

Expected output:

WhatsApp default: enabled, configured, linked, running, connected

Configuration Options

Field	Description	Default
`dmPolicy`	Access control: `allowlist`, `pairing`, `open`, `disabled`	`pairing`
`allowFrom`	Phone numbers in E.164 format (e.g., `+1234567890`)	`[]`
`sendReadReceipts`	Send blue checkmarks when messages are read	`true`
`mediaMaxMb`	Max file size for images/videos/documents	`16`
`debounceMs`	Delay between processing messages	`1000`
`selfChatMode`	Enable if using your personal number	`false`

Using Your Personal Number

If testing with your own WhatsApp:

{
  "channels": {
    "whatsapp": {
      "selfChatMode": true,
      "dmPolicy": "allowlist",
      "allowFrom": ["+1234567890"],
      "sendReadReceipts": false
    }
  }
}

Then message yourself in WhatsApp ("Message Yourself" feature).

Phone Number Format

WhatsApp phone numbers must use E.164 format:

Correct:

"+919047527108"
"+14155551234"
"+442071234567"

❌ Wrong:

"9047527108" - Missing country code and +
"91-904-752-7108" - Has dashes
"+91 9047527108" - Has spaces
"(91) 904-752-7108" - Has parentheses and dashes

Format: +[country code][number] (no spaces, dashes, or parentheses)

WhatsApp Credentials

Credentials are stored at:

~/.openclaw/credentials/whatsapp/default/creds.json

Logout

pnpm openclaw channels logout

pnpm openclaw channels login

Test WhatsApp

Send Test Message

Open WhatsApp on your phone
Find the number you linked to OpenClaw
Send a message: Hello ArmorIQ!
Bot should respond (if your number is in allowFrom)

Using Self Chat Mode

If using your personal number with selfChatMode: true:

Open WhatsApp
Tap compose → Search for your own name
Use "Message Yourself"
Send test message

Troubleshooting

WhatsApp not connecting

Check:

Completed QR code login: pnpm openclaw channels login
WhatsApp plugin enabled in plugins.entries.whatsapp.enabled
Phone number in allowFrom uses E.164 format
For personal number, added "selfChatMode": true
Credentials exist: ls ~/.openclaw/credentials/whatsapp/default/

Solution:

# Re-login
pnpm openclaw channels logout
pnpm openclaw channels login

# Check credentials
ls ~/.openclaw/credentials/whatsapp/default/

Bot responding to everyone

CRITICAL SECURITY ISSUE: Your config has "dmPolicy": "open" with "allowFrom": ["*"]"

Fix immediately:

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+YOUR_PHONE_NUMBER"]
    }
  }
}

Then restart gateway.

Phone number format error

Error: Invalid phone number format

Fix:

Use E.164 format: +[country][number]
No spaces, dashes, or parentheses
Must start with +

QR code expired

If QR code expires during login:

Run pnpm openclaw channels login again
Scan the new QR code quickly
Ensure phone has internet connection

Connection lost

If WhatsApp disconnects:

Check phone has WhatsApp open occasionally
Don't log out from the phone
Re-login if needed: pnpm openclaw channels login

Security Best Practices

Never Use Open Policy with Wildcards

❌ DANGEROUS - Gives anyone who messages you full system access:

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "open",
      "allowFrom": ["*"]    // NEVER DO THIS!
    }
  }
}

SAFE - Only specific numbers can interact:

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+1234567890"]    // Your number only
    }
  }
}

Use Dedicated Phone Number

Recommended setup:

Use a separate phone/SIM for OpenClaw
Keep it secure and don't share the number
Use business WhatsApp account for production

Testing Safely

When testing:

Use "allowlist" with only your number
Test from your own devices
Never share your WhatsApp number publicly with open policy
Use "pairing" mode if you need to approve new users dynamically

Rate Limits

WhatsApp has sending limits:

Don't spam messages
Respect rate limits
Monitor for connection quality

OpenClaw handles basic throttling automatically.

Next Steps

WhatsApp configured!

Configure additional channels:

WhatsApp Setup