GLOSSARY

What is a Message Template?

A message template is a pre-registered, Meta-approved message structure that a business must use to start a WhatsApp conversation outside the 24-hour customer service window. It is created on a WABA, categorised as marketing, utility or authentication, referenced by name plus language, and filled in at send time with positional or named parameters.

Try Pinlyx free See live demo

Free forever plan · No credit card required · Cancel anytime

Quick definition

In a single sentence: outside the 24-hour window you cannot write a message, you can only fill one in.

What it means

WhatsApp does not let a business type a fresh message to a customer whenever it likes. If the customer has not written to you in the last 24 hours, the only thing you may send is a message template: a structure you registered in advance, that a Meta reviewer approved, with a small number of blanks you fill at send time.

This is the single largest architectural difference between WhatsApp and every other messaging channel a CRM touches. On Telegram or email you compose and send. On WhatsApp you either reply inside an open window, or you select an approved template and supply parameters. A campaign that was designed as free text has to be redesigned as a template library.

Templates live on the WABA, are created and read at /{waba-id}/message_templates, and are sent from a specific phone number. A template is identified by its name together with its language, so order_shipped in en_US and order_shipped in tr are two separate approvals of the same logical message.

The three categories, and why the choice is financial

Every template is filed under one of three categories, and the category is not a label you pick for tidiness. It determines what you are charged, how aggressively the message is frequency-capped per user, and how strictly it is reviewed.

The rule that catches people out is contamination. Category is decided by content, not by your intent for the message. Take a genuine order confirmation and add one closing line offering ten percent off the next purchase, and the template is no longer utility. Meta will either reject it for an incorrect category or, more disruptively, approve it and later re-categorise it, which arrives as a template_category_update webhook and quietly changes what your notifications cost.

Authentication is stricter still. It exists for one-time passcodes and uses a fixed structure with a copy-code or one-tap autofill button. Anything else in the body, including a friendly marketing sign-off, is a category mismatch.

Structure: components, variables and limits

A template is made of components, and only the body is mandatory:

Header. Optional. Either a short line of text or a single media item: image, video or document. A text header may contain at most one variable.
Body. Required. The message itself, with as many variables as you need, subject to the formatting rules below.
Footer. Optional, short, and static. Footers cannot contain variables at all, which is why the "reply STOP to unsubscribe" line belongs there.
Buttons. Optional. Quick replies that come back to your webhook, URL buttons that open a link, a single call button, copy-code buttons for authentication, and Flow buttons that open a WhatsApp Flow.

Variables are written as {{1}}, {{2}} and so on, in order, and newer templates may use named placeholders such as {{order_id}} instead. Whichever form you use, three formatting rules cause most of the rejections we see:

The body may not begin or end with a variable. A body that is nothing but {{1}} is rejected every time.
Two variables may not sit adjacent to each other. {{1}} {{2}} needs real words in between.
Every variable needs an example value submitted with the template. A missing example is an invalid format, not a warning.

Component text is also length-capped: headers and footers are limited to a short single line, the body allows a long paragraph but not an article, and button labels are very short. Meta publishes the exact character counts and adjusts them, so build your editor against the documented limits rather than assuming the ones you memorised last year still hold.

Lifecycle: from submitted to disabled

A template moves through a small state machine, and the states arrive as message_template_status_update webhooks:

PENDING. Submitted, awaiting review. Usually minutes.
APPROVED. Sendable. This is the only state from which a send succeeds.
REJECTED. Comes with a machine-readable reason code. Fix and resubmit, or appeal.
PAUSED. Quality-triggered. Recipients blocked or reported messages built from this template, so Meta stopped it temporarily. It resumes by itself.
DISABLED. The end state after repeated pauses. The template is dead and needs to be rebuilt with different content, not resubmitted unchanged.

Pausing is the state teams misread most often. It is not an account penalty and it is not random: it is Meta telling you that this specific piece of copy generated negative feedback. The correct response is to look at who received it and why they objected, not to resubmit the same words under a new name, which simply reproduces the pause on a fresh template.

Why it matters

Templates are the throttle on every outbound WhatsApp programme. You cannot launch faster than review, you cannot personalise beyond your declared variables, and you cannot change your mind about the wording on the morning of the campaign. Teams that treat the template library as product infrastructure, versioned, reviewed, and shipped ahead of the campaign, run smoothly. Teams that treat it as copywriting discover that the campaign is blocked on a reviewer.

The library is also an asset with real switching costs. Approval history and template quality accrue to the WABA. Move to a different account and you start again from zero, which is one more reason to own your WABA.

