WhatsApp Cloud API

Templates

Learn about templates, their uses and limitations, and the various types of templates you can create.

Templates are WhatsApp Business Account assets that can be sent in template messages via Cloud API or Marketing Messages Lite API. Template messages are the only type of message that can be sent to WhatsApp users outside of a customer service window, so templates are commonly used when messaging users in bulk, or when you need to message a user, but no customer service window is open between you and the user.

Creation

Use the POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates endpoint or message templates panel in WhatsApp Manager to create a template.

Template creation via API uses a common syntax. The bulk of the variation occurs in the category string, which assigns a category to the template, and the components array, which defines the components that make up the template.

You can create a maximum of 100 templates in a WhatsApp Business Account per hour.

Common syntax

curl 'https://graph.facebook.com/v23.0/102290129340398/message_templates' \
-H 'Authorization: Bearer EAAJB...' \
-H 'Content-Type: application/json' \
-d '
{
"fname": "<NAME>",
"category": "<CATEGORY>",
"language": "<LANGUAGE>",
"parameter_format": "<PARAMETER_FORMAT>",
"components": [<COMPONENTS>]
}'

Names

Every template must have a name, but names are not unique. This flexibility allows you to create multiple templates with the same name, but in different languages.

Template names are limited to a maximum of 512 characters, consisting of lowercase alphanumeric characters and underscores.

Categories

Each template must be categorized as authentication, marketing, or utility. Our template categorization document describes how to assign the proper category to a template, and what can happen if we determine that a template has been mis-categorized.

Note that template categories also factor into pricing.

Components

Templates are made up of various text, media, and interactive UI components, which you define upon template creation. Our template components document describes all possible components and how to define them.

Since there are a lot of components to choose from, we have dedicated authentication, marketing, and utility template documents and sub-documents, each with code examples that show how to create various templates with commonly used components.

Languages

You must assign a template language code upon template creation. Template strings and variables are not translated by Meta, so you are responsible for supplying strings and example parameters in their appropriate language.

If you create multiple templates with the same name but with different languages, each template counts against your template limit.

Parameter formats

Some template components allow you to define strings that contain one or more parameters (described as "variables" in WhatsApp Manager). These are replaced with values included by you in your send message payload when you send the template.

Upon template creation, if a string includes one or more parameters, you can specify their format — either named or positional — and you must include an example value for each parameter. If you do not specify a format, the template will use positional format by default.

Named parameters

Parameters using the named format must be unique, single strings, composed of lowercase characters and underscores, wrapped in double curly brackets, for example, {{first_name}}. Example values in template creation payloads and real values in template send payloads can appear in any order.

Example template creation payload with named parameters:

{
"name": "order_confirmation",
"language": "en_US",
"category": "utility",
"parameter_format": "named",
"components": [
  {
    "type": "body",
    "text": "Thank you, {{first_name}}! Your order number is {{order_number}}.",
    "example": {
      "body_text_named_params": [
        {
          "param_name": "first_name",
          "example": "Pablo"
        },
        {
          "param_name": "order_number",
          "example": "860198-230332"
        }
      ]
    }
  }
]
}

Example template send payload of template that uses named parameters:

{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "+16505551234",
"type": "template",
"template": {
  "name": "order_confirmation",
  "language": {
    "code": "en_US"
  },
  "components": [
    {
      "type": "body",
      "parameters": [
        {
          "type": "text",
          "parameter_name": "first_name",
          "text": "Jessica"
        },
        {
          "type": "text",
          "parameter_name": "order_number",
          "text": "SKBUP2-4CPIG9"
        }
      ]
    }
  ]
}
}

Positional parameters

Positional parameters must be ordered array index numbers, starting from 1, wrapped in double curly brackets: ({{1}}...{{2}}...and so on). Example values in template creation payloads and real values in template send payloads must appear in the order in which their corresponding placeholders appear in the component text string.

Example template creation payload with positional parameter:

{
"name": "order_confirmation",
"language": "en_US",
"category": "utility",
"parameter_format": "positional",
"components": [
  {
    "type": "body",
    "text": "Hi {{1}}! Your order number is {{2}}. Thank you.",
    "example": {
      "body_text": [
        [
          "Pablo",
          "860198-230332"
        ]
      ]
    }
  }
]
}

