WhatsApp Configuration

Clawdbot integrates with WhatsApp through the Baileys library, supporting both private and group chats.

Quick Start

Minimal Configuration

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

Login

Run the login command and scan the QR code through WhatsApp's "Linked Devices" feature:

clawdbot channels login whatsapp

Operating Modes

Recommended: Dedicated Number

Use a separate phone number exclusively for Clawdbot:

An old phone with an eSIM works well
You can use WhatsApp Business on the same device with a different number

{
  channels: {
    whatsapp: {
      dmPolicy: "open",  // Safe for dedicated number
      account: "+15559876543"
    }
  }
}

Personal Number Mode

Run on your personal WhatsApp:

{
  channels: {
    whatsapp: {
      // Only respond to messages from yourself
      selfChatMode: true,
      dmPolicy: "allowlist",
      allowFrom: ["your own number"]
    }
  }
}

Test by messaging yourself to avoid disturbing contacts.

Phone Number Requirements

Must be a real mobile number: Able to receive SMS verification
Avoid: VoIP, virtual numbers (usually get blocked)
Recommended: Local eSIM or prepaid SIM cards
Not recommended: TextNow, Google Voice, etc.

Access Control

Pairing Mode (Default)

Unknown senders receive a pairing code they must provide to use:

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      // Pairing code expiry (seconds)
      pairingExpiry: 3600
    }
  }
}

Allowlist Mode

Only respond to specified numbers:

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

Group Chat Configuration

Mention-Based Activation

Only respond when @mentioned:

{
  channels: {
    whatsapp: {
      groups: {
        "*": {
          requireMention: true
        }
      }
    }
  }
}

Group Allowlist

Only respond in specific groups:

{
  channels: {
    whatsapp: {
      groupPolicy: "allowlist",
      allowGroups: [
        "123456789@g.us"
      ]
    }
  }
}

Features

Auto-Reactions

Send emoji reactions when messages are received:

{
  channels: {
    whatsapp: {
      ackReaction: "👀",
      processingReaction: "🤔",
      doneReaction: "✅"
    }
  }
}

Media Support

Supports images, video, audio, and documents:

{
  channels: {
    whatsapp: {
      media: {
        // Max image size (MB)
        imageMaxMb: 6,
        // Max video size (MB)
        videoMaxMb: 16,
        // Max document size (MB)
        documentMaxMb: 100
      }
    }
  }
}

History Injection

Inject historical messages as context in group chats:

{
  channels: {
    whatsapp: {
      groups: {
        "*": {
          // Inject last 50 messages
          historyCount: 50
        }
      }
    }
  }
}

Multi-Account Support

Run multiple WhatsApp accounts in one gateway process:

{
  channels: {
    whatsapp: {
      accounts: {
        personal: {
          phone: "+15551234567",
          dmPolicy: "pairing"
        },
        work: {
          phone: "+15559876543",
          dmPolicy: "allowlist",
          allowFrom: ["work contacts"]
        }
      }
    }
  }
}

Important Notes

Twilio API Not Supported

Clawdbot no longer supports Twilio's WhatsApp Business API due to:

24-hour reply window limitation
Aggressive blocking of high-volume personal assistant usage

Avoiding Bans

Don't send spam
Avoid frequent bulk sending
Use a dedicated number
Maintain normal usage patterns

Troubleshooting

QR Code Scan Failed

Ensure phone WhatsApp is up to date
Try regenerating QR code: clawdbot channels login whatsapp --refresh
Check network connection

Connection Dropped

# Check status
clawdbot channels status whatsapp
 
# Reconnect
clawdbot channels reconnect whatsapp

Messages Not Responding

Check dmPolicy/groupPolicy configuration
Confirm number is in allowlist
View logs: clawdbot logs --channel whatsapp

Next Steps

Overview Telegram