Meta App Dashboard → select your app → App settings → Basic. Copy App ID (public) and click Show next to App Secret (you may be re-prompted for your Facebook password). Paste both into the fields below.
Open Meta App Dashboard →
WABA ID (WhatsApp Business Account ID)Required
WhatsApp Manager → the small settings gear at the top-right of the account name shows the numeric ID. Or, in the App Dashboard, WhatsApp → API Setup displays it under “WhatsApp Business Account ID”.
Open WhatsApp Manager →
Phone Number IDRequired
App Dashboard → WhatsApp → API Setup → the “From” dropdown lists every number added to this WABA and displays its Phone Number ID (a long numeric string; NOT the phone number itself). If your production number isn’t listed, add it in WhatsApp Manager → Phone numbers → Add phone number.
Access Token — use a System User token, not the temporary one
Required
The token shown in WhatsApp → API Setup expires in 24 hours — fine for a first “hello world”, useless in production. For real deployment, mint a non-expiring System User token:
Business Settings → Users → System users → Add. Give it a name (e.g. “codeb-wa-bridge”) and role Admin.
Click the new system user → Add assets → add the WhatsApp Account with Full control.
Click Generate new token → pick your Meta App → expiration Never → permissions whatsapp_business_messaging + whatsapp_business_management.
Copy the token immediately (Meta shows it once) and paste into the field below.
Copy the actual number in E.164 format (e.g. +4915157610183) from WhatsApp Manager → Phone numbers. The display name is what your chat UI shows above each thread — a short label like “WhatsApp” or “Guest inbox”.
Callback URL + Verify Token — auto-generated below
Paste into Meta
After you save the config below, scroll down to Meta Dashboard values. Copy the Callback URL and Verify Token and paste them into Meta App Dashboard → WhatsApp → Configuration → Webhook → Edit. Meta verifies immediately by hitting our /whatsapp.ashx?action=webhook with hub.mode=subscribe; on success the panel turns green. Then subscribe to the fields listed lower down on this page (messages is the essential one).
Order matters. Fill and save steps 1–5 before pasting the Callback URL into Meta — the webhook handshake fails if the App ID hasn’t been saved on our side yet (we look it up per tenant to verify the X-Hub-Signature-256 header).
Tenant configuration
Values from App_Data/<tenant>/chat-whatsapp/config.json. Secrets are masked on load and only sent when the field is edited.
Rotate the App Secret in the Meta Dashboard once initial setup works — if any Secret has been sent through a chat/support channel, treat it as leaked.
Real inbound needs a published app
While your Meta App is in unpublished / Development mode, Meta will not forward real WhatsApp messages to this webhook — only synthetic events fired from the Meta Dashboard’s Send test webhook button. To receive real customer messages, you need to complete App Review and publish the app (which in turn requires Business Verification). Outbound send is not affected — it works pre-publish as long as the recipient is on the allowed-tester list.
Webhook subscriptions
In the Meta App Dashboard → WhatsApp → Configuration → Webhooks, subscribe to these WhatsApp Business Account fields. Only messages is required for the chat bridge; the rest are recommended so operational events (template approvals, quality drops, account alerts) land in the audit log.
Field
Purpose
Priority
Our handling
Tip. A successful subscription requires the callback URL and verify token to match on both sides. Meta’s dashboard verifies immediately by sending a GET to our webhook with hub.mode=subscribe. If it fails, check the Verify Token above matches character-for-character what you paste in the Meta Dashboard.
Test send
Sends a text message via POST /whatsapp.ashx?action=send. Requires Phone Number ID and Access Token to be filled in.
Recent activity (last 60 events)
From the tenant audit log at chat-whatsapp/audit/*.jsonl. Inbound = webhook events from Meta. Outbound = replies you sent.