WhatsApp onboarding

The path from “no Meta app” to a WhatsApp channel that sends approved template messages and receives delivery receipts. Meta’s free test number gets you sending in about 15 minutes; a production number needs Meta business verification, which takes days.

1. What you are building & the two paths

When you finish, you’ll have a WhatsApp channel that sends business-initiated messages through Meta’s WhatsApp Cloud API using Meta-approved message templates, and receives delivery receipts on a signed callback, so the Logs tab shows what actually reached the recipient.

• Free test number. Every new WhatsApp app gets a free test sender. No business verification, no number of your own, no cost. It can message up to 5 recipient numbers you verify, and Meta’s pre-approved hello_world template works out of the box — which is exactly what ImpulseNotify’s Test send uses.
• Production number. Your own number as the sender, your business display name, higher messaging limits, and Meta billing. Traffic beyond the unverified limit (around 250 conversations a day) needs Meta business verification.

Do the test-number path first

It exercises every moving part — token, app secret, webhook and templates — with nothing at stake, and all of it carries over. Going to production later only changes the phone number.

Templates for your own events

This release ships one WhatsApp template link: the diagnostics test message, pointing at hello_world. The admin area can’t yet link your own approved templates to WHMCS events or to client contact verification. Until it can, a rule that routes an event to WhatsApp skips it for lack of a template, and clients can’t verify a WhatsApp number — the client area tells them verification isn’t available. Test sends and manual or bulk messages work; they go out as the approved test template, not as your typed text. For billing, order, ticket and service notices today, see Templates.

You collect these items, each mapping to a field on the channel form:

Field	Where it comes from
App ID	Part A — App settings → Basic (needed for Auto-configure)
Phone number ID	Part B — the API Setup page (a long number, not the phone number itself)
WhatsApp Business Account ID	Part B — the API Setup page
Access token (permanent)	Part C — a system user
App secret	Part D — App settings → Basic
Webhook verify token	Part E — a string you invent, or one Auto-configure generates

2. Part A — Meta developer account and app

Everything lives inside a Meta app — a container for credentials and webhook settings that your customers never see.

1. Go to developers.facebook.com, sign in, and register as a developer.
2. Link your Meta Business portfolio, or create one under your legal company name — this is the identity Meta verifies later, so use the real one from the start.
3. Create an app of type Business (only Business apps can add WhatsApp). Name it after your company and its job, for example Acme Hosting Notifications.
4. Note the numeric App ID under App settings → Basic.

3. Part B — add WhatsApp & copy the IDs

On the app dashboard, add the WhatsApp product. Meta creates a WhatsApp Business Account (WABA) under your portfolio. Open WhatsApp → API Setup — most of this part is on that page:

• The free test number under From works immediately, for up to 5 recipient numbers you verify.
• Phone number ID — a long numeric ID shown with the From number. The module needs this ID, not the +1… display number.
• WhatsApp Business Account ID — also long and numeric, on the same page.

The temporary token expires in 24 hours

The API Setup page’s temporary access token is fine for a first test today, but anything that has to keep working needs the permanent token from Part C. If the channel stops sending a day later with error 190, this token is why.

4. Part C — a permanent access token

The permanent token comes from a system user — a non-human identity in your Business portfolio whose tokens can be set never to expire.

1. Open Meta Business Settings with the right portfolio selected.
2. Under Users → System Users, add a system user (for example notifications-sender) with the Admin role.
3. Assign your app to it as an asset, with full control.
4. Generate a new token for your app, set to never expire, with both permissions: whatsapp_business_messaging (sending) and whatsapp_business_management (template sync and Auto-configure).
5. Copy the token straight away — Meta shows it once — and paste it into the channel’s Access token field.

Storage & rotation

The token is stored encrypted (AES-256-GCM, keyed to your WHMCS install) and only ever shown masked. To rotate, generate a new token for the same system user, paste it over the mask and save — every secret you leave masked keeps its stored value.

5. Part D — the app secret

The app secret is not the access token. The token lets the module talk to Meta; the app secret lets it check that callbacks claiming to come from Meta really do.

