Send template messages to WhatsApp users via the WhatsApp Business Platform (Cloud API). Use Zeotap to send transactional notifications, marketing campaigns, and personalized messages at scale through approved WhatsApp message templates.
Prerequisites
- A Meta Business Account with WhatsApp Business Platform access
- A registered WhatsApp Business phone number
- At least one approved message template in your WhatsApp Business Account
- A permanent access token from a Meta System User with
whatsapp_business_messagingpermission
Permissions
The System User access token must have the following permission:
whatsapp_business_messaging— required to send messages via the Cloud API
Authentication
Permanent Access Token
- In Meta Business Suite, navigate to Business Settings > System Users
- Create a new System User (or select an existing one) with Admin access
- Click Generate New Token
- Select the WhatsApp Business app
- Grant the
whatsapp_business_messagingpermission - Copy the generated token
- In Zeotap, paste the token into the Access Token field
Permanent tokens do not expire but can be revoked. Store them securely and rotate periodically.
Configuration
| Field | Type | Required | Description |
|---|---|---|---|
| Phone Number ID | Text | Yes | The WhatsApp Business phone number ID that sends messages. Find this in Meta Business Suite > WhatsApp Manager > Phone Numbers |
| API Version | Select | Yes | Meta Graph API version to use. Default: v21.0 |
Target Settings
| Field | Type | Required | Description |
|---|---|---|---|
| Template Name | Text | Yes | The name of the approved WhatsApp message template to send (e.g., hello_world) |
| Template Language | Text | Yes | The language code for the template (e.g., en_US, es, pt_BR). Default: en_US |
Supported Operations
Sync Modes
| Mode | Supported |
|---|---|
| Insert | Yes |
| Upsert | — |
| Update | — |
| Mirror | — |
Audience Sync Modes
| Mode | Supported |
|---|---|
| Add | Yes |
| Remove | — |
| Mirror | — |
| Upsert | — |
Features
- Field Mapping: Yes — map source columns to template parameters
- Schema Introspection: No — WhatsApp templates are configured externally in Meta Business Manager
Required Mapping Fields
| Field | Description |
|---|---|
Recipient Phone Number (to) | The recipient’s WhatsApp phone number in E.164 format (e.g., +14155551234) |
Default Destination Fields
| Field | Type | Description |
|---|---|---|
to | string | Recipient phone number in E.164 format |
header_text | string | Text parameter for the template header component |
body_param_1 through body_param_5 | string | Positional parameters for the template body (matched in order) |
button_payload_1 through button_payload_3 | string | Payloads for quick reply button components |
How It Works
Zeotap sends one WhatsApp template message per row of data:
- For each row, the Recipient Phone Number (
to) field determines who receives the message - Template parameters are populated from mapped fields:
body_param_1,body_param_2, etc. map to{{1}},{{2}}, etc. in the template - The message is sent via
POST /{phone_number_id}/messageson the WhatsApp Cloud API - WhatsApp delivers the rendered template message to the recipient
Template Parameters
WhatsApp templates use positional parameters ({{1}}, {{2}}, etc.) in the body and optional header/button components:
- Header: Map a source column to
header_textto populate a text header parameter - Body: Map source columns to
body_param_1,body_param_2, etc. — these fill{{1}},{{2}}, etc. in order - Buttons: Map source columns to
button_payload_1,button_payload_2, etc. for quick reply button payloads
Example
For a template named order_confirmation with body text:
Hi {{1}}, your order #{{2}} has been shipped and will arrive by {{3}}.Map your source columns as:
| Source Column | Destination Field |
|---|---|
customer_phone | to |
customer_name | body_param_1 |
order_id | body_param_2 |
delivery_date | body_param_3 |
Batch Processing
Messages are sent individually (the WhatsApp Cloud API does not support batch sending). Zeotap uses retry logic with exponential backoff for transient failures (HTTP 429, 5xx). Each failed message is tracked individually in sync run results.
Rate Limits
WhatsApp Cloud API has the following throughput limits:
| Tier | Messages Per Second |
|---|---|
| Default | 80 per phone number |
| Upgraded (eligible accounts) | 1,000 per phone number |
To qualify for the higher throughput tier, the business phone number must message 100K+ unique users in a 24-hour period and maintain a Medium or higher quality rating.
Additionally, WhatsApp enforces messaging limits at the business portfolio level that control how many unique users you can message in a 24-hour rolling window. These limits increase automatically as you send more messages and maintain quality.
Best Practices
- Use approved templates only — WhatsApp requires pre-approved templates for business-initiated messages. Messages with unapproved templates will fail.
- E.164 phone format — Always include the country code with a
+prefix (e.g.,+14155551234). Numbers without proper formatting will be rejected. - Monitor quality rating — WhatsApp tracks message quality based on user feedback. Low ratings can restrict messaging. Check quality in Meta Business Suite > WhatsApp Manager.
- Start with low volume — New phone numbers have limited messaging tiers. Gradually increase volume to unlock higher tiers.
- Template parameter count must match — The number of
body_param_Nfields mapped must exactly match the number of parameters in the template body. Missing or extra parameters cause delivery failures.
Troubleshooting
Message not delivered
Verify the recipient’s phone number is a valid WhatsApp number in E.164 format. The number must have an active WhatsApp account. Check the sync run logs for per-row error details from the WhatsApp API.
Template not found
Ensure the template name in Target Settings exactly matches the name in Meta Business Manager > WhatsApp > Message Templates. Template names are case-sensitive. Also verify the language code matches an approved translation of the template.
Authentication failed (401)
The access token may be invalid or expired. Generate a new permanent token from Meta Business Suite > System Users. Ensure the token has the whatsapp_business_messaging permission and is associated with the correct WhatsApp Business Account.
Rate limited (429)
You are exceeding the per-phone-number throughput limit (default: 80 messages/second). Zeotap automatically retries with backoff on 429 responses. To increase throughput, request an upgrade to 1,000 messages/second through Meta Business Support if eligible.
Parameter count mismatch
The WhatsApp API rejects messages when the number of body parameters does not match the template. Count the {{N}} placeholders in your template and map exactly that many body_param_N fields. Unused parameter fields (beyond what the template expects) cause errors.
Phone number not registered
The Phone Number ID must correspond to a phone number registered in the WhatsApp Business Platform. Verify the ID in Meta Business Suite > WhatsApp Manager > Phone Numbers. The phone number must be in Connected status.
Messaging limit reached
WhatsApp enforces a rolling 24-hour limit on unique recipients. If you hit this limit, new messages to previously unreached users will fail. Wait for the window to reset or request a tier increase by maintaining high message quality and volume.