Template Message
Send personalized WhatsApp messages using pre-approved templates
Templates enable personalized communication while ensuring compliance with WhatsApp’s business policies. This API lets you send template-based messages to your customers with dynamic content.
WhatsApp requires businesses to use pre-approved templates for initiating conversations. This API allows you to send template messages with personalized variables, media attachments, and interactive components to your customers.
Overview
The Send Template Message API enables you to:
- Send WhatsApp messages using your pre-approved templates
- Dynamically replace variables with personalized content
- Attach media (images, videos, documents) when supported by the template
- Include interactive elements like buttons and quick replies
- Track delivery status through WhatsApp response information
Try it in the API Reference
Experiment with the Send Template Message API and view responses in real-time
Send Template Message
Send a personalized WhatsApp template message to a specific phone number.
Endpoint
Authentication
All API requests require authentication using your API key. Never share your API keys in client-side code.
Include your API key in all requests using Bearer authentication:
Request Body
The unique identifier of the template to use. You can retrieve this from the Get Templates API.
The recipient’s phone number in international format with country code (e.g., “+123456789012”).
Object containing key-value pairs for template variables. The keys must match the variable names defined in your template.
The language code for the template. Must match one of the languages your template is approved for.
Response
The API returns a detailed response indicating whether the message was accepted for delivery and provides WhatsApp message identifiers for tracking.
Indicates if the request was successfully processed
Details from the WhatsApp Business API about the message delivery
Example Request
Example Response
Response Codes
200: Success
200: Success
Your request was successful and the message has been accepted for delivery.
400: Bad Request
400: Bad Request
The request was invalid. Check the error message for details.
401: Unauthorized
401: Unauthorized
403: Forbidden
403: Forbidden
Your account doesn’t have permission to send messages.
404: Not Found
404: Not Found
The template specified doesn’t exist.
422: Unprocessable Entity
422: Unprocessable Entity
The request was well-formed but contains invalid parameters.
429: Too Many Requests
429: Too Many Requests
You’ve exceeded the rate limit. Implement exponential backoff in your requests.
500: Server Error
500: Server Error
Something went wrong on our end. Please contact support if the issue persists.
Working with Template Variables
Templates contain placeholders that are replaced with dynamic content when sending messages. Understanding how to map your data to these variables is essential.
Variable Types
Text Variables
Body and header variables replace text placeholders in your template. They are named body1
, body2
, etc., or header1
, header2
, etc.
Media Variables
Media variables allow you to attach images, videos, or documents to your template. Provide a public URL in the media
property.
Button Variables
Used for dynamic buttons in interactive templates. Can be URLs or text, depending on the button type.
Quick Reply Variables
For templates with quick reply buttons, provide the text to display on each button.
Variable Mapping
Identify template variables
Examine your template structure to identify which variables are required. You can find this information using the Get Templates API.
Prepare your data
Format your data to match the expected variable structure. Ensure values meet any length or format requirements.
Map data to variables
Create a variables
object with keys matching your template’s variable names and values from your data.
Handle media properly
For media templates, ensure your media URL is publicly accessible and in a WhatsApp-supported format.
Media Guidelines
When including media in your templates, follow these guidelines for optimal delivery:
Images
- Supported formats: JPG, JPEG, PNG
- Max size: 5MB
- Recommended aspect ratio: 1.91:1
Videos
- Supported formats: MP4, 3GPP
- Max size: 16MB
- Max duration: 1 minute
Documents
- Supported formats: PDF, DOC, DOCX, PPT, PPTX, XLS, XLSX
- Max size: 100MB
URLs
- Must be publicly accessible
- Direct file links (no redirects)
- HTTPS required
Media URLs must be publicly accessible without requiring authentication. For security, we recommend using signed URLs with limited-time access.
Best Practices
Error Handling
Implement comprehensive error handling to manage API failures gracefully. Always check the success
field in responses and handle various error scenarios.
Message Tracking
Store the returned message_id
values to track delivery status using the Message Status API.
Throttling
Implement request throttling when sending to multiple recipients to avoid hitting rate limits and ensure reliable delivery.
Template Testing
Test your templates with various inputs to ensure variables are correctly replaced and messages appear as expected.
FAQs
Why was my message not delivered?
Why was my message not delivered?
Messages may fail to deliver for several reasons: invalid phone number, recipient has blocked your WhatsApp Business number, template issues, or WhatsApp temporary service interruptions. Check the error code returned for specific details.
Can I send to non-WhatsApp users?
Can I send to non-WhatsApp users?
No, recipients must have an active WhatsApp account associated with the phone number you’re sending to.
How do I know if my message was delivered?
How do I know if my message was delivered?
The initial response only confirms that WhatsApp accepted the message. For actual delivery status, implement webhook handling using our Webhooks API or query the Message Status API.
Can I edit a message after sending?
Can I edit a message after sending?
No, WhatsApp messages cannot be edited once sent. You would need to send a new message with the corrected information.
Need help?
Our support team is available 24/7 to assist with template issues, API integration, or any other questions.