> ## Documentation Index
> Fetch the complete documentation index at: https://docs.impellabs.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Templates

> Create, read and change the WhatsApp message templates of a tenant, and send one.

A WhatsApp template is a message that Meta reviews before you can send it. You need a template to write to a customer
after the 24-hour window closes, or to write first. Templates belong to the WhatsApp Business Account of the tenant, so
the tenant needs a [connected number](https://docs.impellabs.tech/partners/channels/whatsapp/setup.md) first. Without one, the calls answer 400
`WhatsApp is not connected.`

When the tenant has more than one number, add `phone_number_id` to pick the account. Without it, the first connected
number is used. Read calls need the `channels:read` scope. The other calls need `channels:write`.

## List templates

```bash theme={null}
curl "https://api.impellabs.tech/api/v1/partner/tenants/acme-001/templates/" \
  -H "Authorization: Bearer implpk_..."
```

The call reads the templates again from Meta, then lists them. `limit` sets how many to return. The default is 100.

```json theme={null}
{
  "data": [
    {
      "id": "400000000000001",
      "name": "appointment_reminder",
      "status": "APPROVED",
      "category": "UTILITY",
      "language": "en_US",
      "components": [{ "type": "BODY", "text": "Hi {{1}}, see you at {{2}}." }],
      "rejected_reason": "",
      "quality_score": { "score": "UNKNOWN" }
    }
  ]
}
```

`GET /api/v1/partner/tenants/{external_ref}/templates/{name}/` returns the template in every language.

## Create a template

```bash theme={null}
curl -X POST https://api.impellabs.tech/api/v1/partner/tenants/acme-001/templates/ \
  -H "Authorization: Bearer implpk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "appointment_reminder",
    "category": "UTILITY",
    "language": "en_US",
    "body_text": "Hi {{1}}, see you at {{2}}.",
    "example_body_params": ["Sam", "3 pm"]
  }'
```

`name`, `category` and `language` are required. Send either `components` as Meta defines them, or `body_text` with the
optional `header_text`, `footer_text` and `example_body_params`. The answer is 201:

```json theme={null}
{ "ok": true, "status": 200, "response": { "id": "400000000000001", "status": "PENDING", "category": "UTILITY" } }
```

Meta reviews the template. The result comes later as the event `template.status_changed`. See
[WhatsApp events](https://docs.impellabs.tech/partners/channels/whatsapp/events.md). A refusal by Meta answers `{ "ok": false, "error": ... }` with the
reason.

## Change or delete a template

`PATCH /api/v1/partner/tenants/{external_ref}/templates/{name}/` sends new `components`, and optionally `category`, to Meta
for review. Send `language` when the template exists in more than one language. Without it the call answers 400.

`DELETE` removes the template in every language.

## Media in a header

A template can have an image, video or document header. Meta needs a sample file for the review. Upload it first, as
multipart form data with `file` and `header_type`.

```bash theme={null}
curl -X POST https://api.impellabs.tech/api/v1/partner/tenants/acme-001/templates/media/ \
  -H "Authorization: Bearer implpk_..." \
  -F header_type=IMAGE -F file=@sample.png
```

| `header_type` | File type | Size limit |
| - | - | - |
| `IMAGE` | JPEG or PNG | 5 MB |
| `VIDEO` | MP4 | 16 MB |
| `DOCUMENT` | PDF | 100 MB |

The answer is 201 `{ "handle", "mime", "size" }`. Use the `handle` in the header component of the template.

## Send a template

Send a template with the message routes in [Conversations](https://docs.impellabs.tech/partners/conversations.md): set `type` to `template`, and send
`template_name`, `lang` and `body_params`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.