Skip to main content

WhatsApp Setup

WhatsApp is the most popular way to interact with your ClawBook AI assistant. This guide covers connecting your personal WhatsApp account using WhatsApp Web's multi-device feature.

How It Works​

OpenClaw connects to WhatsApp using Baileys, an open-source library that implements the WhatsApp Web protocol. When you link your account, ClawBook acts as another "linked device" alongside your phone—just like using WhatsApp Web on your computer.

Your phone doesn't need to stay online 24/7 thanks to WhatsApp's multi-device architecture. Once paired, your ClawBook instance maintains its own connection to WhatsApp's servers.

Prerequisites​

Before you begin, make sure you have:

  • An active ClawBook subscription with a configured LLM provider
  • WhatsApp installed on your smartphone
  • Available linked device slot (WhatsApp allows 4 linked devices max)
Node.js Required

WhatsApp integration has known issues with Bun. ClawBook instances are pre-configured to use Node.js for the Gateway, which ensures reliable WhatsApp connections. Don't switch to Bun if you're using WhatsApp.

Quick Setup​

Step 1: Start the Pairing Process​

You can pair WhatsApp via the web dashboard or command line.

Via Dashboard:

  1. Open your ClawBook dashboard at http://YOUR_IP:18789
  2. Navigate to Channels → WhatsApp
  3. Click Link Device

Via Command Line (SSH):

openclaw channels login

A QR code will appear. It expires in about 60 seconds, so have your phone ready.

Step 2: Scan the QR Code​

On your smartphone:

  1. Open WhatsApp
  2. Tap the three-dot menu (Android) or Settings (iOS)
  3. Select Linked Devices
  4. Tap Link a Device
  5. Point your camera at the QR code

Your phone's camera will automatically detect and scan the code.

Step 3: Verify the Connection​

Once paired, verify the connection:

openclaw status --deep

You should see:

Channels:
  whatsapp: connected
    Account: +1-555-123-4567
    Session: active
    Last ping: 2s ago

Step 4: Test with a Message​

Send yourself a WhatsApp message or message from another phone. Your AI assistant should respond within a few seconds.

If you don't get a response, check that:

  • Your LLM provider is configured and has credits
  • The sender has been approved via pairing (see security section below)

Security: The Pairing System​

By default, OpenClaw doesn't respond to just anyone who messages you. There's a security feature called pairing that prevents unauthorized users from consuming your LLM API credits.

How Pairing Works​

  1. Someone sends you a WhatsApp message
  2. OpenClaw responds with a short pairing code (e.g., ABC123)
  3. You must approve this code before OpenClaw will respond to that person
  4. Once approved, they can chat freely

Managing Pairings​

View pending pairing requests:

openclaw pairing list whatsapp

Output:

Pending pairings (WhatsApp):
  ABC123  +1-555-987-6543  requested 5 minutes ago
  XYZ789  +1-555-111-2222  requested 12 minutes ago

Approve a pairing:

openclaw pairing approve whatsapp ABC123

View approved contacts:

openclaw pairing list whatsapp --approved

Changing the Default Policy​

You can adjust who can message your bot without approval:

# View current policy
openclaw config get channels.whatsapp.dmPolicy

# Options:
# "pairing" (default) - Require approval for unknown senders
# "allowlist" - Only allow pre-approved numbers
# "open" - Allow anyone (not recommended unless you have rate limits)
openclaw config set channels.whatsapp.dmPolicy "pairing"

Group Chat Configuration​

OpenClaw can respond in WhatsApp groups, but it requires careful configuration to avoid annoying group members.

Default Behavior​

By default, OpenClaw only responds in groups when mentioned. This prevents it from jumping into every conversation.

Configuring Group Behavior​

# Require @mention in all groups (default, recommended)
openclaw config set channels.whatsapp.groups.*.requireMention true

# Respond to all messages in a specific group
openclaw config set channels.whatsapp.groups.GROUP_ID.requireMention false

Finding Group IDs​

Group IDs appear in the logs when someone messages in a group:

openclaw logs | grep "group"

Reconnection and Session Management​

Automatic Reconnection​

The Gateway automatically attempts to reconnect if the WhatsApp connection drops. You'll see logs like:

[whatsapp] Connection lost, reconnecting...
[whatsapp] Reconnected successfully

Manual Reconnection​

If automatic reconnection fails:

# Logout and re-login
openclaw channels logout whatsapp
openclaw channels login

# Then scan the QR code again

Session Storage​

Your WhatsApp session credentials are stored at:

~/.openclaw/credentials/whatsapp/<accountId>/creds.json

This file is sensitive—it allows access to your WhatsApp account. ClawBook backups include this file (encrypted).

Troubleshooting​

QR Code Expired​

WhatsApp QR codes expire after approximately 60 seconds. Run openclaw channels login again to generate a fresh one.

"Phone Not Connected" or "Logged Out"​

This usually happens when:

  • You logged out from your phone's Linked Devices
  • WhatsApp detected unusual activity and terminated the session
  • There was a prolonged network outage

Solution: Re-scan the QR code to re-establish the connection.

Messages Not Being Received​

  1. Check Gateway is running:

    openclaw gateway status

  2. Check WhatsApp connection:

    openclaw status --deep | grep whatsapp

  3. Check for errors in logs:

    openclaw logs --limit 100 | grep -i "whatsapp\|error"

High Latency or Slow Responses​

WhatsApp message delivery is usually instant, but responses depend on your LLM provider's API latency. If responses feel slow:

  • Switch to a faster model (Claude Haiku instead of Opus)
  • Check your server's network latency to the LLM API
  • Verify there's no rate limiting

"Disconnected (1008): pairing required"​

This error means your session was invalidated. Common causes:

  • You removed ClawBook from Linked Devices on your phone
  • WhatsApp's servers invalidated the session
  • You exceeded the 4 device limit and an old device was kicked

Solution: Run openclaw channels login and scan a new QR code.

Best Practices​

For Personal Use​

  • Keep pairing mode enabled to control who can use your AI
  • Set reasonable rate limits to protect your API budget
  • Use a dedicated phone number if you want complete separation

For Teams or Multiple Users​

  • Consider WhatsApp Business API for higher volume
  • Create allowlists of approved numbers
  • Set up different agents for different use cases

Privacy Considerations​

  • Messages are decrypted on your ClawBook server for AI processing
  • Conversation history is stored locally (configurable retention)
  • Your LLM provider receives message content for processing
  • ClawBook staff cannot access your messages—only you have server access

WhatsApp Business API (Advanced)​

For business use cases requiring higher message volumes, verified business profiles, or message templates, you'll need the official WhatsApp Business API.

This requires:

  • Meta Business Manager account
  • Business verification
  • Phone Number ID and Access Token
  • Webhook configuration

Contact support@clawbook.io if you need help setting up WhatsApp Business API integration.