WhatsApp¶
WhatsApp uses Twilio Messaging API and an in-process aiohttp webhook listener.
Twilio Setup¶
- Create or select a Twilio account.
- Enable WhatsApp messaging for a sender.
- Record:
- Account SID
- Auth token
- WhatsApp sender, for example
whatsapp:+15550001111 - Put them in
team.env:
TWILIO_ACCOUNT_SID=AC...
TWILIO_AUTH_TOKEN=...
TWILIO_WHATSAPP_FROM=whatsapp:+15550001111
Webhook URL¶
The adapter validates Twilio signatures using the public URL. Configure:
--enable-whatsapp \
--whatsapp-webhook-host 0.0.0.0 \
--whatsapp-webhook-port 8081 \
--whatsapp-webhook-path /webhooks/whatsapp \
--whatsapp-public-base-url https://example.ngrok.app
Set the Twilio webhook to:
https://example.ngrok.app/webhooks/whatsapp
Use HTTPS for public Twilio webhooks. Local development commonly uses a tunnel such as ngrok or a reverse proxy.
Inbound Allowlists¶
Restrict inbound senders:
--whatsapp-allow-sender-id whatsapp:+15551234567
The sender id should match Twilio's From value.
Proactive Delivery¶
If WhatsApp should receive proactive agent messages:
--default-delivery-channel whatsapp \
--default-delivery-chat-id whatsapp:+15551234567
If no default target is set, ordinary proactive traffic does not infer a WhatsApp recipient. Manager available/unavailable notices may fall back to the most recently active WhatsApp session.
Verification¶
- Start the gateway with WhatsApp enabled.
- Confirm logs show the webhook listener path and port.
- Send a WhatsApp message from an allowed sender.
- Confirm the webhook returns quickly.
- Confirm the agent replies through Twilio.
- Confirm invalid Twilio signatures are rejected unless signature validation is intentionally disabled.
- Confirm the public base URL and webhook path exactly match the Twilio console.
Troubleshooting¶
- Signature validation fails: verify
whatsapp.public_base_url, path, scheme, and Twilio auth token. - No inbound messages: verify the Twilio webhook URL and tunnel.
- Replies fail: verify
TWILIO_ACCOUNT_SID,TWILIO_AUTH_TOKEN, andTWILIO_WHATSAPP_FROM. - Long tasks appear idle: WhatsApp has no native typing indicator in this adapter path; it sends periodic textual progress updates.