1. In the app dashboard, open App settings → Basic.
2. Reveal the App secret and copy it into the channel’s App secret field.

Meta signs every delivery callback with an X-Hub-Signature-256 header — an HMAC-SHA256 of the raw body keyed with this secret. ImpulseNotify checks that signature before it parses or stores anything. With a wrong app secret, every status update is refused (HTTP 403), your messages stay at sent, and the Rejected signatures (lifetime) counter under Diagnostics → Health Checks climbs.

6. Part E — create the channel

In WHMCS admin, open Addons → ImpulseNotify → Channels and click Add channel (guided), then choose WhatsApp. The wizard walks five steps:

1. Channel type & label — for example “Billing WhatsApp”.
2. Meta app credentials — App ID, App secret and Access token. Saving checks the token with Meta; you only advance when it’s valid.
3. Select WABA & number — the business accounts the token can use and their phone numbers are listed for you to pick; a single option is picked automatically. If discovery can’t list them, paste the IDs from Part B.
4. Webhook — choose I’ve configured it manually — continue for now (see the caution below).
5. Test & enable — run the test send, then enable the channel.

Wire the webhook after the channel is enabled

When Meta saves a webhook it immediately calls your callback URL to verify it, and ImpulseNotify answers only for an enabled channel. A wizard draft stays disabled until Test & enable, so Configure webhook automatically in step 4 — or Auto-configure or Meta’s Verify and save on a draft — fails the handshake. Once the channel is enabled, click Auto-configure on the Channels list, or wire it by hand in Part F.

The Webhook verify token is a shared string Meta echoes back during the webhook handshake — it isn’t a Meta credential. Invent a long random value, or let the module generate one.

The shortcut: Auto-configure

On an enabled WhatsApp channel with App ID, App secret and Access token saved, the Auto-configure button on the channel list (or the channel’s edit form) runs the whole setup: token check → business account discovery → phone number discovery → verify-token generation → webhook subscription → app subscription to the business account → token re-check, reporting each step. If the token can reach several business accounts, or the account has several numbers, it stops and lists them — paste the ID you want into its field, save, and run it again. It’s safe to re-run.

7. Part F — manual webhook wiring

Delivery receipts arrive because Meta POSTs to a URL on your WHMCS server. Auto-configure sets this up; here is what it does, and where to look when a webhook breaks.

Copy the callback URL

Diagnostics → Health Checks → WhatsApp callback endpoints lists a Callback URL for each WhatsApp channel:

<your WHMCS System URL>/modules/addons/impulsenotify/callbacks/whatsapp.php?channel=3

The ?channel= number ties the callback to that channel’s verify token and app secret — copy the URL exactly, query string included. The Verify token column should read set.

Wire it into Meta

1. In the Meta app, open WhatsApp → Configuration and edit the Webhook section.
2. Paste the Callback URL, and in Verify token the same string as the channel’s Webhook verify token — character for character; a trailing space counts. The wizard’s webhook step can reveal the stored token once.
3. Click Verify and save. Meta sends a GET with hub.mode, your hub.verify_token and a random hub.challenge; the endpoint echoes the challenge when the token matches and answers 403 when it doesn’t.
4. Under Webhook fields, subscribe to messages — despite the name it carries the delivery-status updates for your outbound sends, and it’s the only field the module needs.
5. Make sure the app is subscribed to your WhatsApp Business Account — Auto-configure does this; without it, the webhook stays silent.

The URL must be public HTTPS

Meta must reach it from the internet over a valid, not self-signed, certificate — no password prompt, no IP allowlist blocking Meta, and no maintenance page intercepting /modules/ paths. A WHMCS reachable only over a VPN can’t complete the handshake.

8. Part G — your first message

1. Verify a recipient: on Meta’s API Setup page, add your mobile number to the test number’s recipient list and enter the code Meta sends. The free test sender allows up to 5 numbers.
2. Test send: on the Channels tab, enter that number in E.164 form (+15551234567) in your WhatsApp channel’s Test send box, and send.
3. Within seconds the hello_world message arrives. The module shows the provider message id and response time, and the channel status turns ok with a fresh Last test time.

