We are making changes to the WhatsApp Business Platform pricing model. See Pricing Updates on the WhatsApp Business Platform.

Template Messages

WhatsApp message templates are specific message formats that businesses use to send out notifications or customer care messages to people that have opted in to notifications. Messages can include appointment reminders, shipping information, issue resolution or payment updates.

Before sending a template message, you need to create a template. See Create Message Templates for Your WhatsApp Business Account for more information. If your account is not verified yet, you can use one of our pre-approved templates.

Currently, you can send the following template types:

All API calls mentioned in this guide must be authenticated with an access token. Developers can authenticate their API calls with the access token generated in the App Dashboard > WhatsApp > API Setup panel. Solution Partners must authenticate themselves with an access token with the whatsapp_business_messaging permission.

Pacing

Newly created or unpaused marketing templates are subject to template pacing. See Template Pacing.

Text-Based Message Templates

To send a text-based message template, make a POST call to /PHONE_NUMBER_ID/messages and attach a message object with type=template. Then, add a template object.

Substitute the placeholder properties below using the properties table.

Sample Request

curl -X  POST \
 'https://graph.facebook.com/CURRENT_API_VERSION/FROM_PHONE_NUMBER_ID/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "template",
  "template": {
    "name": "TEMPLATE_NAME",
    "language": {
      "code": "LANGUAGE_AND_LOCALE_CODE"
    },
    "components": [
         <NAMED_PARAMETER_INPUT>
         <POSITIONAL_PARAMETER_INPUT>
        ]
      }
    ]
  }
}'

Properties

Placeholder Description Example Value

Placeholder	Description	Example Value
`<NAMED_PARAMETER_INPUT>`	`[JSON Object]` \| Optional Required when you have used named parameters in your template's body text. An array of JSON objects that contain `type`, `parameter_name`, and `text` strings. `“type”` — Parameter type. Always the value `"text"` `“parameter_name”` — The custom parameter name used in your template. Must be lowercase letters and underscores only. `“text”` — The actual text that will replace the named parameter in your template.	"type": "body", "parameters": [ { "type": "text", "paramter_name": "customer_name", "text": "John" }, { "type": "text", "parameter_name": "order_id", "text": "9128312831" } ]
`<POSITIONAL_PARAMTER_INPUT>`	`[JSON Object]` \| Optional Required when you have used positional parameters in your template's body text. An array of JSON objects that contain `type` and `text` strings. `“type”` — Parameter type. Always the value `"text"` `“text”` — The actual text that will replace the positional parameter in your template. The number of strings must match the number of parameters included in the chosen template.	"type": "body", "parameters": [ { "type": "text", "text": "John" }, { "type": "text", "text": "9128312831" } ] ]

<NAMED_PARAMETER_INPUT>

[JSON Object] | Optional

Required when you have used named parameters in your template's body text.

An array of JSON objects that contain type, parameter_name, and text strings.

“type” — Parameter type. Always the value "text"
“parameter_name” — The custom parameter name used in your template. Must be lowercase letters and underscores only.
“text” — The actual text that will replace the named parameter in your template.

    "type": "body",
    "parameters": [
      {
        "type": "text",
        "paramter_name": "customer_name",
        "text": "John"
      },
      {
        "type": "text",
        "parameter_name": "order_id",
        "text": "9128312831"
      }        
    ]

<POSITIONAL_PARAMTER_INPUT>

[JSON Object] | Optional

Required when you have used positional parameters in your template's body text.

An array of JSON objects that contain type and text strings.

“type” — Parameter type. Always the value "text"
“text” — The actual text that will replace the positional parameter in your template.

The number of strings must match the number of parameters included in the chosen template.

    "type": "body",
      "parameters": [
        {
          "type": "text",
          "text": "John"
        },
        {
          "type": "text",
          "text": "9128312831"
        }        
      ]
    ]

Sample Reponse

A successful response includes an object with an identifier prefixed with wamid. Use the ID listed after wamid to track your message status.

{
  "messaging_product": "whatsapp",
  "contacts": [{
      "input": "PHONE_NUMBER",
      "wa_id": "WHATSAPP_ID",
    }]
  "messages": [{
      "id": "wamid.ID",
    }]
}

Media-Based Message Templates

To send a media-based message template, make a POST call to /PHONE_NUMBER_ID/messages and attach a message object with type=template. Then, add a template object. Supports Media HTTP Caching.

