Talk to CUGA on WhatsApp via Meta's Cloud API — four values, a signed webhook, and the test-number gotchas to know.
WhatsApp is a direct channel over Meta's Cloud API: Meta posts each inbound message to a CUGA webhook, and CUGA replies through the Graph API. It needs a public URL. Four values:
WHATSAPP_TOKEN=… # a System User token (permanent) — not the 24h test token
WHATSAPP_PHONE_NUMBER_ID=… # the number's id (not the phone number itself)
WHATSAPP_APP_SECRET=… # validates inbound signatures
WHATSAPP_VERIFY_TOKEN=… # any secret you choose; echoed on webhook verificationCreate a Meta app with WhatsApp
developers.facebook.com → your app → add the WhatsApp
product. The API Setup page gives you a Phone number ID → WHATSAPP_PHONE_NUMBER_ID.
Get a permanent token
The temporary token on API Setup expires in 24 hours. For anything real, create a System User
token (Business Settings → Users → System Users → generate a token with whatsapp_business_messaging)
→ WHATSAPP_TOKEN. A System User token does not expire.
App secret + a verify token
App → Settings → Basic → App Secret → WHATSAPP_APP_SECRET (CUGA verifies the inbound HMAC with
it). Pick any random string as WHATSAPP_VERIFY_TOKEN — you'll paste the same value into the webhook
config next.
Point the webhook at CUGA + subscribe messages
WhatsApp → Configuration → Webhook: Callback URL = https://<your-events-url>/api/events/whatsapp/events,
Verify token = your WHATSAPP_VERIFY_TOKEN. Then subscribe to the messages field.
Run it
make up-noap-slack # a tunnel so Meta's webhook can reach you (Slack + WhatsApp both use it)
make channelsMessage your WhatsApp number; CUGA replies. Arm automations with /automate ….
Test Number → allow-list your phone
Meta's free Test Number can only exchange messages with numbers you've added to its allow-list (API Setup → the "To" list → add your number + verify the code). If your phone isn't on the list, your message may arrive but the reply is rejected by Meta — and you see nothing. A verified/real number can message anyone, subject to Meta's rate tiers.
Two more WhatsApp rules
- 24-hour window — a business can only send free-form replies within 24h of the user's last message; after that you need an approved template.
- WABA subscription — the app must be subscribed to your WhatsApp Business Account, or inbound never arrives (it fails silently — the console's own "Send message" button still works). Confirm it under Configuration.
