WhatsApp Business

Datafly Signal sends WhatsApp marketing template messages server-to-server using Meta’s Marketing Messages API (MM Lite). Instead of firing a client-side pixel, Signal triggers an approved WhatsApp template off the back of a first-party event — for example sending an order confirmation when an Order Completed event arrives, or an abandoned-cart reminder after Checkout Started.

MM Lite is send-only and accepts marketing templates exclusively. The recipient must have opted in to marketing messages, the template must be pre-approved in WhatsApp Manager, and every send is a billable WhatsApp marketing conversation.

Prerequisites

Before configuring WhatsApp Business in Signal, you need a WhatsApp Business Account (WABA), a registered phone number, an approved marketing template, and a system-user access token.

Create a WhatsApp Business Account

In Meta Business Suite, go to Business Settings > Accounts > WhatsApp Accounts.
Create or select a WhatsApp Business Account and add a phone number.
Complete phone-number verification.

Find your Phone Number ID

Open WhatsApp Manager > API Setup.
Note the Phone Number ID (a numeric ID like 1059xxxxxxxxxxx). This is not the display phone number.

Create a System User and Access Token

System users provide long-lived tokens for server-to-server integrations.

Go to Business Settings > Users > System Users and add a system user with the Admin role.
Click Add Assets, select your WhatsApp Business Account, and grant full control.
Click Generate New Token, select the whatsapp_business_messaging permission, and copy the token.

⚠️

Store this token securely — it is shown only once. Use a long-lived system-user token, never a temporary one.

Create and approve a Marketing template

In WhatsApp Manager > Message Templates, click Create Template and choose category Marketing.
Add body text with positional placeholders, e.g. Hi, your order {{1}} for {{2}} is confirmed.
Submit for review and wait until the status is Approved.
Note the template name (e.g. order_confirmation) and its language (e.g. en_GB).

Enrol in Marketing Messages (MM Lite)

MM Lite is enabled per WhatsApp Business Account. Confirm in WhatsApp Manager that the Marketing Messages API is available for your phone number. If it is not, you can still send via the standard Cloud API endpoint, but without MM Lite’s delivery optimisation.

Configuration

Field	Required	Description
`phone_number_id`	Yes	Your WhatsApp Business phone number ID (numeric), from WhatsApp Manager > API Setup.
`access_token`	Yes	System-user access token with the `whatsapp_business_messaging` permission.
`template_name`	Yes	Name of an approved Marketing template. Its `{{1}}`, `{{2}}`, … placeholders must match the parameters Signal sends. Can be overridden per event.
`default_language`	Yes	The template’s language code (e.g. `en_GB`, `en_US`, `es_ES`). Must match the approved template.
`api_version`	No	Graph API version for the endpoint path (e.g. `v23.0`). Defaults to a recent version.

Configure in Signal

Go to Integrations > Add Integration > WhatsApp Business.
Enter your phone_number_id, access_token, template_name, and default_language.
Select the consent category marketing — Signal only sends WhatsApp messages to users who have granted marketing consent.
Click Save.

The default preset maps four events to templates. Edit the integration’s Field Mappings to point each event at a different approved template or to add positional parameters.

Signal event	WhatsApp template (config-driven)	Body parameters
`Order Completed`	`order_confirmation`	order id, order total
`Order Shipped`	`shipping_update`	order id, carrier, tracking number
`Checkout Started`	`abandoned_cart`	cart value
`Signed Up`	`welcome`	first name

API Endpoint

POST https://graph.facebook.com/{api_version}/{phone_number_id}/marketing_messages
Authorization: Bearer {access_token}
Content-Type: application/json

MM Lite uses the same request body as the Cloud API send-message endpoint; only the path differs (/marketing_messages instead of /messages).

Identity Signals

WhatsApp must deliver the message to a real handset, so the recipient phone number is sent in cleartext E.164 (digits only, no +) — it is never hashed.

Signal	Field	Description
Recipient phone	`to`	Sourced from the user’s `phone` trait, normalised to digits-only E.164 (e.g. `447700900123`). Sends are skipped when no phone is present.
Tracking id	`biz_opaque_callback_data`	Set to Signal’s `anonymous_id`. WhatsApp echoes this back in delivery and read webhooks so you can attribute outcomes to the originating event.

Set the recipient by calling datafly.identify() with a phone number when the user opts in:

datafly.identify("user-123", {
  phone: "+44 7700 900123",
  firstName: "Jane"
});

Signal normalises the number to 447700900123 before sending.

⚠️

Only send to users who have explicitly opted in to WhatsApp marketing. Signal gates every send on the marketing consent category, but you are responsible for capturing and recording opt-in.

Event Mapping

Example: Order confirmation

Datafly.js call:

datafly.identify("user-123", { phone: "+44 7700 900123" });
 
datafly.track("Order Completed", {
  order_id: "ORD-001",
  revenue: 129.99,
  currency: "GBP"
});

WhatsApp MM Lite payload sent by Signal:

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "447700900123",
  "type": "template",
  "biz_opaque_callback_data": "a1b2c3d4e5f6",
  "template": {
    "name": "order_confirmation",
    "language": { "code": "en_GB" },
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "ORD-001" },
          { "type": "text", "text": "129.99" }
        ]
      }
    ]
  }
}

The positional parameters fill the template’s {{1}}, {{2}}, … placeholders in order. The number of parameters must match the approved template exactly, or WhatsApp rejects the message.

Testing

Add a test phone number that has opted in to marketing messages from your business.
Trigger the event from your site (e.g. complete a test order) with that number set via datafly.identify().
The message should arrive on the handset within seconds.
Inspect delivery in WhatsApp Manager > Insights, and check Signal’s event debugger for the request/response.
Confirm the biz_opaque_callback_data value appears in your Cloud API delivery webhook for attribution.

Troubleshooting

Problem	Solution
`(#132000) template name does not exist`	The `template_name` / language does not match an approved template. Check the exact name and `default_language` in WhatsApp Manager.
`(#132012) parameter count mismatch`	The number of body parameters sent does not match the template’s `{{n}}` placeholders. Adjust the Field Mappings.
`(#131047) re-engagement message` / `(#470)` outside marketing window	The recipient has not opted in or is outside the allowed marketing window. Confirm opt-in.
`(#190)` / `OAuthException`	The access token is invalid, expired, or lacks `whatsapp_business_messaging`. Regenerate the system-user token.
`404` on the endpoint	Wrong `phone_number_id` or `api_version`, or the account is not enrolled in MM Lite (try the Cloud API `/messages` path).
No message sent, no error	The user has no `phone` trait or has not granted marketing consent — Signal skips the send.

Rate Limits

WhatsApp Cloud / MM Lite sustains up to ~500 messages per second per phone number; Signal throttles conservatively below that ceiling. Marketing message volume is also governed by your account’s per-number messaging tier, which scales with quality and engagement.

ClickSend Loops