Use the POST WhatsApp Business Phone Number > Messages endpoint to send a media-based template message. Set the type property to template and use the template property to define your template object and its media object.

When defining your media object, you can either upload your media asset to our servers and use its media ID (using the id property), or host the asset on your server and use its URL (using the link property). If using link, your asset must be on a publicly accessible server or the message will fail to send.

To reduce the likelihood of errors and avoid unnecessary requests to your public server, we recommend that you upload your media assets and use their IDs when sending messages.

Media assets can also be cached. See Media HTTP Caching.

Sample request:

curl -X  POST \
 'https://graph.facebook.com/v21.0/FROM_PHONE_NUMBER_ID/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "template",
  "template": {
    "name": "TEMPLATE_NAME",
    "language": {
      "code": "LANGUAGE_AND_LOCALE_CODE"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": {
              "link": "https://URL"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "TEXT-STRING"
          },
          {
            "type": "currency",
            "currency": {
              "fallback_value": "VALUE",
              "code": "USD",
              "amount_1000": NUMBER
            }
          },
          {
            "type": "date_time",
            "date_time": {
              "fallback_value": "MONTH DAY, YEAR"
            }
          }
        ]
      }
    ]
  }
}'

A successful response includes an object with an identifier prefixed with wamid. Use the ID listed after wamid to track your message status.

{
  "messaging_product": "whatsapp",
  "contacts": [{
      "input": "PHONE_NUMBER",
      "wa_id": "WHATSAPP_ID",
    }]
  "messages": [{
      "id": "wamid.ID",
    }]
}

Interactive Message Templates

Interactive message templates expand the content you can send recipients beyond the standard message template and media messages template types to include interactive buttons using the components object. There are two types of predefined buttons:

Call-to-Action — Allows your customer to call a phone number and visit a website.
Quick Reply — Allows your customer to return a simple text message.

These buttons can be attached to text messages or media messages. Once your interactive message templates have been created and approved, you can use them in notification messages as well as customer service/care messages.

To send an interactive message template, make a POST call to /PHONE_NUMBER_ID/messages and attach a message object with type=template. Then, add a template object with your chosen button.

Sample request:

curl -X  POST \
 'https://graph.facebook.com/v21.0/FROM_PHONE_NUMBER_ID/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "template",
  "template": {
    "name": "TEMPLATE_NAME",
    "language": {
      "code": "LANGUAGE_AND_LOCALE_CODE"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": {
              "link": "http(s)://URL"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "TEXT_STRING"
          },
          {
            "type": "currency",
            "currency": {
              "fallback_value": "VALUE",
              "code": "USD",
              "amount_1000": NUMBER
            }
          },
          {
            "type": "date_time",
            "date_time": {
              "fallback_value": "MONTH DAY, YEAR"
            }
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "quick_reply",
        "index": "0",
        "parameters": [
          {
            "type": "payload",
            "payload": "PAYLOAD"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "quick_reply",
        "index": "1",
        "parameters": [
          {
            "type": "payload",
            "payload": "PAYLOAD"
          }
        ]
      }
    ]
  }
}'

A successful response includes an object with an identifier prefixed with wamid. Use the ID listed after wamid to track your message status.

{
  "messaging_product": "whatsapp",
  "contacts": [{
      "input": "PHONE_NUMBER",
      "wa_id": "WHATSAPP_ID",
    }]
  "messages": [{
      "id": "wamid.ID",
    }]
}

Location-based Message Templates

To send a template that uses a location header your request must include a location header object.

Syntax

{
  "type": "header",
  "parameters": [
    {
      "type": "location",
      "location": {
        "latitude": "<LATITUDE>",
        "longitude": "<LONGITUDE>",
        "name": "<NAME>",
        "address": "<ADDRESS>"
      }
    }
  ]
}

Properties

Placeholder	Description	Sample Value
`<ADDRESS>`	Address that will appear after the `<NAME>` value, below the generic map at the top of the message.	`1 Hacker Way, Menlo Park, CA 94025`
`<LATITUDE>`	Location latitude.	`37.483307`
`<LONGITUDE>`	Location longitude.	`122.148981`
`<NAME>`	Text that will appear immediately below the generic map at the top of the message.	`Pablo Morales`

Example Request

