WhatsApp Integration
Connect your Hatcher agent to WhatsApp so users can chat with it via WhatsApp messages. This integration uses Baileys (WhatsApp Web protocol) with QR code pairing — no Meta Business account or Cloud API required.
WhatsApp integration is free on all Hatcher plans. You just need a WhatsApp account and a phone to scan the QR code.
Supported Frameworks
WhatsApp integration works with OpenClaw, Hermes, and Hermes. OpenClaw does not support WhatsApp.
| Framework | WhatsApp Support |
|---|---|
| OpenClaw | Supported |
| Hermes | Supported |
| Hermes | Supported |
| OpenClaw | Not supported |
Prerequisites
- A WhatsApp account on your phone
- A Hatcher agent already created (Getting Started)
- Agent framework must be OpenClaw or Hermes
How It Works
Hatcher uses Baileys , an open-source WhatsApp Web client library. When you pair your WhatsApp account, Hatcher connects as a linked device (similar to WhatsApp Web or Desktop). Your agent can then send and receive messages through your WhatsApp number.
Setup
Open the Integrations tab
- Go to your Hatcher Dashboard
- Navigate to My Agents and select your agent
- Open the Integrations tab
Configure allowed phone numbers (optional)
Before pairing, you can restrict which phone numbers your agent responds to:
- Find WhatsApp in the integrations list
- Click Configure (or expand the WhatsApp section)
- In the Allowed Phone Numbers field, enter the phone numbers that should be able to chat with your agent (one per line, in international format like
+1234567890) - Leave this field empty to allow messages from everyone
Allowed phone numbers are optional. If you leave the field empty, your agent will respond to any incoming WhatsApp message.
Start WhatsApp pairing
- Find WhatsApp in the integrations list
- Click Pair WhatsApp
- A QR code will appear on screen
Scan the QR code
- Open WhatsApp on your phone
- Go to Settings (or the three-dot menu) → Linked Devices
- Tap Link a Device
- Point your phone’s camera at the QR code displayed in Hatcher
The pairing completes automatically within a few seconds.
The QR code expires after about 60 seconds. If it expires, click Pair again to generate a new one.
Verify the connection
Once paired, the WhatsApp integration status in Hatcher will show as Connected. Your agent is now linked to your WhatsApp account as a device.
Test it
From another phone or WhatsApp account, send a message to your WhatsApp number. Your Hatcher agent should respond.
How It Differs from Meta Cloud API
Previous versions of the WhatsApp integration used the Meta Cloud API, which required a Meta Business account, system user tokens, webhook configuration, and a registered business phone number. The new QR pairing approach is much simpler:
| QR Pairing (Baileys) | Meta Cloud API (old) | |
|---|---|---|
| Setup | Scan a QR code | Meta Business account, webhooks, system user tokens |
| Cost | Free | 1,000 free conversations/month, then per-message |
| Phone number | Your existing WhatsApp number | Separate business number required |
| Time to set up | ~30 seconds | ~30 minutes |
Limitations
- Linked device limits — WhatsApp allows up to 4 linked devices. Your Hatcher agent counts as one.
- End-to-end encryption — Messages are encrypted via the WhatsApp protocol. Hatcher processes messages in memory but does not store WhatsApp message content beyond the agent’s chat history.
- Session persistence — The pairing session persists across agent restarts. If you log out the linked device from your phone, you will need to re-pair.
- No broadcast lists — The integration handles one-to-one and group conversations, but does not support broadcast lists.
Troubleshooting
QR code expired
QR codes expire after about 60 seconds.
Fix: Click Pair again to generate a new QR code and scan it promptly.
Agent not responding to messages
- Check the pairing status — Go to the Integrations tab and verify WhatsApp shows as Connected
- Check your phone — Go to Linked Devices in WhatsApp and confirm the Hatcher device is still listed
- Restart the agent — Sometimes a restart resolves connection issues
- Re-pair — If the device was removed from your phone, you need to pair again
”Connection closed” or frequent disconnections
WhatsApp may close linked device sessions if the primary phone is offline for too long (usually 14+ days).
Fix: Make sure the phone with your primary WhatsApp account stays connected to the internet regularly.
Messages from groups not received
By default, the agent responds to all messages including group chats. If group messages are not coming through, restart the agent to refresh the connection.
Multiple agents on the same WhatsApp number
Each WhatsApp number can only be paired with one agent at a time. If you need multiple agents, use different WhatsApp numbers.
Useful Links
- Baileys — Open-source WhatsApp Web library
- WhatsApp Linked Devices FAQ — Official WhatsApp documentation