WhatsApp Cloud API
Add WhatsApp via Meta's official Business Cloud API. The supported route — distinct from the QR-based add-whatsapp skill.
What it does
- Official Meta API — supported, no ToS risk
- 1:1 conversations only (no group chats in the Cloud API)
- Permanent System User access tokens
- Webhook signature verification via app secret
- Pairs with the existing QR-based /add-whatsapp skill — pick one
What you'll need
- NanoClaw installed and running
- A Meta for Developers account
- A WhatsApp Business app on Meta with a phone number
- A publicly reachable HTTPS endpoint for the webhook
Install
/add-whatsapp-cloud How it works
The /add-whatsapp-cloud skill connects NanoClaw to WhatsApp via Meta’s official WhatsApp Business Cloud API. This is the supported, ToS-clean route — distinct from /add-whatsapp, which uses the unofficial Baileys library and a QR-code login.
The Cloud API supports 1:1 messaging only (no group chats), but it’s stable, cheap at low volume, and has none of the account-ban risk of the unofficial route.
Setup
- Create an app of type Business.
- Add the WhatsApp product.
- Open WhatsApp → API Setup:
- Note the Phone Number ID (this is the platform ID NanoClaw uses, not the phone number).
- Generate a permanent System User access token with
whatsapp_business_messagingpermission.
- Open WhatsApp → Configuration:
- Webhook URL:
https://your-domain/webhook/whatsapp - Verify Token: any random string you choose (matches
WHATSAPP_VERIFY_TOKEN) - Subscribe to webhook fields:
messages
- Webhook URL:
- Copy the App Secret from Settings → Basic.
Add to .env:
WHATSAPP_ACCESS_TOKEN=...
WHATSAPP_PHONE_NUMBER_ID=...
WHATSAPP_APP_SECRET=...
WHATSAPP_VERIFY_TOKEN=...The skill copies the WhatsApp Cloud adapter from the channels branch and installs @chat-adapter/whatsapp.
Cloud vs. Baileys
Cloud API (/add-whatsapp-cloud) | Baileys (/add-whatsapp) | |
|---|---|---|
| Supported | Yes — Meta’s official API | No — reverse-engineered |
| Group chats | No | Yes |
| Account ban risk | None | Some |
| Setup | Meta dev console + webhook | QR scan |
| Cost | Free at low volume; paid above | Free |
Pick the Cloud API for production / business use. Pick Baileys when you need group chat support or want a personal account without setting up a Meta business app.
Tips
- The Verify Token is a string you make up — it just needs to match between Meta’s webhook config and your
.env. Meta uses it once during webhook handshake. - Keep the App Secret locked down — it’s used to verify webhook signatures, so a leak lets anyone forge inbound messages to your bot.
- The Phone Number ID is what NanoClaw uses for routing. The actual phone number is just a display thing — don’t confuse them.
- Each sender gets their own conversation automatically. Use a separate agent group when different contacts shouldn’t share information.