This is an example request to send an existing template that uses the following components:

a location header
a text body with a variable
a footer
a quick reply button

curl -L 'https://graph.facebook.com/v16.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "12245554792",
  "type": "template",
  "template": {
    "name": "order_delivery_update",
    "language": {
      "code": "en_US"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "location",
            "location": {
              "latitude": "37.483307",
              "longitude": "122.148981",
              "name": "Pablo Morales",
              "address": "1 Hacker Way, Menlo Park, CA 94025"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Pablo"
          },
          {
            "type": "text",
            "text": "566701"
          }
        ]
      }
    ]
  }
}'

Authentication Templates

Attempting to send legacy authentication templates (templates without one-time password buttons) will return error code 100 if variable values exceed 15 characters or contain links or emojis, or the template body component contains a link. Instead, create and use an authentication template that has a one-time password button.

See Authentication Templates and Sending Authentication Templates.

Delivery Sequence of Multiple Messages

When sending a series of messages, the order in which messages are delivered is not guaranteed to match the order of your API requests. If you need to ensure the sequence of message delivery, confirm receipt of a delivered status in a messages webhook before sending the next message in your message sequence.

User preferences for marketing messages

Starting November 22, 2024, we will begin gradually rolling out user preferences for marketing messages. This feature may not be available to WhatsApp users in some regions initially.

WhatsApp provides a setting (Offers and announcements) that allows users to stop or resume delivery of marketing template messages from your business, or to indicate their interest level in these types of messages.

Stop/Resume controls

WhatsApp users can use the Offers and announcements setting to stop or resume delivery of marketing template messages from your business.

If you attempt to send a marketing template to a WhatsApp user who has stopped marketing template messages from your business, the API will process the request but not send the message. Instead, the API will trigger a messages webhook with:

status set to failed,
code set to 131050,
title set to Unable to deliver the message. This recipient has chosen to stop receiving marketing messages on WhatsApp from your business

To be notified whenever a WhatsApp user stops or resumes delivery of marketing template messages from your business, subscribe to the user_preferences webhook.

Interested/Not Interested feedback

WhatsApp users can use the Offers and announcements setting to indicate how interested they are in receiving marketing template messages from your business.

If a user chooses Not interested, it can affect per-user marketing template messaging limits between you and the user.

Per-User Marketing Template Message Limits

Since launching the per-user marketing template limit, we have seen significant improvements in user read rates and sentiment. We are continuing to improve how we limit delivery of marketing messages.

What is it?

WhatsApp may limit the number of marketing template messages a person receives from any business in a given period of time, starting with a small number of conversations that are less likely to be read. Soon, we will also start to deliver fewer marketing conversations to those users who are less likely to engage with them.

Why it’s important

WhatsApp has found that per-user marketing template limits maximize message engagement and improve the user experience, measured through improvements in user read rates and sentiment. This limit helps WhatsApp users find business messaging more valuable and feel less like they receive too many business messages.

How this Applies to Your Business

The limit only applies to marketing template messages that would normally open a new marketing conversation. If a marketing conversation is already open between you and a WhatsApp user, you may send one additional marketing template message. Further marketing template messages can only be sent in an open marketing conversation if the person responds to any message.

Example:

The first marketing template message is delivered and opens a new 24-hour marketing conversation customer service window. The per-user marketing template message limit applies
A second marketing template message can be sent in an existing conversation.
Each time the WhatsApp user responds in an existing conversation window, you can send one additional marketing template message. You can also send unlimited free-form messages.

How We Notify via Error Code

Soon, we will also introduce a new error code to help businesses understand when a message has not been delivered in order to maintain ecosystem health.

If a marketing template message is not sent due to per-user marketing template limit enforcement, a messages webhook will be triggered with status set to failed and (error) code set to 131049 (for Cloud API) or 1026 (for On-Premises API).

If you do receive this error code and suspect it is due to the limit, avoid immediately resending the template message. Doing so will only result in another error response since the limit may be in effect for differing periods of time. Instead, retry sending the message in increasingly larger time increments until it is delivered.

We will continue to refine our approach, and we appreciate your partnership as we invest in making WhatsApp the best possible experience for your business and your customers.

Troubleshooting

If you are experiencing problems with message delivery, see Message Not Delivered.

WhatsApp Business Platform | Cloud API | Business Management API