Skip to content
BrainRoad BrainRoad
Documentation Menu

WhatsApp Setup

Connect your agent to WhatsApp so it can send and receive messages.

On this page

How WhatsApp Connection Works

Your agent connects to WhatsApp as a linked device on your existing WhatsApp account. This is the same mechanism you use to connect WhatsApp Web or WhatsApp Desktop — your phone remains the primary device, and your agent operates alongside it.

Messages sent to your WhatsApp number are visible to both your phone and your agent. The agent can read incoming messages and send replies through your number.

How to Connect WhatsApp

After your agent finishes onboarding, you can connect WhatsApp in two ways:

  1. Go to your agent’s detail page
  2. Click “Add Channel” in the Getting Started panel
  3. Select WhatsApp (marked as recommended)
  4. Follow the on-screen setup steps
  5. When ready, the console will show a QR code

From the Console

Open the Console and run:

openclaw channels add

Then select WhatsApp, or run directly:

openclaw channels login whatsapp

Scanning the QR Code

  1. Open WhatsApp on your phone.
  2. Go to Settings and tap Linked Devices.
  3. Tap Link a Device.
  4. Point your phone’s camera at the QR code displayed in your console or setup dialog.

WhatsApp authenticates the connection within a few seconds. Once complete, your agent is ready to receive and send messages.

QR Code Timing

The QR code is valid for approximately 60 seconds. If it expires before you scan it, a new one is generated automatically. Check your console for the updated code.

If the QR code is hard to read (too small or unclear), try maximizing your browser window or opening the standalone Console page for more screen space.

If the Connection Fails

  • Code expired: A new one appears automatically within a few seconds.
  • Scan succeeded but connection drops: WhatsApp may need a moment. Wait 10–15 seconds and check the console output for a confirmation message.
  • Repeated failures: Try again from the Console: openclaw channels login whatsapp gives you a fresh setup outside the dashboard flow.

After Setup

Your agent can now receive and respond to WhatsApp messages automatically. All messages flow through your existing WhatsApp number — contacts message you as they normally would, and your agent handles the responses on your behalf.

If the connection drops (for example, after a phone restart or gateway update), your agent reconnects automatically. If it cannot reconnect, you will see an error in the Activity feed and may need to re-scan the QR code by repeating the setup process above.