WhatsApp Business API & Cloud API
How to Send WhatsApp Template Messages
Send approved WhatsApp templates from your backend with dynamic parameters, media headers, and business workflow data.
Step 1
What You Need
Before sending a template message, you need a registered WhatsApp business phone number, the sending Phone Number ID, a server side access token with the required messaging permission, and an approved template available in the language you plan to send.
Also prepare the customer data used by template variables. Your backend should know the exact template name, language code, component structure, and parameter order before the request is built. Test with a simple approved template first so authentication and phone configuration are already proven.
Implementation Checklist
- Confirm the business phone number is registered and usable in Cloud API.
- Store the access token and Phone Number ID in server side configuration.
- Check the template's exact approved name and language.
- Prepare validated values for every required variable, header, or button parameter.
Step 2
Find the Template Name And Language
The language configured for a template becomes part of its identity when you send it. Your API request must use a language code that exists for the approved template. Do not assume that changing the language code automatically translates the template or falls back to another version.
If you serve customers in multiple languages, create and review the required language variants intentionally. Store the customer's preferred language in your CRM or customer record and select the matching approved template at send time.
Implementation Checklist
- Use the exact approved template name and language code in API requests.
- Validate every dynamic value before building the template payload.
- Keep template purpose and category aligned with the actual customer communication.
- Test a simple approved template before adding media, dynamic URLs, or multiple variables.
Step 3
Understand Template Components
Templates should be designed around a clear business purpose and stable variable structure. Decide what part of the message is fixed, what data is dynamic, and which actions the recipient needs before creating the template in WhatsApp Manager.
Keep names predictable and use a consistent internal naming convention. Your backend will refer to the template name and language exactly, so clear names make deployments, debugging, and CRM mappings easier.
Implementation Checklist
- Use the exact approved template name and language code in API requests.
- Validate every dynamic value before building the template payload.
- Keep template purpose and category aligned with the actual customer communication.
- Test a simple approved template before adding media, dynamic URLs, or multiple variables.
Step 4
Send A Basic Template
To send a template, your backend posts to the same messages endpoint used for other outbound WhatsApp messages, but the type is template. The payload identifies the approved template by name and language and supplies component parameters when the template contains variables, media, or dynamic buttons.
Keep template selection separate from customer data. First decide which approved template and language applies, then build the parameter values from validated CRM or workflow data. This reduces the chance of sending the wrong content to the right customer or the right template with the wrong values.
Implementation Checklist
- Use the exact approved template name and language code in API requests.
- Validate every dynamic value before building the template payload.
- Keep template purpose and category aligned with the actual customer communication.
- Test a simple approved template before adding media, dynamic URLs, or multiple variables.
Template message payload
{
"messaging_product": "whatsapp",
"to": "<RECIPIENT_PHONE_NUMBER>",
"type": "template",
"template": {
"name": "<APPROVED_TEMPLATE_NAME>",
"language": { "code": "<LANGUAGE_CODE>" }
}
}Step 5
Pass Dynamic Variables
Pass Dynamic Variables is part of building the template request body. The payload must mirror the approved template structure, including the exact language and any component parameters expected by headers, body variables, or buttons.
Build template parameters from validated business data and keep the mapping in one place. That way, when a template changes, you update one mapping instead of finding parameter arrays scattered across CRM jobs, order workflows, and campaign code.
Implementation Checklist
- Use the exact approved template name and language.
- Build parameters in the same component order the template expects.
- Validate dynamic values before calling the API.
- Store the returned message ID so delivery statuses can be tracked later.
Step 6
Send Media Header Templates
A template header can use supported content such as text or media depending on how the template was created. When a media header is expected, the API request must include the corresponding header parameter with a valid media reference or URL in the structure required by the message API.
Validate media before sending. A URL that is private, expired, blocked, or returns the wrong content type can cause the message request to fail even when the template name and body parameters are correct.
Implementation Checklist
- Use the exact approved template name and language code in API requests.
- Validate every dynamic value before building the template payload.
- Keep template purpose and category aligned with the actual customer communication.
- Test a simple approved template before adding media, dynamic URLs, or multiple variables.
Step 8
Send a WhatsApp Template From Node.js
Once the template works in a direct API test, move the request into a server side messaging function. Keep the token, Phone Number ID, and Graph API version in environment variables, and pass only validated recipient and template data into the function.
The example below sends an approved template without dynamic components. Add the components array only when the approved template expects body variables, media, or dynamic button parameters.
Node.js Example
const response = await fetch(
`https://graph.facebook.com/\${process.env.META_GRAPH_VERSION}/\${process.env.WHATSAPP_PHONE_NUMBER_ID}/messages`,
{
method: "POST",
headers: {
Authorization: `Bearer \${process.env.WHATSAPP_ACCESS_TOKEN}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
messaging_product: "whatsapp",
to: recipient,
type: "template",
template: {
name: templateName,
language: { code: languageCode },
},
}),
}
);
const data = await response.json();
if (!response.ok) {
throw new Error(data?.error?.message || "WhatsApp template request failed");
}
const messageId = data?.messages?.[0]?.id;Implementation Checklist
- Keep all Meta credentials on the server.
- Validate the template name, language, recipient, and dynamic values before the request.
- Store the returned message ID for webhook status tracking.
- Log sanitized API errors with enough context to reproduce the failed template request.
Step 9
Handle API Errors
Debug one failing layer at a time. Capture the exact request or event, HTTP result, structured error, message ID, and configuration involved, then compare it with a known successful baseline before changing another part of the integration.
Implementation Checklist
- Reproduce one controlled failure.
- Log safe identifiers and structured errors.
- Change one layer at a time and retest the same case.
This guide only covers the part needed for the current workflow. For the complete setup, examples, and troubleshooting, continue with How to Debug a WhatsApp Cloud API Integration.
Step 10
Track Delivery Status
The initial send response is not the final delivery result. Store the outbound WhatsApp message ID and update that record when webhook events report sent, delivered, read, or failed states.
Implementation Checklist
- Match events by WhatsApp message ID.
- Store timestamps and failure details.
- Make repeated status events safe to process.
This guide only covers the part needed for the current workflow. For the complete setup, examples, and troubleshooting, continue with WhatsApp Cloud API Message Statuses Explained.
Related Guides
Continue Learning
Need Implementation Help?
Need Help With Your WhatsApp or Automation Project?
If you need help building, integrating, troubleshooting, or improving a production system, you can discuss the project with me directly.