> This page is for Omni Channel.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.hams.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.hams.ai/_mcp/server.

# Templates

> How to send an approved WhatsApp template, and what to put in processed_params.

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:

```json
{
  "inbox_id": 5,
  "phone_number": "+971500000000",
  "template_params": {
    "name": "order_confirmation",
    "language": "en",
    "category": "UTILITY",
    "processed_params": { "body": { "1": "121212" } }
  }
}
```

| Field              | Meaning                                                                   |
| ------------------ | ------------------------------------------------------------------------- |
| `name`             | The name of the approved template. Necessary                              |
| `language`         | The language code of the template, for example `en` or `en_US`. Necessary |
| `category`         | The category of the template, for example `UTILITY` or `MARKETING`        |
| `processed_params` | The 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:

#### Open a conversation

Open a conversation in the WhatsApp inbox.

#### Open the template list

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

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

> **Warning**
>
> 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.

#### WhatsApp Cloud: positional

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

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

#### WhatsApp Cloud: named

A template with the variable `{{order_id}}`:

```json
{ "processed_params": { "body": { "order_id": "121212" } } }
```

#### WhatsApp Cloud: header, footer, and buttons

```json
{
  "processed_params": {
    "header": { "1": "Order 121212" },
    "body": { "1": "121212" },
    "footer": { "1": "Hams" },
    "buttons": [{ "type": "url", "parameter": "121212" }]
  }
}
```

For a header with an image, a video, or a document, send `header.media_url` and `header.media_type`. You can also send `header.media_name`. The API sends each button in the order of the list.

#### Twilio

Twilio takes a flat map of variable name to value. It has no `body` level:

```json
{ "processed_params": { "1": "121212", "2": "3 days" } }
```

If you send the WhatsApp Cloud shape to a Twilio inbox, Twilio gets 1 variable with the name `body`. The template then shows the wrong text.

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

## Related

* [Messages](/omni-channel/api/messages)
* [WhatsApp campaigns](/omni-channel/whatsapp-campaigns)
* [Inboxes and channels](/omni-channel/inboxes)
* [Errors](/omni-channel/api/errors)