WhatsApp Setup

WhatsApp is one of the most popular messaging platforms, and Moltbot connects to it using WhatsApp Web via the Baileys library. This guide covers everything you need to set up WhatsApp with Moltbot.

Setting up WhatsApp is straightforward:

1. Start your Gateway: openclaw gateway
2. Link WhatsApp: openclaw channels login
3. Scan QR code with your phone
4. Start chatting!

WhatsApp uses QR code pairing (like WhatsApp Web):

Step-by-Step

1. Run: openclaw channels login
2. A QR code will appear in your terminal
3. Open WhatsApp on your phone
4. Go to Settings → Linked Devices
5. Tap "Link a Device"
6. Scan the QR code
7. Wait for connection confirmation

QR Code Display

The QR code appears as:

• ASCII art in terminal (default)
• Or as a URL you can open in browser
• Or displayed in Control UI dashboard

Direct Messages

• Send and receive DMs
• Media support (images, audio, video)
• Voice notes
• Location sharing
• Read receipts

Group Chats

• Join group chats
• Mention-based activation (default)
• Reply threading
• Group allowlists
• Sandboxed execution

Media Support

• Images and photos
• Audio and voice notes
• Video files
• Documents
• Location sharing

Basic Configuration

{
  "channels": {
    "whatsapp": {
      "enabled": true
    }
  }
}

DM Allowlist

Control who can message you:

{
  "channels": {
    "whatsapp": {
      "allowFrom": ["+1234567890", "+0987654321"]
    }
  }
}

Group Configuration

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

DM Pairing

By default, unknown senders require pairing:

• Unknown contacts receive a pairing code
• Approve with: openclaw pairing approve whatsapp <code>
• Once approved, added to allowlist

Opening DM Access

To allow public DMs (not recommended):

• Set dmPolicy: "open"
• Include "*" in allowlist
• Warning: Only use with proper security

QR Code Not Appearing

If QR code doesn't show:

1. Check terminal supports QR display
2. Try opening Control UI: http://localhost:18789
3. Check Gateway is running: openclaw status

Connection Drops

If WhatsApp disconnects:

1. Check internet connection
2. Restart Gateway: openclaw gateway
3. Re-link device: openclaw channels login
4. Check WhatsApp Web isn't open elsewhere

Messages Not Received

If messages aren't coming through:

1. Check Gateway is running
2. Verify WhatsApp is connected
3. Check allowlist configuration
4. Review Gateway logs

• Use Allowlists - Control who can message you
• Enable Mention Gating - For group chats
• Keep Gateway Running - Maintains WhatsApp connection
• Monitor Connection - Check status regularly
• Backup Credentials - Save WhatsApp session data