WhatsApp Cloud Adapter Starter Guide

Reference implementation:

• rooaak-whatsapp-cloud-adapter-starter

Required env

• ROOAAK_API_KEY
• ROOAAK_WEBHOOK_SECRET
• ROOAAK_AGENT_ID
• WHATSAPP_VERIFY_TOKEN
• WHATSAPP_APP_SECRET
• WHATSAPP_ACCESS_TOKEN

Meta dashboard setup

1. Open developers.facebook.com/apps and select app.
2. Add/select WhatsApp product.
3. Go to WhatsApp -> Configuration -> Webhooks.
4. Configure:
   • Callback URL: https://<your-host>/webhooks/whatsapp
   • Verify token: exactly WHATSAPP_VERIFY_TOKEN
5. Click Verify and Save.
6. Subscribe messages field.

Credential sources

1. WHATSAPP_VERIFY_TOKEN:
   • self-generated secret string, example:
   • openssl rand -hex 24
2. WHATSAPP_APP_SECRET:
   • App settings -> Basic -> App Secret.
3. WHATSAPP_ACCESS_TOKEN:
   • WhatsApp API Setup page (use long-lived/system-user token in production).

Rooaak webhook registration

curl -X POST https://www.rooaak.com/api/v1/webhooks \
  -H "Authorization: Bearer $ROOAAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://<your-host>/webhooks/rooaak",
    "events": ["message.responded"]
  }'

Persist returned secret as ROOAAK_WEBHOOK_SECRET.

Session mapping

• sessionId: whatsapp:<phone_number_id>:<wa_id>
• metadata.channel.type: whatsapp_cloud
• include provider IDs in metadata.channel.*

Smoke test

1. Send WhatsApp message from tester number to configured sender/test number.
2. Verify adapter forwards inbound message to Rooaak.
3. Verify Rooaak response is delivered back to WhatsApp chat.

Failure checks

1. Verify callback fails:
   • WHATSAPP_VERIFY_TOKEN mismatch between Meta and runtime.
2. Inbound requests rejected:
   • WHATSAPP_APP_SECRET mismatch causes signature verification failure.
3. Outbound message errors:
   • invalid/expired WHATSAPP_ACCESS_TOKEN.