Clawdbot WhatsApp Integration

Clawdbot WhatsApp Integration Overview

Clawdbot WhatsApp integration enables you to connect your personal AI assistant directly to WhatsApp, the world's most popular messaging platform. Clawdbot uses WhatsApp Web via Baileys, with the Gateway owning the session. This allows you to automate conversations, receive intelligent responses, and manage your WhatsApp messages through AI-powered automation.

Why Use Clawdbot with WhatsApp?

WhatsApp is used by over 2 billion people worldwide. By integrating Clawdbot with WhatsApp, you unlock powerful AI capabilities:

Quick Setup (Beginner)

1. Use a separate phone number if possible (recommended)
2. Configure WhatsApp in ~/.clawdbot/clawdbot.json
3. Run clawdbot channels login to scan the QR code (Linked Devices)
4. Start the gateway

Minimal config:

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

Getting a Phone Number

WhatsApp requires a real mobile number for verification. VoIP and virtual numbers are usually blocked. There are two supported ways to run Clawdbot on WhatsApp:

Dedicated Number (Recommended)

Use a separate phone number for Clawdbot WhatsApp. This provides the best UX with clean routing and no self-chat quirks.

Ideal setup: spare/old Android phone + eSIM. Leave it on Wi-Fi and power, and link it via QR.

WhatsApp Business tip: You can use WhatsApp Business on the same device with a different number to keep your personal WhatsApp separate.

Sample config (dedicated number, single-user allowlist):

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

Personal Number (Fallback)

Quick fallback: run Clawdbot on your own number. Message yourself (WhatsApp "Message yourself") for testing.

Sample config (personal number, self-chat):

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

Number Sourcing Tips

• Local eSIM from your country's mobile carrier (most reliable)
• Prepaid SIM — cheap, just needs to receive one SMS for verification
• Avoid: TextNow, Google Voice, most "free SMS" services — WhatsApp blocks these aggressively

Tip: The number only needs to receive one verification SMS. After that, WhatsApp Web sessions persist via creds.json.

Setting Up Clawdbot WhatsApp

Prerequisites

Before connecting Clawdbot to WhatsApp, ensure you have:

• Clawdbot installed on your device
• A WhatsApp account with an active phone number
• Node.js 22 or higher

Step 1: Configure WhatsApp Channel

Add WhatsApp configuration to your ~/.clawdbot/clawdbot.json:

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

Step 2: Login with QR Code

Run the Clawdbot WhatsApp login command:

clawdbot channels login

Open WhatsApp on your phone, go to Settings > Linked Devices > Link a Device, and scan the QR code displayed by Clawdbot.

For multi-account login:

clawdbot channels login --account <id>

Step 3: Start the Gateway

clawdbot gateway --port 18789

Step 4: Verify Connection

Confirm your Clawdbot WhatsApp integration is working:

clawdbot channels status whatsapp

Clawdbot WhatsApp Features

Intelligent Message Handling

Clawdbot WhatsApp processes incoming messages and generates contextual responses. The AI understands conversation history and provides relevant answers. The model sees enough context to understand quoted replies.

DM Policy Options

Group Message Support

Clawdbot WhatsApp supports group conversations. Direct chats use the agent's main session; groups stay isolated.

Media Support

Clawdbot WhatsApp can process and respond to:

• Text messages
• Images (with vision AI)
• Voice messages (PTT audio with transcription)
• Documents
• Location messages

Read Receipts

Clawdbot WhatsApp can send read receipts when configured.

Acknowledgment Reactions

Auto-react on receipt to confirm message received.

Clawdbot WhatsApp Configuration

Full Configuration Example

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+15551234567", "+10987654321"],
      "configWrites": true,
      "selfChatMode": false
    }
  }
}

Config Writes

By default, WhatsApp is allowed to write config updates triggered by /config set|unset. Disable with:

{
  "channels": {
    "whatsapp": {
      "configWrites": false
    }
  }
}

Clawdbot WhatsApp Credential Storage

Clawdbot stores WhatsApp credentials securely:

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

• Backup copy at creds.json.bak (restored on corruption)
• Legacy compatibility: older installs stored Baileys files directly in ~/.clawdbot/credentials/

Your WhatsApp session data remains on your local machine, ensuring privacy.

Troubleshooting Clawdbot WhatsApp

Connection Lost

If Clawdbot WhatsApp disconnects:

1. Check internet connection
2. Re-authenticate: clawdbot channels login
3. Review logs: cat /tmp/clawdbot/whatsapp.log

Messages Not Sending

If Clawdbot WhatsApp fails to send messages:

1. Verify account status: clawdbot channels status whatsapp
2. Check allowlist configuration
3. Ensure Clawdbot gateway is running
4. Active listener is required for outbound sends

QR Code Expired

If the Clawdbot WhatsApp QR code expires:

clawdbot channels logout
clawdbot channels login

Logout

Logout deletes WhatsApp auth state (but keeps shared oauth.json):

clawdbot channels logout
# or for specific account
clawdbot channels logout --account <id>

Clawdbot WhatsApp Best Practices

1. Use Dedicated Number: Separate phone number provides best experience
2. Set Clear Boundaries: Configure allowlists to control Clawdbot WhatsApp access
3. Monitor Usage: Review Clawdbot WhatsApp logs regularly
4. Update Regularly: Keep Clawdbot updated for latest WhatsApp compatibility
5. Backup Credentials: Backup your Clawdbot WhatsApp credentials periodically

Why Not Twilio?

WhatsApp Business numbers are a poor fit for a personal assistant:

• Meta enforces a 24-hour reply window
• High-volume usage triggers aggressive blocking
• Business accounts aren't meant for personal assistant messages

Next Steps

• Clawdbot Telegram Integration - Connect Clawdbot to Telegram
• Clawdbot Discord Integration - Set up Clawdbot on Discord
• Clawdbot Setup Guide - Complete installation guide