Template messages
WhatsApp only allows businesses to send messages outside an active conversation window using pre-approved templates. Templates must be created and approved before use. You can request templates via the Channels portal.
Once a template is approved you can use the template name to send a message (Use the details button in your template overview to find this value).
The template message must have the exact same number of variables as the template has. The same template can be set-up in multiple languages, hence you also need a language parameter.
Please remember that a user must have opted in for the type of communication as well. The opt-in must be an active opt-in. This means it must be triggered by a user action, such as entering a phone number in a WhatsApp field or checking a box to indicate consent.
Before you send: user opt-in
Users must have actively opted in to receive the type of communication you are sending. An active opt-in means it was triggered by a deliberate user action, entering a phone number, checking a consent box or similar.
When collecting opt-ins you must:
- Clearly state that the user is opting in to receive WhatsApp messages from your business.
- Mention your business name explicitly.
- Comply with all relevant local laws and regulations.
- Make it clear what types of messages the user will receive (e.g. order updates, promotions).
- Provide a straightforward way for users to opt out and honour those requests.
Accepted opt-in methods include: SMS, website, within a WhatsApp thread, IVR flow or in-person/paper sign-up.
Quality rating
Meta monitors delivery quality. If users frequently block or report your business, Meta will rate limit your messaging. Monitor your quality rating closely when introducing new opt-in flows or message types.
Template Object
A template object contains a whatsapp object, which corresponds to the template object in the WhatsApp for Business docs.
All template messages share the same base structure. The template object sits inside richContent.conversation[]:
{
"messages": {
"msg": [{
"from": "00316098765432",
"to": [{ "number": "00316012345678" }],
"body": {
"type": "auto",
"content": "Fallback text shown on unsupported clients"
},
"allowedChannels": ["WhatsApp"],
"richContent": {
"conversation": [{
"template": {
"whatsapp": {
"element_name": "<TEMPLATE_NAME>",
"language": {
"policy": "deterministic",
"code": "en"
},
"components": []
}
}
}]
}
}]
}
}
| Field | Description | Required |
|---|---|---|
element_name | The template name. Provided after approval. | Yes |
language | Specifies the language, see below for object definition | Yes |
components | Array of component objects used to personalize the template. Number of variables must match exactly what the template defines. See the WhatsApp documentation for advanced details. | Yes |
Text parameters cannot be empty
The Text parameter within a template cannot be left empty. Doing so will result in an error.
Additionally, ensure the template does not include any newlines (
\n), tabs (\t), carriage returns (\r) or more than 4 consecutive spaces, including these characters will result in an error.
Language
| Field | Description | Required |
|---|---|---|
policy | Always deterministic — Delivers the message template in exact language and locale specified. | Yes |
code | Language or locale code, e.g. en or en_us. See the full list of supported language codes. | Yes |
Categories
Every template must be assigned to one of three categories at creation time. The category affects delivery rules, pricing, and opt-in requirements.
| Category | Typical use |
|---|---|
AUTHENTICATION | Verify a user's identity at any step of the customer journey — OTPs, verification codes, and login confirmations. |
UTILITY | Follow up on user actions or requests — order confirmations, delivery updates, and account alerts. |
MARKETING | Drive business goals from awareness to sales — promotions, offers, product announcements, and re-engagement. |
Miscategorization can result in template rejection or removal. See Meta's categorization guidelines for the full rules.
Components types
Templates are built from one or more components. Not all component types are available in every category.
| Component | Description |
|---|---|
header | Optional. Supports text, media (image, document, video or gif (marketing only, MP4, max 3.5 MB)) and location. |
body | Required. The main message text. Supports variables. |
footer | Optional. Static text shown below the body. Not supported on LTO or coupon templates. |
button | Optional. Supports quick_reply, url, copy_code and flow sub-types. |
limited_time_offer | Limited time offer templates only. Shows an offer expiration countdown. |
Media header template message
Media templates, in addition to the text body, can include a header featuring an image, video, or document, as well as a footer.
The header can have these component types: image, document, video and gif apart from text. The body and footer can only have the component type text and limited to one component per template.
Note
GIFs are currently supported only in the Marketing Messages API. GIFs must be in MP4 format with a maximum file size of 3.5 MB. Larger files will be displayed as video messages.
In the examples below, we send a media header template message.
{
"messages": {
"msg": [
{
"from": "00316098765432",
"to": [
{
"number": "0031612345678"
}
],
"body": {
"type": "auto",
"content": "This is a WhatsApp message"
},
"allowedChannels": ["WhatsApp"],
"richContent": {
"conversation": [
{
"template": {
"whatsapp": {
"element_name": "TEMPLATE_NAME",
"language": {
"policy": "deterministic",
"code": "en"
},
"components": [
{
"type": "header",
"parameters": [
{
"type": "image",
"media": {
"mediaName": "conversational-commerce",
"mediaUri": "https://www.cm.com/cdn/web/nl-nl/blog/conversational-commerce.jpg",
"mimeType": "image/jpeg"
}
}
]
},
{
"type": "body",
"parameters": [
{
//Text cannot be empty, always need to have value
"type": "text",
"text": "replace-value-1"
}
]
}
]
}
}
}
]
}
}
]
}
}
{
"messages": {
"msg": [
{
"from": "00316098765432",
"to": [
{
"number": "0031612345678"
}
],
"body": {
"type": "auto",
"content": "This is a WhatsApp message"
},
"allowedChannels": [
"WhatsApp"
],
"richContent": {
"conversation": [
{
"template": {
"whatsapp": {
"element_name": "document_test",
"language": {
"policy": "deterministic",
"code": "en"
},
"components": [
{
"type": "header",
"parameters": [
{
"type": "document",
"media": {
"mediaName": "terms-and-conditions",
"mediaUri": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
"mimeType": "document/pdf"
}
}
]
},
{
"type": "body",
"parameters": [
{
//text cannot be empty
"type": "text",
"text": "your-body-text"
}
]
}
]
}
}
}
]
}
}
]
}
}
Parameter types
Inside components[].parameters[], the following types are supported:
| Field | Description |
|---|---|
text | Plain text variable. Cannot be empty. |
currency | Localized currency amount. Requires fallback_value, code (ISO 4217) and amount_1000 (amount × 1000). |
date_time | Localized date/time. Requires fallback_value. Optionally accepts day_of_week, year, month, day_of_month, hour, minute, calendar (GREGORIAN or SOLAR_HIJRI) or a timestamp. |
image/document/video | Used in header components. |
payload | Used on quick_reply buttons. Returned in the MO webhook when the user taps the button. Maximum 128 characters. |
coupon_code | Used on copy_code buttons. Maximum 20 characters. |
action | Used on flow buttons. Contains flow_token and optional flow_action_data. |
In the example below, we send a template message.
{
"messages": {
"msg": [
{
"from": "00316098765432",
"to": [
{
"number": "0031612345678"
}
],
"body": {
"type": "auto",
"content": "This is a WhatsApp message"
},
"allowedChannels": ["WhatsApp"],
"richContent": {
"conversation": [
{
"template": {
"whatsapp": {
"namespace": "your namespace id here",
"element_name": "TEMPLATE_NAME",
"language": {
"policy": "deterministic",
"code": "en"
},
"components": [
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "your-text-string"
},
{
"type": "currency",
"currency": {
"fallback_value": "$100.99",
"code": "USD",
"amount_1000": 100990
}
},
{
"type": "date_time",
"date_time": {
"fallback_value": "February 25, 1977",
"day_of_week": 5,
"day_of_month": 25,
"year": 1977,
"month": 2,
"hour": 15,
"minute": 33
}
},
{
"type": "date_time",
"date_time": {
"fallback_value": "February 25, 1977",
"timestamp": 1485470276
}
}
]
}
]
}
}
}
]
}
}
]
}
}
Media header template message
Media templates, in addition to the text body, can include a header featuring an image, video, or document, as well as a footer.
The header can have these component types: image, document, video and gif apart from text. The body and footer can only have the component type text and limited to one component per template.
Note
GIFs are currently supported only in the Marketing Messages API. GIFs must be in MP4 format with a maximum file size of 3.5 MB; larger files will be displayed as video messages.
In the examples below, we send a media header template message.
{
"messages": {
"msg": [
{
"from": "00316098765432",
"to": [
{
"number": "0031612345678"
}
],
"body": {
"type": "auto",
"content": "This is a WhatsApp message"
},
"allowedChannels": ["WhatsApp"],
"richContent": {
"conversation": [
{
"template": {
"whatsapp": {
"element_name": "TEMPLATE_NAME",
"language": {
"policy": "deterministic",
"code": "en"
},
"components": [
{
"type": "header",
"parameters": [
{
"type": "image",
"media": {
"mediaName": "conversational-commerce",
"mediaUri": "https://www.cm.com/cdn/web/nl-nl/blog/conversational-commerce.jpg",
"mimeType": "image/jpeg"
}
}
]
},
{
"type": "body",
"parameters": [
{
//Text cannot be empty, always need to have value
"type": "text",
"text": "replace-value-1"
}
]
}
]
}
}
}
]
}
}
]
}
}
{
"messages": {
"msg": [
{
"from": "00316098765432",
"to": [
{
"number": "0031612345678"
}
],
"body": {
"type": "auto",
"content": "This is a WhatsApp message"
},
"allowedChannels": [
"WhatsApp"
],
"richContent": {
"conversation": [
{
"template": {
"whatsapp": {
"element_name": "document_test",
"language": {
"policy": "deterministic",
"code": "en"
},
"components": [
{
"type": "header",
"parameters": [
{
"type": "document",
"media": {
"mediaName": "terms-and-conditions",
"mediaUri": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
"mimeType": "document/pdf"
}
}
]
},
{
"type": "body",
"parameters": [
{
//text cannot be empty
"type": "text",
"text": " "
}
]
}
]
}
}
}
]
}
}
]
}
}
Authentication template message
Authentication templates let you send one-time passwords and verification codes to your users via WhatsApp.
BSUID recipients not supported
Authentication templates cannot be sent to BSUID recipients. Use the user's phone number instead.
Button types
| Field | Description |
|---|---|
One-tap autofill | The user taps the button. WhatsApp opens your app and passes the code directly. Requires changes to your Android app. On iOS 26+, keyboard suggestions provide native autofill from the push notification with no integration required. |
Copy code | The user taps the button. The code is copied to their clipboard. They then switch to your app and paste it. |
Zero-tap | WhatsApp broadcasts the code directly to your app via a broadcast receiver — the user never has to leave your app. |
In the examples below, we send an WhatsApp authentication template message with the different button types.
{
"messages": {
"msg": [{
"from": "00316098765432",
"to": [{ "number": "00316012345678" }],
"body": {
"type": "auto",
"content": "authentication message"
},
"allowedChannels": ["WhatsApp"],
"richContent": {
"conversation": [{
"template": {
"whatsapp": {
"element_name": "your-template-name",
"language": {
"policy": "deterministic",
"code": "en"
},
"components": [
{
"type": "body",
"parameters": [{
"type": "text",
"text": "123456"
}]
},
{
"type": "button",
"sub_type": "url",
"index": "0",
"parameters": [{
"type": "text",
"text": "Copy"
}]
}
]
}
}
}]
}
}]
}
}
{
"messages": {
"msg": [{
"from": "00316098765432",
"to": [{ "number": "00316012345678" }],
"body": {
"type": "auto",
"content": "authentication message"
},
"allowedChannels": ["WhatsApp"],
"richContent": {
"conversation": [{
"template": {
"whatsapp": {
"element_name": "your-template-name",
"language": {
"policy": "deterministic",
"code": "en"
},
"components": [
{
"type": "body",
"parameters": [{
"type": "text",
"text": "123456"
}]
},
{
"type": "button",
"sub_type": "copy_code",
"index": "0",
"parameters": [{
"type": "coupon_code",
"coupon_code": "123456"
}]
}
]
}
}
}]
}
}]
}
}
{
"messages": {
"msg": [{
"from": "00316098765432",
"to": [{ "number": "00316012345678" }],
"body": {
"type": "auto",
"content": "authentication message"
},
"allowedChannels": ["WhatsApp"],
"richContent": {
"conversation": [{
"template": {
"whatsapp": {
"element_name": "your-template-name",
"language": {
"policy": "deterministic",
"code": "en"
},
"components": [
{
"type": "body",
"parameters": [{
"type": "text",
"text": "123456"
}]
}
]
}
}
}]
}
}]
}
}
Example of copy code authentication template
Linked device security
Authentication messages are only delivered to the user's primary WhatsApp device. On linked devices (e.g. WhatsApp Web, desktop), the message is masked with a prompt to view it on the primary device. This is enabled by default and requires no configuration.
Location template message
Location templates let you share a specific location, such as a store, event venue, or pickup point, directly in a template message. The location is rendered as a map pin in the conversation.
Location templates are supported under both MARKETING and UTILITY categories. Make sure the category matches the context, sharing a store address for a promotion is marketing and sharing a delivery drop-off point triggered by a user action is utility.
| Field | Description | Required |
|---|---|---|
latitude | Latitude of the location. | Yes |
longitude | Longitude of the location. | Yes |
name | Name of the location (e.g. store or venue name). | No |
address | Address of the location. | No |
In the example below, we send an WhatsApp location template message.
{
"messages": {
"msg": [{
"from": "00316098765432",
"to": [{ "number": "00316012345678" }],
"body": {
"type": "auto",
"content": "fallback message"
},
"allowedChannels": ["WhatsApp"],
"richContent": {
"conversation": [{
"template": {
"whatsapp": {
"element_name": "your-template-name",
"language": {
"policy": "deterministic",
"code": "en"
},
"components": [
{
"type": "header",
"parameters": [{
"type": "location",
"location": {
"latitude": "52.3676",
"longitude": "4.9041",
"name": "CM.com HQ",
"address": "Konijnenberg 30, 4825 BD Breda"
}
}]
},
{
"type": "body",
"parameters": [{
"type": "text",
"text": "your-text-string"
}]
}
]
}
}
}]
}
}]
}
}
Interactive template message
Interactive templates is a newer generation of WhatsApp templates, which in addition to the media template, can also support button-components.
The button-component can be either of sub_type: quick_reply or url.
- With
quick_replythe end-user will see a suggestion to respond with. The button text itself has to be specified during creation of the template. - With
urlyou are able to send a Call-to-action button. This can be a phone number to call, or an url to visit. This has to be specified during creation of the template as well.
The payload on quick_reply buttons will be sent back when an end-user interacts with such a button. The maximum length of the payload is 128 characters. This will be explained in the incoming messages documentation.
In the example below, we send an interactive template message.
{
"messages": {
"msg": [
{
"from": "00316098765432",
"to": [
{
"number": "00316012345678"
}
],
"body": {
"type": "auto",
"content": "fallback message"
},
"allowedChannels": ["WhatsApp"],
"richContent": {
"conversation": [
{
"template": {
"whatsapp": {
"namespace": "your namespace id here",
"element_name": "TEMPLATE_NAME",
"language": {
"policy": "deterministic",
"code": "en"
},
"components": [
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "your-text-string"
}
]
},
{
"type": "button",
"sub_type": "quick_reply",
"index": "0",
"parameters": [
{
"type": "payload",
// Business Developer-defined payload
"payload": "aGlV0RT"
}
]
},
{
"type": "button",
"sub_type": "url",
"index": "1",
"parameters": [
{
"type": "text",
// Business Developer-defined dynamic URL suffix
"text": "9rwn"
}
]
},
{
"type": "button",
"sub_type": "url",
"index": "2",
"parameters": [
{
"type": "text",
// Business Developer-defined dynamic URL suffix
"text": "ticket.pdf"
}
]
}
]
}
}
}
]
}
}
]
}
}
Flows template message
Example of flow template message
In the example below, we send an WhatsApp Template Flows message.
{
"messages": {
"msg": [
{
"from": "00316098765432",
"to": [
{
"number": "00316012345678"
}
],
"body": {
"type": "auto",
"content": "fallback message"
},
"allowedChannels": [
"WhatsApp"
],
"richContent": {
"conversation": [
{
"template": {
"whatsapp": {
"namespace": "your-namespace",
"element_name": "your-template-name",
"language": {
"policy": "deterministic",
"code": "en"
},
"components": [
{
"type": "button",
"sub_type": "flow",
"index": "0",
"parameters": [
{
"type": "action",
"action": {
"flow_token": "your-flow-token",
"flow_action_data": {}
}
}
]
}
]
}
}
}
]
}
}
]
}
}
Carousel template message
Media card carousel templates enable you to send a single MARKETING template message along with up to 10 product media cards displayed in a horizontally scrollable format. Each card has its own header (image or video), body, and buttons.
Example of carousel template message
In the example below, we send an WhatsApp Carousel template message.
{
"messages": {
"msg": [
{
"from": "00316098765432",
"to": [
{
"number": "00316012345678"
}
],
"body": {
"type": "auto",
"content": "fallback message"
},
"allowedChannels": [
"WhatsApp"
],
"richContent": {
"conversation": [
{
"template": {
"whatsapp": {
"namespace": "your-namespace",
"element_name": "your-template-name",
"language": {
"policy": "deterministic",
"code": "en"
},
"components": [
{
"type": "BODY",
"parameters": []
},
{
"type": "CAROUSEL",
"cards": [
{
"card_index": 0,
"components": [
{
"type": "HEADER",
"parameters": [
{
"type": "IMAGE",
"image": {
"mediaUri": "https://cmcom.s3.eu-west-3.amazonaws.com/webimage-C0D8E5EE-2ABC-41F2-B3E694BF22A1D6C6.png"
}
}
]
},
{
"type": "BODY",
"parameters": []
},
{
"type": "BUTTON",
"sub_type": "QUICK_REPLY",
"index": 0,
"parameters": [
{
"type": "PAYLOAD",
"payload": "your-payload-here"
}
]
}
]
},
{
"card_index": 1,
"components": [
{
"type": "HEADER",
"parameters": [
{
"type": "IMAGE",
"image": {
"mediaUri": "https://cmcom.s3.eu-west-3.amazonaws.com/webimage-4C0C8462-0F93-41AC-A66F3D614E53DFA5.png"
}
}
]
},
{
"type": "BODY",
"parameters": []
},
{
"type": "BUTTON",
"sub_type": "QUICK_REPLY",
"index": 0,
"parameters": [
{
"type": "PAYLOAD",
"payload": "your-payload-here"
}
]
}
]
}
]
}
]
}
}
}
]
}
}
]
}
}
Limited-time offer template message (LTO)
Limited-time offer are MARKETING templates that let you show expiration dates and countdown timers for offer codes in your messages. It makes it easy for you to let end-users know about time-limited deals and keep them engaged.
Limited-time offer template message
Limited-time offer object:
| Field | Description | Required |
|---|---|---|
| expiration_time_ms | Offer code expiration time as a UNIX timestamp in milliseconds. | Yes |
In the example below, we send a Limited-time offer template message:
{
"messages": {
"msg": [
{
"from": "00316098765432",
"to": [
{
"number": "00316012345678"
}
],
"body": {
"type": "auto",
"content": "fallback message"
},
"allowedChannels": [
"WhatsApp"
],
"richContent": {
"conversation": [
{
"template": {
"whatsapp": {
"namespace": "your-namespace",
"element_name": "your-template-name",
"language": {
"policy": "deterministic",
"code": "en_US"
},
"components": [
{
"parameters": [],
"type": "body"
},
{
"type": "limited_time_offer",
"parameters": [
{
"type": "limited_time_offer",
"limited_time_offer": {
"expiration_time_ms": 1708184832000
}
}
]
},
{
"type": "button",
"sub_type": "copy_code",
"index": 0,
"parameters": [
{
"type": "coupon_code",
"coupon_code": "1234ab"
}
]
}
]
}
}
}
]
}
}
]
}
}
Coupon Code template message
Coupon code templates are MARKETING templates that display a copy code button (without expiration date). When tapped, the code is copied to the customer's clipboard. They can also contain an image as header.
Coupon code template message
Coupon code:
| Field | Description | Required |
|---|---|---|
| coupon_code | Offer code as text. Maximum 20 characters. | Yes |
In the example below, we send a Coupon template message:
{
"messages": {
"msg": [
{
"from": "00316098765432",
"to": [
{
"number": "00316012345678"
}
],
"body": {
"type": "auto",
"content": "fallback message"
},
"allowedChannels": [
"WhatsApp"
],
"richContent": {
"conversation": [
{
"template": {
"whatsapp": {
"element_name": "your-template-name",
"language": {
"policy": "deterministic",
"code": "en_US"
},
"components": [
{
"parameters": [],
"type": "body"
},
{
"type": "button",
"sub_type": "copy_code",
"index": 0,
"parameters": [
{
"type": "coupon_code",
"coupon_code": "1234ab"
}
]
}
]
}
}
}
]
}
}
]
}
}
Important for LTO and Coupon templates
- Only templates categorized as MARKETING are supported.
- Only one copy coupon button per template and the copy coupon button text cannot be customized.
- Footer components are not supported.
- Users viewing limited-time offer or coupon template messages on WhatsApp Web or the desktop app will not see the offer. Instead, they will see a message indicating that their client does not support this message type.
Call Permissions Request template message
Call permissions request templates are MARKETING messages that allows that your business can send request to your customers outside the customer service window.
To place a call to your WhatsApp customers, you must obtain their explicit permission, which can be temporary or permanent. Only your customer can grant or revoke this permission, and permanent permissions will be stored until revoked.
Limitations per business phone number
- Temporary permissions last 7 days (168 hours).
- Permanent permissions do not expire but can be revoked by the user.
- Maximum of 100 connected calls per business phone number every 24 hours.
Sending a template message enables you to initiate a conversation with your customers by including a call permission request. When sending a template message with a call permission request, it is mandatory to include context in the form of a text body. Additionally, template messages allow for further customization of the permission request by including a header and footer.
Example of call permission request template
{
"messages": {
"msg": [
{
"from": "00316098765432",
"to": [
{
"number": "00316012345678"
}
],
"body": {
"type": "auto",
"content": "fallback message"
},
"allowedChannels": [
"WhatsApp"
],
"richContent": {
"conversation": [
{
"template": {
"whatsapp": {
"components": [
{
"type": "body",
"parameters": [
{
"key": "text",
"text": "text"
}
]
}
],
"element_name": "test_call_request_permissions",
"language": {
"code": "en",
"policy": "deterministic"
}
}
}
}
]
}
}
]
}
}
{
"messages": {
"msg": [
{
"from": "00316098765432",
"to": [
{
"number": "00316012345678"
}
],
"body": {
"type": "auto",
"content": "fallback message"
},
"allowedChannels": [
"WhatsApp"
],
"richContent": {
"conversation": [
{
"template": {
"whatsapp": {
"components": [
{
//template has a static text prederminated.
"type": "body",
"parameters": []
}
],
"element_name": "test_call_request_permissions",
"language": {
"code": "en",
"policy": "deterministic"
}
}
}
}
]
}
}
]
}
}
Time-To-Live (TTL) for WhatsApp Message Templates
The Time-To-Live (TTL), or validity period, defines how long the system will attempt to deliver a WhatsApp message if the recipient is temporarily unavailable. This parameter is configurable per template type: Authentication, Utility, and Marketing.
Default TTL Values
| Template Type | Default TTL |
|---|---|
| Authentication | 10 minutes |
| Utility | 30 days |
| Marketing | 30 days |
Custom TTL Ranges
| Template Type | Customizable Range |
|---|---|
| Authentication | 30–900 seconds (30 secs–15 mins) |
| Utility | 30–43,200 seconds (30 secs–12 hours) |
| Marketing | 43,200–2,592,000 seconds (12 hrs–30 d) |
Templates created before 23 October 2024
Authentication templates created before 23 October 2024 default to 30 days unless explicitly updated.
TTL Expiry and Dropped Messages
Messages not delivered within the configured TTL will no longer end up on the end user's phone.
If you do not receive a delivered message webhook before the TTL expires, assume the message was dropped.
There may be a short delay between TTL expiry and the corresponding webhook. Consider implementing a buffer period before acting on undelivered messages.
Recommendation
We recommend setting the TTL of your authentication templates equal to or less than your code expiration time to avoid delivering expired codes to users.
Updated 19 days ago