Skip to main content
Connect WhatsApp to your LemonClaw instance by scanning a QR code — just like WhatsApp Web. This guide works for both hosted Claw instances and self-hosted LemonClaw deployments.

​
Prerequisites

WhatsApp uses your real phone number. Messages sent through the bot will appear as coming from your WhatsApp account. Use a dedicated number if you want separation.
VoIP numbers are not supported. WhatsApp requires a real SIM-based phone number. Virtual numbers (Google Voice, Skype, etc.) will not work for QR code pairing.

​
Setup Guide

1

Open the LemonClaw WebUI

  1. If you’re using hosted Claw, go to your Claw Dashboard and click Open WebUI
  2. If you’re self-hosting LemonClaw, open your own WebUI (for example http://your-ip:18789) and sign in with your token
  3. In the WebUI, navigate to Settings → Channels
  4. Expand the WhatsApp section
  5. Configure the Access Policy (allowlist recommended)
  6. Click Save first — you must save the configuration before scanning the QR code
2

Scan the QR Code

  1. Click Scan QR Code button
  2. A QR code will appear (valid for ~60 seconds)
  3. On your phone, open WhatsApp → Settings → Linked Devices → Link a Device
  4. Scan the QR code displayed on screen
  5. Wait for the connection to establish
3

Configure Access Policy

WhatsApp uses the allowlist policy — only phone numbers you specify can interact with the AI bot.Add allowed phone numbers in the LemonClaw WebUI (international format, e.g., +1234567890).
Unlike other platforms, WhatsApp does not support the pairing mechanism. You must explicitly add allowed contacts.
4

Start Chatting

Send a message to the connected WhatsApp number from an allowed contact — the AI will respond!

​
Group Settings

WhatsApp groups are supported. Configure group behavior in the Channels section:
SettingOptionsDescription
Group PolicyOpen (default) / Allowlist / DisabledControls who can trigger the bot in groups
Require @mentionOn / OffBot only responds when @mentioned
Group IDsList of group JIDsRestrict to specific groups (empty = all groups)
Group Allowed UsersList of phone numbersOnly these users can trigger the bot (allowlist mode)
Use E.164 format for phone numbers in the group allowlist (e.g., +1234567890).

​
Troubleshooting

Click Scan QR Code again to generate a fresh code. QR codes expire after ~60 seconds.
WhatsApp may disconnect linked devices after inactivity. Re-scan the QR code to reconnect.
  • Check that the sender’s number is in your allowlist (if using allowlist policy)
  • Verify your instance is running
  • Check your LemonData balance