When the delivery receipt for that message comes back, Last verified callback received under Diagnostics → Health Checks → WhatsApp callback endpoints updates — that’s a signed receipt landing. A test send isn’t written to the Logs tab; to see a sent row followed by a delivered row there, send a message from the Manual Message tab. If messages reach the phone but never show delivered, the webhook — not the sending — is what’s broken.

9. Part H — templates & approval status

Meta doesn’t allow freeform business-initiated text: every business-initiated message must use a template Meta approved in advance. ImpulseNotify only ever sends WhatsApp as a template, and checks the template’s approval status when a message is queued — a message whose template isn’t approved at that point isn’t queued.

Create a template in Meta

Open WhatsApp Manager → Message templates and create a template. Choose the category with care:

• Use Utility for billing and service notices — invoices, payments, suspensions, ticket replies — that the customer expects.
• Don’t file transactional notices as Marketing; marketing templates cost more and are throttled harder, and Meta re-categorizes templates it considers mislabelled.

Name templates in lowercase with underscores (for example invoice_due_reminder), pick the language, and write the body with numbered placeholders such as {{1}}, {{2}}. Meta asks for example values and usually decides within minutes to hours; a rejection comes with a reason.

Approval status

Diagnostics → Health Checks → WhatsApp template approval shows each linked template’s status — approved, pending, rejected, paused or not synced. Statuses refresh hourly; Sync WhatsApp templates now pulls them immediately. Only approved templates send. A template’s language is mapped to Meta’s locale automatically (en → en_US, pt → pt_BR, zh → zh_CN).

10. Part I — going to production

Production means your own number, your business name on the message, higher limits, and Meta billing.

• Business verification: start it early in Meta Business Settings. Meta asks for your legal name, address, website and supporting documents, and usually takes a few business days. Nothing else in this part is blocked while you wait.
• Add your number: on WhatsApp → API Setup, add a phone number that can receive an SMS or voice call and isn’t registered with another WhatsApp account, and set its display name (Meta reviews it). The new number has its own Phone number ID — put it in the channel, or re-run Auto-configure and pick it.
• Messaging limits rise automatically as you keep sending messages recipients want, which transactional utility notices are.
• Pricing: Meta bills you directly for WhatsApp messages; ImpulseNotify adds no per-message charge. Meta changes its pricing model from time to time, so check its current WhatsApp pricing before you forecast.

11. Troubleshooting matrix

Symptom	Likely cause / fix
Error 132001 (template not found)	The template isn’t approved on this business account, or the language doesn’t match (en is sent as en_US). For a Test send, the stock hello_world template is missing from the account — restore or re-create it. Check WhatsApp template approval and run Sync WhatsApp templates now.
Error 131030 (recipient not allowed)	You’re on the free test number: add the recipient on Meta’s API Setup page first, or move to a production number.
Error 190 (token expired or invalid)	You’re still on the 24-hour temporary token. Create the permanent system-user token (Part C).
Verify and save fails in Meta	The channel isn’t enabled yet (a wizard draft stays disabled until Test & enable), the verify token doesn’t match exactly (watch for a trailing space), the channel wasn’t saved before verifying, or the callback URL isn’t public HTTPS.
Rejected signatures keeps climbing	Wrong App secret — copy it again from App settings → Basic.
Messages stay sent, never delivered	The messages webhook field isn’t subscribed, or the app isn’t subscribed to the business account. Re-run Auto-configure to repair both.
Rate-limit errors (4, 80007, 130429, 131048, 131056)	Retryable — the module retries automatically with backoff. Persistent throttling points to Meta’s quality rating for your number.
Meta’s webhook log shows HTTP 500	The callback endpoint couldn’t run — usually the ionCube Loader is missing or outdated for the web PHP.
Callback URL reads (SystemURL missing)	Set System URL under WHMCS General Settings.

Confirming it works

After a successful send, the Last verified callback received time under Diagnostics → Health Checks updates — a signed, verified delivery receipt has landed. If it still says never, the webhook subscription, not the sending, is the problem.