A rejected template, and the fix

Here is a real shape of failure. A retailer submits a template under utility:

{{1}}, your order {{2}} has shipped. Track it here. Also, everything in our summer range is 30% off this week, grab it before it goes: bit.ly/sale

This fails on four counts at once. It begins with a variable. It claims to be utility while advertising a sale, so the category is wrong. It uses a link shortener, which reads as a phishing signal to a reviewer. And it never names the business, which is the other half of the same signal.

The version that passes, submitted as utility:

Hi {{1}}, your Acme order {{2}} has shipped and should arrive by {{3}}. You can follow it from the button below.

The promotion becomes its own marketing template, sent to the audience that opted in to promotions, with a full acme.com URL button and an opt-out line in the footer. Two templates, two categories, two audiences, and both get approved.

Common mistakes

Writing one template and hoping. Submit the whole campaign set days early. Review time is not yours to control.
Editing an approved template in place. Version the name instead, so the running campaign is never blocked by a re-review.
Blaming the account for a paused template. The pause is about that specific copy and that specific audience.
Using shortened links. Shorteners hide the destination from the reviewer and are a reliable way to collect a scam rejection.
Leaving the opt-out out of marketing templates. A visible way to stop reduces blocks, and blocks are what destroy your quality rating.
Ignoring category re-classification. Meta can move a template between categories after approval, and your cost per message moves with it.

Related concepts

24-hour customer service window: the reason templates exist at all.
Conversation-based pricing: where the category turns into money.
Quality rating: what a badly targeted template destroys.
Opt-in: the permission that should exist before any template is sent.
Interactive message: the free-form counterpart available inside the window.
Drip campaign: a multi-step sequence built entirely out of approved templates.

How Pinlyx handles it

Pinlyx syncs your WABA's template library, shows each template's category, language, approval state and rejection reason in one list, and blocks a campaign from launching on a template that is not currently approved. Variables are mapped to CRM fields visually, with the start, end and adjacency rules checked before submission rather than after rejection. Status and category changes arrive through the Meta webhooks and appear as alerts, so a template that gets paused mid-campaign stops the sequence instead of failing silently. More on WhatsApp CRM.

Decision table · picking the category

Category is decided by content, not by intent.

One promotional sentence promotes the whole template.

Category	Use it when	The one-line test	Commercial effect
`UTILITY`	A message about a transaction the customer already started: order confirmation, shipping update, appointment reminder, payment receipt, account alert.	Would the customer be confused if they had NOT done something first? If yes, it is utility.	Lower rate than marketing, and free in some situations inside an open service window.
`AUTHENTICATION`	A one-time passcode or verification code, and nothing else. Uses a fixed Meta-supplied body structure with a copy-code or one-tap button.	Does the message contain a code the user must enter somewhere else? If yes, it is authentication.	Priced separately, and several markets carry their own authentication rate.
`MARKETING`	Anything promotional, and also anything that mixes promotion into a transactional message. Offers, product news, cart recovery, re-engagement, invitations.	Does any sentence try to make the customer buy, come back or feel curious? Then the whole template is marketing.	Highest rate, tightest per-user frequency controls, and the category most likely to earn blocks.

Rejection reasons · what each one really means

Read the reason code before you rewrite the copy.

Reason	What the reviewer saw	The fix
`INVALID_FORMAT`	The structure breaks a formatting rule: a variable at the very start or end of the body, two variables side by side, missing sample values, or a footer that contains a variable.	Wrap variables in real words, separate them with static text, and supply an example for every placeholder.
`INCORRECT_CATEGORY`	The content does not match the category you claimed. Almost always a promotional sentence inside a template submitted as utility.	Remove the promotional sentence, or resubmit honestly as marketing and accept the higher rate.
`SCAM`	The reviewer read the copy as a phishing or lottery pattern: an unexplained prize, an urgent account problem, a shortened link, or a request for credentials.	Name your business in the body, drop urgency language, and use a full branded URL instead of a shortener.
`ABUSIVE_CONTENT`	The template contains content that violates WhatsApp Commerce or Business policy, including regulated goods and adult content.	Check the Commerce Policy for your vertical before rewriting. Some categories cannot be messaged at all.
`TAG_CONTENT_MISMATCH`	The declared purpose and the actual text disagree, the classic case being an authentication template that also advertises something.	Authentication templates carry a code and nothing else. Move every other sentence into a separate template.

On the wire · create, then send

A utility template that passes review.

