Setup guide for the five plugin fields (Automation → Plugins → Whatsapp messages), plus what has to exist on the Meta side first. Screenshots come from the app used for testing (Automation messages).
| Plugin field | Where it comes from in Meta |
|---|---|
| Access token | A long-lived system user token — see step 2. The token on Step 1. Try it out is temporary (24 h) and is only good for a quick manual test. |
| WhatsApp Business Account ID | App → Use cases → Connect on WhatsApp → Step 1. Try it out → WhatsApp Business account ID |
| Phone number ID | Same panel → Phone Number ID (the numeric ID, not the phone number) |
| App secret | App → App settings → Basic → App secret → Show |
| Webhook verify token | Any string you pick. The same value must be entered in Meta (see step 5). |
0. Before you start — create the Meta app
Everything below assumes a Meta app that already has the WhatsApp use case, a WhatsApp Business Account and a phone number. If you are starting from nothing, this part comes first.
0.1 — Business portfolio. The app and the WhatsApp Business Account both hang off a business portfolio on business.facebook.com. Create one if the account does not have it yet.
0.2 — Create the app. developers.facebook.com → My Apps → Create App. Give it a name and a contact email.
The app name cannot contain the word "whatsapp" — Meta rejects its own trademarks in app names. Use something like Automation messaging instead.
0.3 — Pick the use case. On the next step tick Connect with customers through WhatsApp, then finish the wizard. This is what adds the Connect on WhatsApp section that every later step lives in.
0.4 — WhatsApp Business Account and phone number. During that use case setup Meta either creates a new WhatsApp Business Account (WABA) or connects an existing one, and gives you a test number to play with. The test number can only message a handful of pre-registered recipients, so for real traffic register your own number: Use cases → Connect on WhatsApp → Step 2. Production setup → Register your WhatsApp phone number. Add a payment method in the same panel — without one, only replies inside the 24 h customer-service window go out and campaign sends fail.
0.5 — Business verification and publishing the app. Step 3. Business verification is required to leave the test-number tier, and the app itself has to be published. While it is unpublished Meta only delivers the Test webhooks triggered from the app dashboard, so no delivery receipts and no unsubscribes reach the instance.
1. WhatsApp Business Account ID and Phone number ID
App → Use cases → Connect on WhatsApp → Step 1. Try it out. Both IDs sit next to the number. The same panel also has the temporary token, if you only want to smoke-test the API.
2. Access token — use a long-lived system user token
business.facebook.com → Settings → Users → System users → pick (or add) the system user → Generate token.
Assign both the app and the WhatsApp Business account to that system user first, otherwise the token cannot send. Required permissions: whatsapp_business_messaging and whatsapp_business_management. A system user token does not expire, unlike the 24 h token from Step 1. Try it out.
3. App secret
App → App settings → Basic → App secret → Show.
This one is mandatory. The webhook signature check fails closed: with a missing or wrong app secret every delivery from Meta is answered with 403 Invalid signature, so delivery receipts and unsubscribes are silently dropped.
4. Callback URL and verify token (Meta side)
App → Use cases → Connect on WhatsApp → Step 2. Production setup → Configure Webhooks.
-
Callback URL:
https://<instance-domain>/whatsapp/message/callback - Verify token: the same string as the plugin's Webhook verify token field
- Press Verify and save. Meta calls the URL with
hub.mode=subscribe&hub.verify_token=…&hub.challenge=…and the plugin echoes the challenge back when the token matches.
Note that an app has a single callback URL. Pointing it at an instance means any ngrok tunnel used for local development stops receiving webhooks.
5. Webhook field subscription (Meta side)
In the same panel, under Webhook fields, subscribe to messages only. Delivery statuses (sent / delivered / read / failed) and button replies (unsubscribe) both arrive under that field, and the plugin ignores everything else.
Gotchas
- The app has to be published (step 0.5). In development mode only dashboard Test webhooks are delivered, not real traffic.
- App secret is not optional — see step 3.
- Do not use the temporary token in an instance configuration. It dies after 24 h and sends start failing with an auth error.
- A payment method is required for business-initiated messages, which is what campaign sends are.
Comments
0 comments
Please sign in to leave a comment.