Updated on October 29, 2026
A WhatsApp Business API message template is a message pre-approved by Meta, and it is the only kind of message you can send outside the 24-hour customer service window. You create the template via API with a name, language, category (marketing, utility or authentication) and components; Meta reviews it within 24 hours and, if approved, you send it by filling in the variables. The category sets the price, and any promotional intent in the text makes Meta treat a utility template as marketing.
This guide shows how to build, create and send templates with real payloads, why they get rejected, and how to write notifications that stay in the utility category.
When a template is required
The WhatsApp Cloud API separates two kinds of messages. Free-form messages (text, images, buttons, lists) can only be sent while the 24-hour window is open, that is, after the user has messaged or called the business. Outside it, only approved templates go out.
In practice, templates are what you use to:
- notify someone about an order, payment, appointment or account change;
- send a verification code (OTP);
- send offers and campaigns to people who agreed to receive them;
- reach back out to someone who hasn’t talked to you in more than 24 hours.
The three template categories
Every template needs a category. Meta validates the choice based on the content, and the category is used for billing (see the Brazil rates in WhatsApp API pricing in Brazil and other markets in WhatsApp API pricing by country). For a deeper look at how Meta decides, see WhatsApp template categories.
| Category | What it’s for | Accepted examples | Watch out for |
|---|---|---|---|
MARKETING | Awareness, sales, retargeting, app promotion, relationship building | Coupon, abandoned cart, subscription renewal with a discount, birthday | Also gets templates with mixed content (notice + promotion) or vague content, such as just {{1}} |
UTILITY | Following up on a user action or request | Order confirmation and tracking, account alert, billing reminder, survey about a specific interaction | Must be non-promotional and specific to the user, or essential (security, recall, privacy policy change) |
AUTHENTICATION | One-time code to verify identity | “{{1}} is your verification code.” | Requires an OTP button (copy code or one-tap autofill); no URLs, media or emoji; parameters up to 15 characters |
Verification codes can only go in authentication templates. When Meta detects a marketing or utility template that should be authentication, it notifies you and changes the status to REJECTED on the first day of the following month.
Want to try it while you read? Create a Vectalk account and send your first message through the official API. Create free account →
Anatomy: the components of a template
A template has up to four components. Only the body is required.
| Component | Required | Main limits |
|---|---|---|
Header (HEADER) | No | Text up to 60 characters with 1 parameter; or media (image, video, document; GIF only through the Marketing Messages API); or location (utility and marketing only) |
Body (BODY) | Yes | Up to 1,024 characters, multiple parameters |
Footer (FOOTER) | No | Up to 60 characters, text only |
Buttons (BUTTONS) | No | Up to 10 in total, with per-type limits |
The most common buttons follow these rules:
| Button type | Maximum | Details |
|---|---|---|
QUICK_REPLY | 10 | Label up to 25 characters; tapping sends the text as a user message |
URL | 2 | Label up to 25 characters; URL up to 2,000 characters with 1 variable at the end |
PHONE_NUMBER | 1 | Label up to 25 characters; number up to 20 characters |
COPY_CODE | 1 | Copied text up to 20 characters (e.g., a coupon) |
FLOW | — | Opens a WhatsApp Flow |
Quick replies and other buttons must be grouped (all quick replies together). Templates with 4 or more buttons, or with a quick reply mixed with another type, can’t be viewed on WhatsApp desktop: the user is prompted to open them on a phone. With more than three buttons, the message shows two and groups the rest under “See all options”.
How to create a template via API
On the Cloud API directly, creating a template is a POST to the message_templates endpoint of your WhatsApp Business Account (WABA). Since the account structure changed on September 23, 2026, templates, billing and webhooks belong to what Meta calls the messaging account, which is still identified by the WABA ID; the new model is explained in WhatsApp account vs. messaging account.
curl 'https://graph.facebook.com/v26.0/YOUR_WABA_ID/message_templates' \
-H 'Authorization: Bearer META_TOKEN' \
-H 'Content-Type: application/json' \
-d '{ "name": "template_name", "language": "en_US", "category": "UTILITY", "components": [ { "type": "BODY", "text": "..." } ] }'With Vectalk, the body is the same. Only the base URL and token change: with an instance token, the WABA is resolved automatically and you don’t pass its ID in the path.
curl -X POST https://apis.vectalk.com.br/api/templates \
-H "Authorization: Bearer YOUR_INSTANCE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "order_confirmed",
"language": "en_US",
"category": "UTILITY",
"components": [
{ "type": "HEADER", "format": "TEXT", "text": "Order confirmed" },
{
"type": "BODY",
"text": "Hi {{1}}, your order {{2}} is confirmed and will arrive within {{3}} business days.",
"example": { "body_text": [["Marina", "48213", "5"]] }
},
{ "type": "FOOTER", "text": "Example Store" },
{
"type": "BUTTONS",
"buttons": [
{ "type": "URL", "text": "Track order", "url": "https://store.example.com/orders/{{1}}", "example": ["https://store.example.com/orders/48213"] }
]
}
]
}'The response includes the id, the status (usually PENDING) and the category. The review result arrives through the message_template_status_update webhook, which Vectalk forwards in Meta’s format to your registered URLs (see the guide to WhatsApp API webhooks). To look it up later, use GET /api/templates?name=order_confirmed.
Rules that prevent errors at creation time:
- Names accept only lowercase letters, numbers and underscores, up to 512 characters. Names aren’t unique: the same name can exist in different languages, and each language counts as one template.
- Meta allows up to 100 templates created per hour in each messaging account.
- A messaging account can hold up to 250 templates if the business portfolio isn’t verified. With a verified portfolio and at least one approved display name, the ceiling rises to 6,000.
- Meta doesn’t translate anything. Each language needs its own text and its own examples.
- On Meta, a media header requires a handle obtained through the Resumable Upload API, and the sample image is reviewed too.
Variables: positional or named
The parameter_format field sets the format. Without it, the default is positional.
Positional variables use {{1}}, {{2}} and so on, in sequence. Sample values at creation and real values at send time follow the order in which they appear in the text.
Named variables use lowercase names with underscores, such as {{customer_name}}. The order of values no longer matters, which reduces bugs when the text changes:
{
"name": "order_shipped",
"language": "en_US",
"category": "UTILITY",
"parameter_format": "named",
"components": [
{
"type": "BODY",
"text": "Hi {{customer_name}}! Your order {{order_number}} is out for delivery with tracking code {{tracking}}. We'll let you know when it arrives.",
"example": {
"body_text_named_params": [
{ "param_name": "customer_name", "example": "Marina" },
{ "param_name": "order_number", "example": "48213" },
{ "param_name": "tracking", "example": "BR123456789" }
]
}
}
]
}At send time, each named parameter carries parameter_name:
{ "type": "text", "parameter_name": "tracking", "text": "BR987654321" }Every parameter needs a sample value at creation. Without samples, the reviewers have no way to judge the final text.
Sending the template
Sending uses the messages endpoint with type: "template". Through Vectalk:
curl -X POST https://apis.vectalk.com.br/api/messages \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"messaging_product": "whatsapp",
"to": "5584999999999",
"type": "template",
"template": {
"name": "order_confirmed",
"language": { "code": "en_US" },
"components": [
{ "type": "body", "parameters": [
{ "type": "text", "text": "Marina" },
{ "type": "text", "text": "48213" },
{ "type": "text", "text": "5" }
]},
{ "type": "button", "sub_type": "url", "index": "0", "parameters": [
{ "type": "text", "text": "48213" }
]}
]
}
}'With an organization token, also include the sender number’s phone_number_id in the body. These are the most common send errors:
| Code | Meaning | What to do |
|---|---|---|
132000 | Number of parameters doesn’t match the template | Check how many parameters each component expects |
132001 | Template doesn’t exist in that language or isn’t approved | Check name, language code and status |
132012 | Parameters in a different format from the template | Use the right format (positional or named) |
132015 | Template paused for low quality | Wait out the pause or edit the content |
132016 | Template disabled after repeated pauses | Create a new template with different content |
Why templates get rejected
Review combines automated systems and manual analysis and takes up to 24 hours. The most common reasons Meta lists are:
- Variable formatting: missing or mismatched braces, special characters such as
#,$or%inside the variable, numbering out of sequence ({{1}},{{2}},{{5}}). - Too many variables for the text length: a short body with many parameters gets rejected. Add fixed text or cut variables.
- Variable at the edges: the text can’t start or end with a parameter.
- Requests for sensitive data: full card number, bank account or national ID number. Asking only for the last digits is accepted.
- Threatening content: threatening the customer with legal action or public shaming.
- Commerce Policy violations: products and services that are prohibited on the platform.
- Duplicates: the same body and footer wording as an existing template (this rule doesn’t apply to authentication).
If you disagree with a rejection, you can edit and resubmit, or appeal in WhatsApp Manager with sample values. Meta decides appeals within 24 hours. The full troubleshooting walkthrough is in WhatsApp template rejected.
To edit via API, Meta allows changes to templates with status APPROVED, REJECTED or PAUSED. An edit replaces all components at once, and an approved template can be edited up to 10 times in 30 days or once in 24 hours. With Vectalk, editing is a POST /api/templates/{templateId} with the new components; the Vectalk docs list APPROVED and REJECTED templates as editable.
How to keep utility from turning into marketing
This is the most expensive template problem. Under Meta’s rules, a template is utility only if it meets two conditions at the same time:
- It is non-promotional, with no persuasive intent.
- It is specific to the user (tied to their order, account, service or transaction) or essential (security, recall, fraud alert, privacy policy change).
Since April 9, 2025, if you submit a template as UTILITY and Meta concludes it’s marketing, the template is approved as MARKETING instead of rejected. You only notice by checking the category in the response or the webhook.
After approval, the template keeps being evaluated. Meta runs a recurring process that recategorizes utility templates that should be marketing, with 1 day’s notice via the template_category_update webhook and email. The payload carries the template’s category in new_category and the category it should have in correct_category:
{
"field": "template_category_update",
"value": {
"message_template_id": 278077987957091,
"message_template_name": "payment_reminder",
"message_template_language": "en_US",
"new_category": "UTILITY",
"correct_category": "MARKETING",
"category_update_timestamp": 1746169200
}
}On Meta’s API you can also list templates with ?fields=category,correct_category and compare the two fields. When they differ and correct_category is filled in, the category is updated to that value on the first day of the next month. You have 60 days to request a review in Business Support Home.
Here is the difference in practice:
| Text | Likely category | Why |
|---|---|---|
| “Your order {{1}} has shipped with tracking code {{2}}. We’ll let you know when it’s delivered.” | Utility | Specific to the order, no promotion |
| “Your order {{1}} has shipped. Enjoy 10% off your next purchase!” | Marketing | Mixes a notice with an offer |
| “Your subscription expires on {{1}}. Renew today with a discount.” | Marketing | Renewal attempt with an incentive |
| “Your {{1}} bill is due on {{2}} and will be charged to the card ending in {{3}}.” | Utility | Account alert with no persuasion |
| “How was your experience with us?” | Marketing | Generic survey, not tied to a specific interaction |
| “You contacted our support about order {{1}}. How did we do?” | Utility | Survey tied to a specific interaction |
A checklist before sending as utility:
- Does the text mention something about the user (order number, date, amount, ticket number)?
- Does any word sound like an invitation to buy, renew or “take advantage”?
- Does the button lead to the order or account page rather than the storefront?
- Is the footer free of slogans or sales pitches?
Repeatedly classifying marketing as utility has consequences. Meta describes an escalating set of restrictions for accounts that do this:
| Level | What happens | Duration |
|---|---|---|
| Warning | Written warning to the messaging account admins; utility-to-marketing changes become immediate, with no advance notice | Ongoing |
| Rate limiting | Utility message volume capped in a rolling 24-hour window; the excess is rejected | At least 7 days |
| Utility restriction | All the account’s approved utility templates become marketing; creating new ones and requesting category reviews are blocked | 7 days (30 for repeat violations) |
| Portfolio-level restriction | The same, across all messaging accounts in the portfolio | 30 days |
These actions arrive through the account_update webhook, with violation_type equal to UTILITY_TEMPLATE_ABUSE (warnings and utility restrictions) or UTILITY_TEMPLATE_ABUSE_RATE_LIMIT (rate limiting).
Template quality and pausing
Each approved template gets a rating based on usage, feedback and engagement: GREEN (high), YELLOW (medium), RED (low) or UNKNOWN (no data yet). A template that reaches RED is paused automatically: 3 hours the first time, 6 hours the second, and disabled the third. While it’s paused, the API rejects sends without charging and without counting them toward the messaging limit.
Pausing the campaigns that depend on the template avoids a queue of errors. The pause doesn’t affect the phone number right away, but Meta warns that frequently sending templates that reach low quality can eventually affect the number. Volume and audience care for large sends through the API are covered in bulk messaging with the official API. If you send marketing at scale, also read about the Marketing Messages API, Meta’s dedicated route for marketing templates.
Frequently asked questions
How long does Meta take to approve a template?
The documentation says the decision comes within 24 hours. Many templates are approved sooner, but plan your launch around the maximum.
Can I send a template to any number?
No. Meta requires the recipient to have given consent (opt-in) to receive messages from your business, and sends outside the window count toward the portfolio’s messaging limit.
Can I change the category of an approved template?
Via API, the category of an approved template can’t be edited. For rejected templates, you can edit the category and resubmit. For templates approved as marketing that you believe are utility, request a review in WhatsApp Manager.
Is a utility template sent inside the 24-hour window free?
Not anymore. Since October 1, 2026, Meta charges for utility templates sent inside the customer service window. The only case in which templates aren’t charged is the free entry point window, which can stay open for up to 7 days for users who arrive through a Click to WhatsApp ad.
Is the template payload on Vectalk different from Meta’s?
No. The creation and send bodies are the same as the Cloud API. Only the base URL (https://apis.vectalk.com.br/api) and the token, generated in the Vectalk dashboard, change.
Create your templates with Vectalk
With Vectalk you create, list, edit and send templates using the same payloads as Meta’s documentation. Template management uses an instance token (one per number), and an organization token can send messages from any of your numbers when you include the phone_number_id. Billing works with a monthly fee plus a prepaid balance: Vectalk puts its own line of credit on your number, each delivered message is deducted from your balance, and you never register a card with Meta. Create your account at apps.vectalk.com.br/register and check the endpoints at docs.vectalk.com.br. If you have questions, use the contact page.
Sources checked on October 29, 2026: Template overview, Template components, Template categorization, Template review, Template management, Template pausing, Error codes.
Put your business on the official WhatsApp
Create your account, connect your number to the official API (you can keep the app with coexistence) and start serving customers and sending messages.