Message Templates: Parts, Limits & Categories

A message template is a message you write once, submit to Meta for approval, and then reuse. It is the only kind of message a business can send to a WhatsApp user outside the 24-hour customer service window. If a customer has not messaged you in the last 24 hours, you cannot send them normal text. You can only send an approved template (see The 24-Hour Customer Service Window). Templates are also what businesses use to message many people at once.

Every template has:

• a name and a language,
• a category: Marketing, Utility or Authentication. The category also decides the price,
• components: the parts the customer sees. These are an optional header, a body (always required), an optional footer and optional buttons.

A template can only be sent once its status is Approved. Meta reviews every new or edited template, usually within 24 hours (see Template Review & Rejections).

The parts of a template#

Think of a template like a printed card. It has an optional title at the top, the main message, an optional small line at the bottom, and optional buttons to tap.

Buttons#

Buttons let the customer act straight from the message. Meta allows up to 10 buttons in a template, with limits per type:

How buttons display:

• If a template has more than three buttons, the customer sees two, plus a See all options button that reveals the rest.
• Templates with 4 or more buttons, or with a quick reply button plus any other button type, cannot be viewed on WhatsApp desktop. The customer is asked to open it on their phone.
• When you mix quick reply buttons with other buttons, keep each type together. "Quick reply, Quick reply, URL, Phone" is valid. "Quick reply, URL, Quick reply" is not, and the API returns an error.

Variables (the blanks you fill in)#

A variable is a blank in the template that you fill in each time you send it, such as the customer's name or an order number. Meta's WhatsApp Manager calls them variables, and the API calls them parameters. They are written in double curly brackets.

There are two styles:

Example body: Thank you, {{first_name}}! Your order number is {{order_number}}.

When you create a template that has variables, you must give a sample value for each one (for example "Pablo" for {{first_name}}). Meta's reviewers use the samples to see how the real message will look.

The three template categories#

Every template must be one of three categories. You choose it when you create the template, and Meta checks your choice against the content.

The rules Meta applies:

• Utility must meet both tests. It must have no promotional or persuasive intent. It must also be either specific to the user (their order, account or transaction) or essential to them (for example their safety).
• Mixed content counts as Marketing. An order update that also contains a promo is Marketing.
• Unclear content counts as Marketing. A template that is only {{1}}, or just "Congratulations!", is Marketing.
• Retargeting is Marketing, even if the user asked for it. This includes abandoned cart reminders and "your subscription is expiring, renew now".
• Only Authentication templates can carry a one-time passcode. Marketing and Utility templates cannot be used for this. Authentication templates must come from Meta's template library, must have a one-time password button (copy code or one-tap), and cannot contain URLs, media or emojis. Their variables are limited to 15 characters.

How Meta assigns and changes the category#

• When you create a template: Meta validates the category you picked. Since April 9, 2025, if you pick Utility but Meta decides it is Marketing, the template is approved as Marketing rather than rejected. If Meta disagrees with the category in another way, the template is rejected with the reason INCORRECT_CATEGORY.
• After approval: Meta regularly re-checks approved templates, including the messages they actually send.
  • A Utility template that should be Marketing is switched to Marketing. You get 1 day's notice first. It stays approved and can still be sent.
  • A Marketing or Utility template that should be Authentication keeps its category. On the first day of the following month, its status is changed to Rejected and it can no longer be sent.
• If you disagree: you can request a category review in WhatsApp Manager, under Business Support, Template Category Updates. The window is up to 60 days from creation, or 60 days from the date the category was changed. Details are in Template Review & Rejections.

Businesses that keep labelling marketing templates as utility face escalating restrictions. These go from a warning, to a cap on utility message volume for at least 7 days, to all their utility templates being moved to Marketing for 7 days (30 days for repeat violations).

How the category affects price#

Meta charges per delivered message, and the price depends on the message's category and the recipient's country. A Marketing template, a Utility template and an Authentication template therefore cost different amounts. When Meta moves a template to a different category, the messages it sends are categorised under the new category. See Message Categories & Pricing.

Account limits#

Sending templates is also governed by messaging limits, and by template quality, which can pause a template (see Template Quality Rating & Pausing).

Technical detail: creating and sending a template#

Templates are created with a POST to /<WABA_ID>/message_templates (or in WhatsApp Manager). This is a Utility template with a named body variable:

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

To send it, call the messages endpoint with "type": "template" and supply the real values:

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

Other technical points:

• Positional samples go in example.body_text as a nested array, for example [["Pablo", "860198-230332"]]. A text header uses example.header_text (positional) or example.header_text_named_params (named).
• Media headers use "format": "IMAGE" | "VIDEO" | "GIF" | "DOCUMENT" with an example.header_handle obtained from the Resumable Upload API. The sample media is reviewed along with the template.
• URL button values must be percent-encoded when sent. For example, a space becomes %20 and ç becomes %C3%A7. Unencoded special characters can make the send fail.
• Category changes arrive on the template_category_update webhook. To list affected templates, request GET /<WABA_ID>/message_templates?fields=category,correct_category. If the two values differ and correct_category is not empty, the category will change on the first day of the next month.
• Status changes arrive on the message_template_status_update webhook, and component changes on message_template_components_update.

Frequently asked#

Gotchas & common mistakes#