WhatsApp Setup

Overview

Connect Clawdbot to WhatsApp and chat with Claude directly from your phone. This guide covers setup, configuration, and best practices.

Note

Clawdbot uses WhatsApp Web protocol. Your phone must stay connected to the internet for the connection to work.

Prerequisites

• Clawdbot installed and configured
• WhatsApp account on your phone
• Active internet connection on both phone and server

Setup

1. Enable WhatsApp channel

   Edit your .env file:

   WHATSAPP_ENABLED=true

2. Install WhatsApp dependencies

   pip install whatsapp-web.py
   # or for Node.js based
   npm install whatsapp-web.js

3. Start Clawdbot

   python -m clawdbot

4. Scan QR Code

   A QR code will appear in your terminal. On your phone:

   • Open WhatsApp
   • Go to Settings → Linked Devices
   • Tap “Link a Device”
   • Scan the QR code

5. Verify connection

   You should see:

   [INFO] WhatsApp connected successfully
   [INFO] Ready to receive messages

Configuration Options

.env

# Enable/disable WhatsApp channel
WHATSAPP_ENABLED=true

# Session storage location
WHATSAPP_SESSION_PATH=.wwebjs_auth

# Rate limiting (messages per minute)
WHATSAPP_RATE_LIMIT=10

# Auto-reply to group messages
WHATSAPP_GROUPS_ENABLED=false

# Message prefix for bot commands (optional)
WHATSAPP_PREFIX=!

# Allowed phone numbers (empty = all)
WHATSAPP_ALLOWED_NUMBERS=+1234567890,+0987654321

Features

Direct Messages

Send any message to your own number or have contacts message you. Clawdbot responds as if you were chatting with Claude.

Group Chat Support

Caution

Group chat support is experimental. Enable with care to avoid rate limits.

When enabled, Clawdbot can respond in group chats. Configure with:

WHATSAPP_GROUPS_ENABLED=true
WHATSAPP_GROUP_PREFIX=@bot  # Only respond when mentioned

Media Support

Media Type	Receive	Send
Text	✅	✅
Images	✅	⚠️ Limited
Voice	✅ (transcribed)	❌
Documents	✅	❌
Location	✅	❌

Best Practices

Avoiding Rate Limits

WhatsApp may restrict your account if it detects automated behavior. To stay safe:

1. Don’t spam: Keep messages reasonable
2. Add delays: Configure rate limiting
3. Avoid bulk messaging: Don’t use for mass outreach
4. Keep natural patterns: Vary response times slightly

Session Management

The WhatsApp session is stored in .wwebjs_auth/. To reset:

rm -rf .wwebjs_auth/
# Restart Clawdbot and scan QR code again

Running 24/7

For always-on operation:

1. Use a VPS or home server
2. Set up as a system service (see Linux Guide)
3. Keep your phone connected to WiFi

Troubleshooting

QR Code Not Showing

# Try running with debug
LOG_LEVEL=DEBUG python -m clawdbot

# Check if terminal supports QR display
# Some terminals need specific encoding
TERM=xterm-256color python -m clawdbot

Disconnection Issues

Symptoms: Bot disconnects randomly

Solutions:

1. Keep phone connected to internet
2. Don’t logout from WhatsApp Web manually
3. Check for WhatsApp app updates
4. Reset session if needed

Message Not Delivered

Check:

• Phone has internet access
• WhatsApp account is not restricted
• Rate limits not exceeded
• Recipient hasn’t blocked you

”Session Expired” Error

# Clear session and re-authenticate
rm -rf .wwebjs_auth/
python -m clawdbot
# Scan new QR code

Security Considerations

• Your number is visible: Recipients see your real number
• Messages on your phone: Conversations appear in your WhatsApp
• Account risk: Excessive automation may trigger WhatsApp restrictions
• End-to-end encryption: Messages are encrypted by WhatsApp

Tip

Consider using a secondary phone number for Clawdbot if you’re concerned about account restrictions.

Example Usage

Once connected, simply message your Clawdbot-connected number:

You: What's the capital of France?
Bot: The capital of France is Paris.

You: Write me a short poem about coding
Bot: Here's a poem for you:
     In lines of code, we dream and build,
     Logic flows, a canvas filled...

Next Steps

• Set up additional channels: Telegram, Discord
• Learn about hooks for custom behavior
• Configure TTS for voice responses