Sending 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:

• Text-based message templates
• Media-based message templates
• Interactive message templates
• Location-based message templates
• Authentication templates with one-time password buttons
• Multi-Product Message templates

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.

Sample request:

curl -X  POST \
 'https://graph.facebook.com/v19.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": "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": "DATE"
            }
          }
        ]
      }
    ]
  }
}'

{
  "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/v19.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"
            }
          }
        ]
      }
    ]
  }
}'

{
  "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/v19.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"
          }
        ]
      }
    ]
  }
}'

{
  "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

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.

Per-User Marketing Template Message Limits

We are rolling out new approaches, starting with consumers in India, that create high-quality user experiences and maximize marketing template message engagement. This may include limiting 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. Note that the limit is determined based on the number of marketing template messages that person has already received from any business, and is not related to your business specifically.

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, marketing template messages sent to the user will not be affected.

If a marketing template message is not delivered to a given user due to the limit, Cloud API will return error code 131026 and On-Premises API will return error code 1026. Note, however, that these error codes cover a wide range of issues that can result in non-delivery of a message, and for privacy reasons, we will not disclose if in fact the message was not delivered due to the limit. Refer to Cloud API's Troubleshooting document and On-Premises API's "Why is my delivery rate not 100%?" FAQ for descriptions of non-delivery reasons and what you can do to determine their underlying cause.

If you do receive one of these error codes and suspect it is due to the limit, avoid immediately resending the template message, as it will only result in another error response. Instead, retry in increasing larger time increments until the message is delivered, since the limit may be in effect for differing periods of time.

We'll continue refining our approach and 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.