WhatsApp Setup

WhatsApp setup connects Meta WhatsApp Cloud API to one Kravos.ai deployment. Meta delivers customer messages to Kravos.ai, and Kravos.ai sends AI or human replies through the configured WhatsApp phone number.

Required Kravos.ai Configuration

The channel settings status endpoint reports this readiness at GET /api/settings/channels.

Meta Setup Checklist

1. Create or choose your Meta app and add WhatsApp.
2. Connect the WhatsApp Business Account and phone number you want Kravos.ai to send from.
3. Create an access token that can send WhatsApp messages for that phone number.
4. Set META_PHONE_NUMBER_ID to the phone number ID, not the display phone number.
5. Set the callback URL to:

https://your-web-app.example.com/api/webhooks/whatsapp

1. Enter the same verify token that you configured as META_VERIFY_TOKEN.
2. Subscribe the webhook to WhatsApp message events.
3. Create or activate a tenant ChannelConfig for WHATSAPP when you need first-message fallback routing.

What The WhatsApp Webhook Accepts

Challenge request

Meta verifies the URL with a GET request that includes:

When the token matches, Kravos.ai returns the raw challenge text with status 200. Invalid tokens return 403. Missing META_VERIFY_TOKEN returns 503.

Message delivery request

Meta delivers messages with POST /api/webhooks/whatsapp.

Implemented behavior:

• reads the raw request body before parsing JSON
• verifies x-hub-signature-256 with HMAC SHA-256 and META_APP_SECRET
• returns 401 for missing or invalid signatures
• returns 400 for invalid JSON
• extracts messages from entry[].changes[].value.messages[]
• extracts the business phone number ID from value.metadata.phone_number_id
• extracts sender name and phone from value.contacts[] when available
• ignores payloads that do not contain complete message records
• deduplicates provider message IDs for 24 hours
• enqueues channel.inbound jobs for new messages

Message Support

Testing WhatsApp

Use Meta's webhook verification first. Then send a test message from a WhatsApp user to the configured business phone number.

A successful POST returns:

{
  "data": {
    "received": true,
    "deduped": false,
    "dedupedCount": 0,
    "enqueued": 1
  }
}

If you resend the same provider message ID within 24 hours, deduped becomes true and no new job is queued.

Troubleshooting

Meta cannot verify the webhook

• Confirm the public URL is HTTPS and points to /api/webhooks/whatsapp.
• Confirm META_VERIFY_TOKEN exactly matches the token entered in Meta.
• Confirm the deployment has PUBLIC_APP_URL or NEXTAUTH_URL set for display, but use the actual public URL in Meta.

POST returns 401

• Confirm META_APP_SECRET is the app secret for the same Meta app sending the webhook.
• Do not reserialize JSON before checking signatures. The implemented handler verifies the raw request body.

POST returns 503

• Check for missing META_APP_SECRET.
• Confirm there is an active ChannelConfig for WHATSAPP if this is a first-time user.
• In multi-tenant deployments, confirm first-message routing is not ambiguous across multiple tenants.

The message is stored but no AI reply is sent

• Confirm the worker process is running.
• Confirm RUNTIME_URL and RUNTIME_SERVICE_TOKEN are set for the worker.
• Confirm the conversation status is AI_ACTIVE.
• Confirm META_WHATSAPP_ACCESS_TOKEN or META_ACCESS_TOKEN and META_PHONE_NUMBER_ID are set for outbound sending.

Related Docs