Example template send payload of template that uses positional parameter:

{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "+16505551234",
"type": "template",
"template": {
  "name": "order_confirmation",
  "language": {
    "code": "en_US"
  },
  "components": [
    {
      "type": "body",
      "parameters": [
        {
          "type": "text",
          "text": "Jessica"
        },
        {
          "type": "text",
          "text": "SKBUP2-4CPIG9"
        }
      ]
    }
  ]
}
}

Media

Template header components can display media assets. If you are creating a template with a media header, you must use the Resumable Upload API to obtain an asset handle, and include this asset handle in your template creation request. The example asset will be reviewed as part of template review.

Template review

Templates are automatically reviewed upon creation or after editing. If your template is approved, its status will be set to APPROVED and you can begin sending it in template messages. If it is rejected, or if its status changes to any other value, it cannot be sent in template messages.

See our template review document to learn more about the template review process, common rejection reasons, and what you can do if your template is rejected.

Template status

Templates must have a status of APPROVED before they can be sent in template messages. A template's status is initially set by the template review process, but can be changed to another value based on usage and quality feedback.

Template status changes are communicated via message_template_status_update webhooks, but you can use the GET /<TEMPLATE_ID> endpoint and request the status field to get the status of a template at any time.

Example request

curl 'https://graph.facebook.com/v23.0/1259544702043867?fields=status' \
-H 'Authorization: Bearer EAAJ...'

Example response

{
"status": "APPROVED",
"id": "1259544702043867"
}

See the GET /<TEMPLATE_ID> endpoint reference for a list of all possible status values and what they mean.

WhatsApp Manager

The Manage templates panel in WhatsApp Manager also displays template statuses, and appends quality ratings for approved (active) templates:

  • In-Review: Indicates that the template is still under review. Review can take up to 24 hours.
  • Rejected: The template has been rejected during our review process or violates one or more of our policies.
  • Active - Quality pending: The message template has yet to receive quality feedback or read-rate information from customers. Message templates with this status can be sent to customers.
  • Active - High Quality: The template has received little to no negative customer feedback. Message templates with this status can be sent to customers.
  • Active - Medium Quality: The template has received negative feedback from multiple customers, or low read-rates, but might soon become paused or disabled. Message templates with this status can be sent to customers.
  • Active - Low Quality: The template has received negative feedback from multiple customers, or low read-rates. Message templates with this status can be sent to customers but are in danger of being paused or disabled soon, so we recommend that you address the issues that customers are reporting.
  • Paused: The template has been paused due to recurring negative feedback from customers, or low read-rates. Message templates with this status cannot be sent to customers. See Template Pausing.
  • Disabled: The template has been disabled due to recurring negative feedback from customers. Message templates with this status cannot be sent to customers.
  • Appeal Requested: Indicates that an appeal has been requested.

Template limits

The number of templates a WhatsApp Business Account can have is determined by its parent business portfolio.

If a parent business portfolio is unverified, each of its WhatsApp Business Accounts is limited to 250 message templates. However, if the portfolio is verified, and at least one of its WhatsApp Business Accounts has a business phone number with an approved display name, each of its WhatsApp Business Accounts can have up to 6,000 templates.

Additionally, there are limits on the number of templates you can send, as well as processes that can affect template delivery:

  • Messaging limits — A limit on the number of message templates you can send outside of customer service windows.
  • Template pacing — A process that allows time for WhatsApp users to provide feedback on message templates.
  • Template pausing — A process that can temporarily pause message templates that have received poor feedback.
  • Per-user marketing template message limits — A process that limits the number of marketing message templates a given WhatsApp user may receive from any business.

Time-to-live

If a message sent to a WhatsApp user cannot be delivered, the system will continue attempting delivery for a period known as the time-to-live (TTL). You can customize the TTL for templates upon template creation.

See our time-to-live document for more information.

Quality rating

Template quality rating is a system used to evaluate the quality of message templates, based on usage, customer feedback, and engagement. This rating helps maintain a high-quality messaging ecosystem and helps ensure that you are sending relevant and well-received messages.

See our template quality rating document for more information about quality ratings, how they can affect a template's status, and how you can be notified of changes to template quality scores.

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 status messages webhook before sending the next message in your message sequence.

Template management

See our template management document for a list of endpoints commonly used for getting, updating, and deleting templates.