Getting started with WhatsApp templates

A WhatsApp template is a pre-written message that Meta (the company behind WhatsApp) has reviewed and approved. Order confirmations, appointment reminders, delivery updates and promotional offers are all typical templates.

This page explains what templates are, how Meta's approval works, and how to create one through the API.

Why you need templates

WhatsApp only lets you send a normal, free-form message within 24 hours of the customer's last message to you. To contact a customer outside that window, or to start a new conversation, you must use an approved template.

INFO

The 24-hour rule and template approval are Meta's rules for WhatsApp, not Chronox limits. They apply to every business on WhatsApp.

What a template is made of

Part	Required?	What it is
Header	No	A title at the top: text, an image, a video or a document.
Body	Yes	The main message.
Footer	No	A short line of small text at the bottom.
Buttons	No	Buttons the customer can tap, such as Visit website or Call us.

Personalising a template

A template can contain blanks (also called variables) that you fill in each time you send it, such as the customer's name or an order number. You write a blank inside double curly brackets:

Hi {{customer_name}}, your order {{order_id}} has been shipped.

Follow these rules when writing blanks:

Use only lowercase letters, numbers and underscores, for example {{customer_name}}. Numbered blanks like {{1}} and {{2}} also work.

Don't mix named and numbered blanks in the same template.

Include enough text around the blanks. A template that's mostly blanks is refused. As a guide, your body needs at least three words for every blank, plus one.

Category	Use it for
Marketing	Promotions, offers, newsletters and anything that encourages a purchase.
Utility	Updates about something the customer has already asked for or bought, such as an order confirmation or delivery update.
Authentication	One-time passcodes for logging in or verifying an account.

Template types

Most templates are Basic: a header, body, footer and buttons. Chronox also supports more advanced types:

Type	What it is
Basic	A standard template. Used if you don't choose a type.
Carousel	A set of cards the customer can swipe through, each with its own image and buttons.
Flow	A template that opens a WhatsApp form.
Catalog	A template that shows products from your catalogue.
Call Permission Request	A template that asks the customer for permission to call them on WhatsApp.

NOTE

Interactive messages are a separate kind of message you can also create with Create Whatsapp Template. They are not sent to Meta for review, so they're ready to use straight away. Because they aren't approved templates, WhatsApp only lets you send them within the 24-hour window.

How approval works

When you create a template, Chronox sends it to Meta for review. The template's status tells you where it is in that process.

Status	What it means	Can you send it?
`PENDING`	Meta is still reviewing it.	No
`APPROVED`	Meta has approved it.	Yes
`REJECTED`	Meta didn't approve it.	No
`PAUSED` / `DISABLED`	Meta has stopped the template, usually because customers reported or blocked it.	No

Only templates with the status APPROVED can be sent. Trying to send any other template returns the error ERROR! The WhatsApp template is not available for use.

TIP

Statuses come directly from Meta, which may add new ones over time. In your code, treat APPROVED as the only status that can be sent, and compare statuses without worrying about upper or lower case.

How long review takes

Meta usually reviews a template within a few minutes, but it can take up to 24 hours. Chronox has no control over how long this takes.

Checking the status

The status is updated automatically when Meta finishes its review. To check it, call Get Whatsapp Template Details and look at whatsapp_template_metadata.meta_whatsapp_template_status_name:

{
  "whatsapp_template_metadata": {
    "meta_whatsapp_template_status_name": "APPROVED",
    "whatsapp_template_metadata_error_reason": null
  }
}

The API doesn't notify you when the status changes. Check again every few minutes until the template is no longer PENDING, and don't check more often than you need to (see Rate limiting).

If your template is rejected

If Meta rejects your template while you're creating it, Create Whatsapp Template returns an error with Meta's reason, and nothing is saved.

If Meta rejects it later during review, the status changes to REJECTED. The API doesn't include Meta's reason in this case. You can see it in Meta's WhatsApp Manager.

To try again, fix the problem and create a new template with a different name. The rejected template still uses its name, so reusing that name returns Template name already exists.

Creating a template

Create Whatsapp Template needs some values, such as the category and language, as ID numbers rather than words. The lookup endpoints give you the list of valid IDs for each one.

Find your WhatsApp account ID

Call Get Meta Integration and note your meta_integration_whatsapp_id. This tells Chronox which WhatsApp account the template belongs to.

Look up the IDs you need

Call the lookup endpoints for the parts you want to use, and pick the matching ID from each list (see the table below).

Send the create request

Call Create Whatsapp Template with your IDs and message text. If it works, the response contains your new template with the status PENDING.

Wait for approval

Check the status with Get Whatsapp Template Details until it's APPROVED. You can then send it with Send Whatsapp Template.

Which lookup to use for each field

Lookup endpoint	Gives you	Use it for this field
Get Whatsapp Template Category	Marketing, Utility, Authentication	`whatsapp_template_category_id`
Get Whatsapp Languages	Every language WhatsApp supports	`whatsapp_language_id`
Get Whatsapp Template Type	Basic, Carousel, Flow and so on	`whatsapp_template_type_id`
Get Whatsapp Template Header Type	Text, Image, Video, Document	`whatsapp_template_header_type_id`
Get Whatsapp Template Button Type	Button types, such as Quick reply and Call to action, and their options	The buttons in your template
Get Whatsapp Template Dynamic Variable Type	Where a blank can be used: body, header, button or carousel header	The blanks in your template
Get Whatsapp Template Interactive Type	Kinds of interactive message, such as reply buttons or a list	`interactive_type_id` (interactive messages only)

TIP

These lists rarely change. Fetch them once, save the results, and reuse them. Get Whatsapp Template Button Type returns a lot of detail and can take several seconds to respond.

A simple example

This request creates a basic utility template with only a body:

Value in the example	Where it comes from
`123`	Replace with your own `meta_integration_whatsapp_id` from Get Meta Integration.
`1`	Basic, from Get Whatsapp Template Type.
`2`	Utility, from Get Whatsapp Template Category.
`15`	English, from Get Whatsapp Languages.

For headers, footers, buttons and blanks, see the full example on the Create Whatsapp Template page.

Naming your template

Use lowercase letters, numbers and underscores only, for example order_shipped.

Each name must be unique within your WhatsApp account, including templates that were rejected.

Common mistakes

Error message	What went wrong
Template name already exists.	Choose a new name.
Invalid body!	A required value is missing or an ID doesn't match the lookup lists. Check the category, language and body.
This template contains variable parameters with incorrect formatting…	A blank isn't written correctly. Use `{{lowercase_name}}`.
Marketing template body can contain a maximum of 10 emojis.	Remove some emojis.
… cannot have more than 2 consecutive line breaks.	Remove the extra blank lines.

See Errors for the full list.

What this section doesn't cover

Editing or deleting templates. Do this in the Chronox dashboard. The API can list, view and create templates only.

Sending templates. See the Messaging section.

Meta's content rules. Meta decides what's allowed in a template. See Meta's WhatsApp Business policies for details.

Getting started

Getting started with WhatsApp templates#

Why you need templates#

What a template is made of#

Personalising a template#

Categories#

Template types#

How approval works#

How long review takes#

Checking the status#

If your template is rejected#

Creating a template#

Which lookup to use for each field#

A simple example#

Naming your template#

Common mistakes#

What this section doesn't cover#

Getting started with WhatsApp templates

Why you need templates

What a template is made of

Personalising a template

Categories

Template types

How approval works

How long review takes

Checking the status

If your template is rejected

Creating a template

Which lookup to use for each field

A simple example

Naming your template

Common mistakes

What this section doesn't cover