Channels

WhatsApp Channel Configuration

Step-by-step setup for WhatsApp Cloud API: Meta app, webhook, dashboard config, activation, and message validation.

Back to Docs

Audience: Channel admins and support engineersRead Time: 12 minUpdated: May 2026

Step 1: Get values from Meta API Setup

Open Meta Developers -> your app -> WhatsApp -> API Setup.
Copy Phone Number ID (sender number identity).
Copy WhatsApp Business Account ID (WABA ID).
Generate or copy a valid Access Token for Cloud API calls.
Add your recipient number in the To test numbers list and complete verification OTP.
Keep this page open; you will reuse these values in later steps.

Step 2: Prepare webhook callback values

Set callback URL format as: https://<your-api-domain>/bots/<botId>/whatsapp.
For this bot, callback URL example is: https://bot-code-zero.onrender.com/bots/84811aa8-44e0-4190-b5d0-879f1c7bba28/whatsapp.
Create your own Verify Token string (do not use access token value).
Use the exact same Verify Token in both Meta Webhook settings and this bot's WhatsApp config.

Step 3: Configure WhatsApp in Bot Dashboard

Open Dashboard -> Bots -> <your bot> -> Channels -> WhatsApp -> Configure.
Enter Access Token, Phone Number ID, Webhook URL, and Verify Token.
Click Save.
Click Test Connection and confirm response shows ok=true and verifiedName.
Confirm channel row shows isActive=true after successful test.

Step 4: Configure Webhook in Meta

Open Meta Developers -> Webhooks -> whatsapp_business_account.
Paste Callback URL and Verify Token, then click Verify and save.
In webhook fields, subscribe at minimum to messages.
If app is in Development mode, publish app (Live mode) to receive real production user events.

Step 6: Send first inbound test message

From the verified recipient number, send a plain text message (for example: hi) to the Meta test sender number.
Check backend logs for POST /bots/<botId>/whatsapp.
Expected processing log: inbound processed ...
Expected outbound behavior: message send attempt to Graph API and outbound metrics increment.

Step 7: Validate metrics and health

Open Channels -> WhatsApp Metrics and click Refresh.
Inbound total should increase after each received user message.
Outbound total should increase when bot sends reply.
If outbound failures > 0, inspect provider error message in WhatsApp service logs.

Step 8: Troubleshooting by log pattern

active config not found ...: bot/channel mapping mismatch or inactive config; re-save channel and run test again.
webhook received with no messages ...: Meta sent status event only; ensure messages field is subscribed.
no POST /bots/<botId>/whatsapp logs: webhook not delivered; verify callback URL, app mode, and WABA subscription.
runtime dispatch failed ...: flow/runtime error after inbound parse; inspect runtime logs and node configuration.

Operational Checklist

OKMeta API Setup values are copied correctly (Phone Number ID, WABA ID, token).
OKDashboard WhatsApp config is saved with Access Token, Phone Number ID, Webhook URL, and Verify Token.
OKWebhook verification succeeds in Meta with exact callback URL and verify token match.
OKApp is subscribed to WABA and messages field is subscribed.
OKInbound POST reaches /bots/<botId>/whatsapp and bot sends outbound response.

Next Action

Apply this guide in your workspace and keep notes for your team in one shared SOP so onboarding and support remain consistent.

Open Workspace Browse More Docs

Loading page...

Step 1: Get values from Meta API Setup

Open Meta Developers -> your app -> WhatsApp -> API Setup.

Copy Phone Number ID (sender number identity).

Copy WhatsApp Business Account ID (WABA ID).

Generate or copy a valid Access Token for Cloud API calls.

Add your recipient number in the To test numbers list and complete verification OTP.

Keep this page open; you will reuse these values in later steps.

Step 2: Prepare webhook callback values

Set callback URL format as: https://<your-api-domain>/bots/<botId>/whatsapp.

For this bot, callback URL example is: https://bot-code-zero.onrender.com/bots/84811aa8-44e0-4190-b5d0-879f1c7bba28/whatsapp.

Create your own Verify Token string (do not use access token value).

Use the exact same Verify Token in both Meta Webhook settings and this bot's WhatsApp config.

Step 6: Send first inbound test message

From the verified recipient number, send a plain text message (for example: hi) to the Meta test sender number.

Check backend logs for POST /bots/<botId>/whatsapp.

Expected processing log: inbound processed ...

Expected outbound behavior: message send attempt to Graph API and outbound metrics increment.

Step 8: Troubleshooting by log pattern

active config not found ...: bot/channel mapping mismatch or inactive config; re-save channel and run test again.

webhook received with no messages ...: Meta sent status event only; ensure messages field is subscribed.

no POST /bots/<botId>/whatsapp logs: webhook not delivered; verify callback URL, app mode, and WABA subscription.

runtime dispatch failed ...: flow/runtime error after inbound parse; inspect runtime logs and node configuration.

Operational Checklist

OKMeta API Setup values are copied correctly (Phone Number ID, WABA ID, token).

OKDashboard WhatsApp config is saved with Access Token, Phone Number ID, Webhook URL, and Verify Token.

OKWebhook verification succeeds in Meta with exact callback URL and verify token match.

OKApp is subscribed to WABA and messages field is subscribed.

OKInbound POST reaches /bots/<botId>/whatsapp and bot sends outbound response.

WhatsApp Channel Configuration

Step 1: Get values from Meta API Setup

Step 2: Prepare webhook callback values

Step 3: Configure WhatsApp in Bot Dashboard

Step 4: Configure Webhook in Meta

Step 6: Send first inbound test message

Step 7: Validate metrics and health

Step 8: Troubleshooting by log pattern

Operational Checklist

Related Guides

Next Action

WhatsApp Channel Configuration

Step 1: Get values from Meta API Setup

Step 2: Prepare webhook callback values

Step 3: Configure WhatsApp in Bot Dashboard

Step 4: Configure Webhook in Meta

Step 6: Send first inbound test message

Step 7: Validate metrics and health

Step 8: Troubleshooting by log pattern

Operational Checklist

Related Guides

Next Action

WhatsApp Channel Configuration

Step 1: Get values from Meta API Setup

Step 2: Prepare webhook callback values

Step 3: Configure WhatsApp in Bot Dashboard

Step 4: Configure Webhook in Meta

Step 5: Subscribe app to WABA

Step 6: Send first inbound test message

Step 7: Validate metrics and health

Step 8: Troubleshooting by log pattern

Operational Checklist

Related Guides

Next Action

WhatsApp Channel Configuration

Step 1: Get values from Meta API Setup

Step 2: Prepare webhook callback values

Step 3: Configure WhatsApp in Bot Dashboard

Step 4: Configure Webhook in Meta

Step 5: Subscribe app to WABA

Step 6: Send first inbound test message

Step 7: Validate metrics and health

Step 8: Troubleshooting by log pattern

Operational Checklist

Related Guides

Next Action