# Create it on the WABA
POST /v22.0/{waba-id}/message_templates
{
  "name": "order_shipped_v2",
  "language": "en_US",
  "category": "UTILITY",
  "components": [
    { "type": "HEADER", "format": "TEXT", "text": "Your Acme order is on its way" },
    {
      "type": "BODY",
      "text": "Hi {{1}}, your Acme order {{2}} has shipped and should arrive by {{3}}. You can follow it from the button below.",
      "example": { "body_text": [["Ada", "AC-10432", "Friday 12 Sep"]] }
    },
    { "type": "FOOTER", "text": "Reply STOP to stop these updates" },
    {
      "type": "BUTTONS",
      "buttons": [
        { "type": "URL", "text": "Track order", "url": "https://acme.com/track/{{1}}",
          "example": ["https://acme.com/track/AC-10432"] }
      ]
    }
  ]
}

# Send it from a phone number
POST /v22.0/{phone-number-id}/messages
{
  "messaging_product": "whatsapp",
  "to": "905551112233",
  "type": "template",
  "template": {
    "name": "order_shipped_v2",
    "language": { "code": "en_US" },
    "components": [
      { "type": "body", "parameters": [
          { "type": "text", "text": "Ada" },
          { "type": "text", "text": "AC-10432" },
          { "type": "text", "text": "Friday 12 Sep" } ] },
      { "type": "button", "sub_type": "url", "index": "0",
        "parameters": [{ "type": "text", "text": "AC-10432" }] }
    ]
  }
}

# What you get back when the parameter count is wrong
{ "error": { "code": 132000,
  "message": "Number of parameters does not match the expected number of params" } }

132000

Parameter count does not match the approved template.

132001

Template does not exist in that name and language pair.

132015

Template is paused for quality reasons. Stop the send.

Pre-submission checklist

Seven checks that clear most rejections before you submit.

The body neither starts nor ends with a variable, and no two variables touch.
Every variable has a realistic example value, not the word "test".
The business name appears in the body, so the message is not anonymous.
Links are full branded URLs, never a shortener.
Nothing promotional has crept into a utility or authentication template.
Marketing templates carry a visible way to stop receiving them.
The name is versioned, so the next edit does not block the running campaign.

Message templates: FAQ

What operators ask after their first rejection, and before their first campaign.

Most templates are reviewed automatically within minutes. Meta states review can take up to 24 hours, and in practice anything still pending after an hour is usually queued for a human. Never plan a launch around an unapproved template: submit the whole set several days before the campaign, and check the message_template_status_update webhook rather than refreshing WhatsApp Manager by hand.

The three most common causes are structural rather than editorial. A variable placed at the very start or end of the body is rejected as invalid format. Two variables next to each other with no static text between them is rejected for the same reason. And a template submitted as utility that contains one promotional sentence is rejected as an incorrect category. Rejections cite a machine-readable reason, so read the reason field before rewriting anything.

Utility is about something the customer already did: an order, a booking, a payment, an account event. Marketing is about something you want them to do. The line is decided by content, not by intent, so one promotional sentence appended to an order confirmation converts the entire template into marketing. That matters commercially because marketing carries the highest rate, the tightest per-user frequency controls and the greatest risk of blocks.

You can edit a template, and an approved template can be edited a limited number of times per period, but any meaningful edit sends it back through review. Category changes and body rewrites are treated as new content. Because the template is referenced by name plus language, the safer production pattern is versioned names such as order_confirm_v3, which lets the old version keep running while the new one waits for approval.

Paused is a quality state, not a policy rejection. When recipients block or report messages built from a specific template, Meta pauses that template so it cannot be sent, then unpauses it automatically after a cooling-off period. Repeated pauses escalate to a longer pause and eventually to the template being disabled permanently. Treat the first pause as a content problem in that exact template, not as a general account problem.

Yes. Templates belong to the WABA, so every phone number under that account can send them, and a template approved for one number needs no separate approval for another. The flip side is that template-level trouble is account-level trouble: a paused or rejected template affects the whole WABA, which is one of the strongest arguments for keeping different brands in different accounts.

Keep reading

24-hour customer service window

The rule that makes templates mandatory in the first place.

Conversation-based pricing

How a template category turns directly into cost.

Quality rating

What a badly targeted template destroys first.

Opt-in

The permission that must exist before any template goes out.

Drip campaign

Multi-step sequences assembled from approved templates.

WhatsApp CRM

Template library, approval state and campaigns in one place.

Ready to ship

Ship templates that get approved.

Pinlyx validates structure before submission, syncs approval state from Meta, and refuses to launch a campaign on a paused template.

Start free Talk to sales

Free forever plan · GDPR-ready · No credit card required