Templates

A template is a message format that WhatsApp reviews and approves before you can use it. Templates are the only messages you can send outside the 24-hour window, so you need them to start conversations, send notifications and send one-time passwords.

How it worksCopy Anchor Link

1. Create the template with Create a template. It's usually PENDING, but WhatsApp can approve or reject it straight away, so check status in the response. Authentication templates are often APPROVED at once.
2. Wait for review, if it's PENDING. WhatsApp usually decides within minutes, and sometimes takes up to 24 hours. The result arrives on your webhook as a template status event (APPROVED or REJECTED, with a reason). You can also retrieve the template.
3. Send it with Send a message, using "type": "template", the template's name and language, and a value for each placeholder.

CategoriesCopy Anchor Link

Every template has a category. It decides how WhatsApp reviews and prices it:

• MARKETING: offers, announcements, newsletters, and anything that encourages a purchase.
• UTILITY: updates about something the customer asked for or bought, such as order confirmations, shipping updates and appointment reminders.
• AUTHENTICATION: one-time passwords (OTP) only. The wording is fixed by WhatsApp; you choose the buttons and expiry.

If WhatsApp thinks you picked the wrong category, it changes it and sends a template category event. Set allow_category_change: true to accept this instead of having the template rejected.

Parts of a templateCopy Anchor Link

• Header (optional): text (up to 60 characters), an image, a video, a document or a location.
• Body (required): the main text, up to 1,024 characters, with WhatsApp formatting.
• Footer (optional): small grey text, up to 60 characters.
• Buttons (optional): up to 10 in total:
  • quick replies,
  • up to 2 website links,
  • 1 phone number,
  • 1 copy-code button,
  • or a catalog or multi-product button.
• Carousel (optional): 2 to 10 swipeable cards, each with its own image or video, text and buttons.
• Limited-time offer (optional): an expiring-offer banner with a countdown. Marketing templates only, with stricter rules; see Rules worth knowing.

PlaceholdersCopy Anchor Link

Write placeholders as {{1}}, {{2}} and so on, and give an example value for each so the reviewers understand the template. When you send, you supply the real values in the same order.

{ "type": "BODY", "text": "Hi {{1}}, your order {{2}} has shipped.", "example": { "body_text": [["Priya", "#1042"]] } }

Named placeholdersCopy Anchor Link

You can name placeholders instead, such as {{first_name}}: lowercase letters and underscores, each name used once. Set "parameter_format": "NAMED" when you create the template, and give the examples by name in body_text_named_params (or header_text_named_params for a text header):

{ "type": "BODY", "text": "Hi {{first_name}}, your order {{order_id}} has shipped.", "example": { "body_text_named_params": [{ "param_name": "first_name", "example": "Priya" }, { "param_name": "order_id", "example": "#1042" }] } }

When you send, add parameter_name to each text value: { "type": "text", "parameter_name": "first_name", "text": "Priya" }. Templates you read back carry parameter_format, POSITIONAL or NAMED, so you know which way to fill them. Templates made in WhatsApp Manager can be either.

Rules worth knowingCopy Anchor Link

• Names use lowercase letters, numbers and underscores only, such as order_shipped. One name can have several languages.
• Media headers need a sample file when you create the template. Upload it with Template samples and put the returned handle in example.header_handle. When you send, you supply the real file.
• Editing an approved template sends it back for review. You can edit an approved template once a day, and 10 times in 30 days.
• Deleting by name deletes every language of that template. You can't reuse a deleted name for 30 days. A deleted template can still appear in List templates for a minute or two.
• Limited-time offers are for MARKETING templates only. The header is optional and must be an image or a video. There's no footer, the body is up to 600 characters, and a website button is required; a copy-code button is optional. Customers on WhatsApp Web and desktop don't see the offer.
• Quality is judged on how customers react. A template that many customers block or report can be PAUSED for a few hours, and then DISABLED.