WhatsApp Integration
Overview
Nexus integrates with the WhatsApp Business API (Cloud API) via Meta's Embedded Signup flow. Once connected, agents can send and receive WhatsApp messages, template messages, media, and reactions from the omnichannel inbox.
Capabilities
- Receive inbound text, image, video, document, audio, and location messages.
- Send outbound text, media, and template messages.
- Send reactions to messages.
- Receive delivery status updates (sent, delivered, read).
- Voice note transcription (Arabic and English) via
voice-transcription-worker.
Required permissions / scopes
whatsapp_business_managementwhatsapp_business_messaging
Edge Functions
| Function | Direction | Purpose |
|---|---|---|
whatsapp-webhook | Inbound | Receives messages and status updates from WhatsApp |
wa-webhook | Inbound | Alternative webhook endpoint |
whatsapp-send-message | Outbound | Sends text and media messages |
wa-send | Outbound | Alternative send endpoint |
whatsapp-send-template | Outbound | Sends pre-approved template messages |
whatsapp-send-reaction | Outbound | Sends emoji reactions to messages |
whatsapp-get-templates | Read | Fetches available message templates |
whatsapp-templates | Read | Lists templates |
whatsapp-reply-status | Status | Handles reply status updates |
whatsapp-status-webhook | Status | Receives delivery status webhooks |
wa-es-callback | Auth | Handles embedded signup OAuth callback |
save-whatsapp-credentials | Config | Stores connection credentials |
Webhook setup
WhatsApp webhooks are registered automatically during the Embedded Signup flow. The webhook endpoint receives all events for the connected WABA (WhatsApp Business Account) and routes them to the correct organization.
Webhook verification uses a verify token stored in environment variables (never exposed publicly).
Common troubleshooting
| Issue | Resolution |
|---|---|
| Messages not arriving | Check webhook subscription in Meta Business Manager → WhatsApp → Configuration. Verify the Edge Function is deployed. |
| Template messages failing | Ensure the template is approved. Check that template parameters match the expected format. |
| Media not downloading | Verify Supabase Storage is configured. Check media URL expiration. |
| Duplicate messages | Check for duplicate webhook deliveries. The system deduplicates by external message ID. |