What it is
Meta’s official Cloud API — no ban risk, but Meta decides what may be sent. Proactive delivery requires an approved template.
This channel is in beta: it works, but has not yet been exercised in production by many customers. Tell us what you find.
Set up
About 20 minutes to a working channel.
- 01Create a Business app on Meta. developers.facebook.com → My Apps → Create App → type Business. You need a Meta Business account; creating one takes a couple of minutes.
- 02Add the WhatsApp product and open API Setup. That screen shows the Phone number ID (copy it) and a temporary access token valid for 24h — good enough for the first test, not for production.
- 03Register your own number under “To”. While the app is in test mode Meta only delivers to numbers verified in that list. Skipping this is the most common cause of “it says sent but nothing arrived”.
- 04Generate a permanent token. Business Settings → Users → System Users → create one → Add Assets (your WhatsApp app) → Generate new token with the whatsapp_business_messaging permission. That one does not expire.
- 05Create a template and get it approved. WhatsApp Manager → Message templates. The body can declare as many parameters as you like, or none — the Template parameters field below says what fills each. To attach the report file the template must also declare a DOCUMENT header. Approval takes minutes to hours.
- 06Fill the fields here, then Test. Test validates the token and the phone number id against the Graph API without sending a message. The real send happens when a report runs.
Fields
| Field | Required | What it is |
|---|---|---|
| Phone Number ID | Yes | Meta app → WhatsApp → API Setup. It is a number id, not the phone number itself. (1234567890) |
| Access token | Yes | Temporary token from API Setup (24h) for a first test, or a permanent System User token for production. |
| API version | No | Graph API version. Leave v21.0 unless Meta deprecates it. (v21.0) |
| Approved template | No | Required for proactive sends. How many parameters the body declares is up to you — the field below says what fills each. A DOCUMENT header is needed when the report produces a file (CSV/XLSX/PDF), and unnecessary when it is Inline HTML. Empty means free-form text, which Meta delivers only inside the 24h window. (report_ready) |
| Template language | No | Meta language code of the approved template, e.g. pt_BR or en_US. A mismatch here comes back as “template not found”, which points at the name and not the language. Left blank it falls back to en_US. (pt_BR) |
| Template parameters | No | One line per body parameter of the approved template: line 1 fills {{1}}, line 2 fills {{2}}, and so on. Use {{message}} for the report copy, plus any report placeholder — {{report_name}}, {{rows}}, {{result_summary}}, {{date}}. Meta refuses the send when the count differs from what the template declares (error 132000). Left blank it sends one parameter carrying the whole message, which is right for a template written as a bare {{1}}; a single - means the template takes no parameters at all, which is right for one whose body is fixed text. ({{message}}) |
What goes in Target
The recipient phone in international format, digits only: 5511999999999. No plus sign, spaces or dashes — anything else is stripped before the call.
Target is required for this channel: a route without one never leaves. — 5511999999999
Test
Every channel has a Test button in the channel list (Settings → Channels). The result is kept — date, status and the provider's error when there was one — and a channel that was never tested is marked in the list.
Test validates the access token and the phone number id against Meta without sending a message. The first real delivery is what proves the template and the 24-hour window.
Check it end to end
- 01Report: open a report, add this channel under Destinations (with the Target when the channel needs one), click Run now and open the run. The log says which channel each recipient went through and what the provider answered.
- 02Alert: under Monitoring → Alert routes, create a route with this channel as an escalation step. Routes match on severity and source; the first match wins.
- 03To fire an alert without breaking anything: create an HTTP monitor pointing at a URL that returns an error (for example https://httpstat.us/500) with a short interval. When it goes down the alert leaves through the route; delete the monitor afterwards. The message carries an acknowledge link — click it and the escalation stops.
- 04Report rules (new rows, value out of range) arrive through the same route, with source "report rule".
What most often goes wrong
Outside the 24h customer-service window Meta only delivers approved templates. With Approved template empty a report goes out as free-form text, which means it reaches almost nobody and reports no error; a campaign refuses to send rather than pretend. It is Meta’s rule, not a DataRunner bug.