WhatsApp API: Message Templates

Last update:

A message template is a standardized message pre-approved by WhatsApp, used when a business wants to message a customer proactively (e.g., when the customer hasn't reached out first, or hasn't replied within the last 24 hours).

A template must pass WhatsApp's review before it can be used.

Requirements

Before creating a message template, make sure:

How to create a message template

Step 1: Go to the create page

Log in to the platform, then go to Settings > Message Templates, select one of the WhatsApp channel, and select Create.


Step 2: Choose how to start

  • Create a blank template: Build the content from scratch

  • Create from the template library: Start from a system default template and edit it (see the screen for examples)

  • Copy an existing template: Copy a template to another WhatsApp Channel for use there. You can still edit the content after copying, then save it to send for a new review.

The steps below use Create a blank template as the example.


Step 3: Fill in the template details

Fill in the following fields in the order they appear on screen:

i. Template is visible to

Choose which group can see this template. The default is "All Groups"

ii. Name

  • Made up of lowercase English letters (a–z), numbers (0–9), and underscores (_)

  • Up to 512 characters

  • Example: intro_message01

  • Recommended to keep unique: avoid reusing a name from an existing or deleted template

iii. Template Type

Determines the format the message is displayed in. There are 4 types:

Template type

Display format

Button

Standard

Text / Image / Document / Video

Quick Reply, URL, Phone Number, Flow

Catalog

Displays your business catalog

View Catalog

Single product

Displays a single product

View Product

Product carousel

Displays multiple products in a carousel

View Product / URL


iv. Category

Determines how WhatsApp reviews this template. There are 3 options:

Category

Best for

Example

Marketing

Brand promotion, sales campaigns, re-engagement

"The holidays are here! Join us at {{1}} on November 24."

Utility

Anything tied to a customer's active transaction, account, subscription, or interaction

"Your order {{1}} is confirmed. We'll notify you when it ships."

Authentication

Sending a one-time passcode (OTP); reviewed under the strictest standard

"{{1}} is your verification code. Please don't share it with anyone."

📌When the template type is set to "Catalog," "Single Product," or "Product Carousel," the category is automatically set to Marketing.


v. Language

Choose the language this template will be written in from the dropdown.

vii. Header

From the dropdown menu, you may choose to have no header, input text, or attach Image, a PDF Document and Video as the message Header.

  • When selecting Image, Document or Video as the message Header, you will be required to upload a sample for approval.

viii. Body

The main message content, up to 1024 characters.

  • You can add "Variables" in the format {{number}} (e.g., {{1}}, {{2}}), listed in order

  • What variables do: at send time, the system automatically fills in each customer's own data (such as name, order number, or amount), so you don't have to edit the message for every customer by hand.

    • E.g., if the body reads "Hi {{1}}, your order {{2}} has shipped," each customer receives the message with {{1}} and {{2}} automatically replaced with their own name and order number.

  • Provide a sample value for every variable, for WhatsApp's review

ix. Footer

  • Supporting text shown below the message body, displayed in italic gray text

  • Up to 60 characters


Example: Completed Form


x. Buttons

Buttons are interactive elements that guide the customer toward a specific action. There are 4 types:

Button type

Description

Quick Reply

Gives a one-tap reply option; sends preset text when clicked

URL

Takes the customer straight to a specified webpage

Phone Number

Lets the customer call a specified number directly

Flow

Opens an interactive in-app form inside WhatsApp


Button quantity and combinations:

  • When using only one button type:

    • up to 10 Quick Reply buttons, or
    up to 2 URL buttons (2 static URLs, or 1 static + 1 dynamic URL), or
    1 Phone Number button, or
    1 Flow button (without other button types)

  • When combining button types:

    • Quick Reply can be combined with URL and/or Phone Number: each URL or Phone Number button added reduces how many Quick Reply buttons you have available

    Buttons

    Max URL buttons

    Max Phone buttons

    Max Quick Replies

    Total buttons

    All Quick Replies

    0

    0

    10

    10

    Max URLs only

    2

    0

    8

    10

    Max Phone only

    0

    1

    9

    10

    Mixed combo

    2

    1

    7

    10



    buttons of the same type must be grouped together in sequence:

    Combination

    Status

    Quick Reply + Quick Reply

    ✅ Valid

    Quick Reply + Quick Reply + URL + Phone Number

    ✅ Valid

    URL + Phone + Quick Reply + Quick Reply

    ✅ Valid

    Quick Reply + URL + Quick Reply

    ❌ Invalid

    URL + Quick Reply + URL

    ❌ Invalid


📌Display tip: With 3 buttons or fewer, the template displays in full on every device, including WhatsApp desktop. With more than 3 buttons, the message shows the first 2 buttons, and the rest are collapsed into a "See all options" link.


Step 4: Preview the template

The screen shows a Preview of how the message will finally look, so you can check the layout before sending it for review.

Step 5: Save and submit for review

Once every field is filled in, select Save. The template is sent to WhatsApp for review.

Step 6: Check the review status

Select Sync to check the review progress. Review can take up to 24 hours.

Step 7: Use the template

Once the status shows "Approved," the template is ready to use for sending messages or creating a broadcast.

Template Quality Rating

Every approved template carries a quality rating — High, Medium, or Low — based on usage, customer feedback, and engagement. A higher rating means more stable use of the template; if a template keeps receiving negative feedback, its rating can drop and the template may eventually be paused. We recommend checking your templates' quality ratings regularly and adjusting content early to keep the customer experience strong.


FAQs

FAQs

1. How is a message template different from a regular message?

  • A template must pass WhatsApp's review before it can be used. It's mainly for when a business needs to message a customer proactively — for example, when the customer hasn't reached out first, or hasn't replied within the last 24 hours.

  1. How do I choose a category (Marketing / Utility / Authentication)?

  • Choose based on purpose: Marketing for brand promotion and sales campaigns; Utility for anything tied to a transaction, account, or subscription; Authentication for sending a one-time passcode (OTP).

  1. What if I want to personalize each message — like using each customer's own name or order details?

  • Add "variables" to the body (in the format {{1}}, {{2}}, etc.). At send time, the system automatically fills in each customer's own data (such as name or order number), so the message is personalized without editing it by hand for every customer.

  1. How long does review take after I submit a template?

  • According to WhatsApp, review typically takes 24 hours.

  1. Why do message templates get rejected, and what should I do afterward?

  • Common reasons a template gets rejected include parameter formatting, content that violates WhatsApp's guidelines, and character count or formatting issues. Once you understand the reason, simply revise the content and resubmit it for review.

  1. Why can't an "Approved" template be delivered to my customers successfully?

  • Delivery failures can be related to the message content, the recipient's status, WhatsApp's messaging policies, or other system factors.

  • If an error appears when sending, check the error code and error message the system returns first, and reach out to support for help if needed.


  1. Are message templates chargeable?

  • Under Meta's pricing policy in effect since July 1, 2025, WhatsApp charges on a per-message basis: a template message is only charged once it's successfully delivered to the customer. The actual cost depends on the template's category (Marketing / Utility / Authentication) and the recipient's country.