Skip to navigation
Developer API

Templates

A template is a WhatsApp message that Meta approved in advance. It is the only message that WhatsApp delivers outside the 24-hour window. It is also the only way to start a conversation on WhatsApp.

To send a template, add template_params to the send request:

{
  "inbox_id": 5,
  "phone_number": "+971500000000",
  "template_params": {
    "name": "order_confirmation",
    "language": "en",
    "category": "UTILITY",
    "processed_params": { "body": { "1": "121212" } }
  }
}
FieldMeaning
nameThe name of the approved template. Necessary
languageThe language code of the template, for example en or en_US. Necessary
categoryThe category of the template, for example UTILITY or MARKETING
processed_paramsThe values for the variables of the template

The content of a template message

On a WhatsApp inbox, content is optional when you send template_params. The API finds the approved template with the same name and language on the inbox. It puts your values into the body of the template, and it uses the result as content. Your agents see this text in the conversation, and search finds it.

If you send content too, the API keeps your content. It does not send content to WhatsApp. WhatsApp gets only the template name and the values.

The API returns 422 with the code content_required in 2 cases:

  • content is empty, and the inbox has no approved template with that name and language.
  • content is empty, and the inbox is not a WhatsApp inbox. A Twilio inbox always needs content, because the API cannot make the text from a Twilio template.

Find a template name

You create templates in the WhatsApp Manager of Meta. After Meta approves a template, it syncs to your WhatsApp inbox. To see the name, the language, and the category of a template, use the template list in a conversation:

1

Open a conversation

Open a conversation in the WhatsApp inbox.

2

Open the template list

In the reply box, click the button with the tooltip Whatsapp Templates. The Whatsapp Templates dialog opens.

3

Read the template

Find the template. The list shows its name, its Language, its body, and its Category. If a new template is not in the list, click Refresh templates.

The developer API has no endpoint that lists templates.

Send the language of the approved template exactly. To WhatsApp, en and en_US are 2 different templates. Send the code exactly as the Language of the template list shows it. If you send content and the language is wrong, the API accepts the request with 201, and the delivery fails later.

Fill in the variables

processed_params gives a value to each variable of the template. The shape depends on the provider of your WhatsApp inbox. Check the provider in the settings of the inbox before you write the request.

A template with the variables {{1}} and {{2}}:

{ "processed_params": { "body": { "1": "121212", "2": "3 days" } } }

A template with no variables needs no processed_params. Send name and language only.

After the template

When the customer replies, the 24-hour window opens. While the window is open, you can send plain content with no template_params.