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 starts as PENDING.
2. Wait for review. 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.

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

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.
• 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.