> ## Documentation Index
> Fetch the complete documentation index at: https://developer.omni.z-api.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Introduction
> Understand how message templates work in Omni Z-API
export const projectName = 'Omni Z-API';
**All three Meta channels have pre-approved templates**: WhatsApp Official, Instagram and Messenger. What changes is the scope, the endpoint and the category.
Today the endpoints in this section cover **WhatsApp Official only** (WABA scope). Instagram and Messenger support is **being implemented**.
## Three things are called "template"
Meta uses the same word for three different features. Mixing them up is the most common source of integration errors:
| | 1. WhatsApp template | 2. Utility Template | 3. Structured message |
| ------------- | ---------------------------------------- | ------------------------------ | ----------------------------------------------- |
| Channels | WhatsApp Official | **Messenger** | Instagram, Messenger, WhatsApp |
| Scope | **WABA** | **Facebook page** | none — it is inline |
| Meta endpoint | `/{waba-id}/message_templates` | `/{page-id}/message_templates` | `/{page-id}/messages` |
| Approval | **required** | **required** (within seconds) | **none** |
| Categories | `UTILITY`, `MARKETING`, `AUTHENTICATION` | **`UTILITY` only** | — |
| Statuses | 3 | **10** | — |
| In Omni Z-API | this section | *being implemented* | [buttons](/en/messages/send-interactive-button) |
### 1 and 2 — pre-approved templates
They serve the same purpose: talking to the customer **outside the conversation window**. Both require prior registration and Meta approval.
The practical difference is scope. A WhatsApp template belongs to a **WABA**; a Utility Template belongs to a **Facebook page**.
**Instagram is not part of this.** The Graph API `message_templates` edge exists only on the `Page` node. No Instagram node exposes it — neither `IGUser` (Facebook login) nor `IGUserForIGOnlyAPI` (Instagram login, which is the Omni Z-API flow).
On Instagram you have the 24-hour window, extended to 7 days with the *human agent tag*. Details in [Connect Instagram](/en/connect/instagram).
The Utility Template has a much richer lifecycle than the WhatsApp one — **10 statuses** against 3:
`PENDING` · `APPROVED` · `REJECTED` · `IN_APPEAL` · `PAUSED` · `DISABLED` · `LIMIT_EXCEEDED` · `ARCHIVED` · `PENDING_DELETION` · `DELETED`
It also accepts `parameter_format` (`NAMED` or `POSITIONAL`) and lets you clone from Meta's pre-approved library via `library_template_name`.
On Messenger, Utility Templates **replaced Message Tags**. The tags `CONFIRMED_EVENT_UPDATE`, `ACCOUNT_UPDATE` and `POST_PURCHASE_UPDATE` were discontinued on **April 27, 2026** and now return error `100`. If your integration still uses tags, it is already broken.
For marketing outside the window on Instagram and Messenger there is also the **Marketing Messages API**, which is opt-in based: you ask the customer for permission to send recurring promotional messages.
### 3 — structured message (no approval)
This is what Meta also calls the *generic template* and *button template*. It is **not** a pre-approved template: it is a payload format sent inline, to put buttons and cards on a message you are already allowed to send.
In Omni Z-API these are the interactive endpoints, available on all five channels with no registration:
Quick reply buttons — Meta's *button template*.
URL and call buttons — Meta's *generic template*.
See the [capability matrix](/en/channels/overview) for what each channel accepts.
## What are WhatsApp templates?
In the official WhatsApp API, you can only send messages freely while the **24-hour conversation window** is open (i.e., when the customer has recently sent you a message).
Outside this window, the only way to start a conversation is through **templates** — pre-defined messages that must be approved by Meta before they can be sent.
## Categories
Each template needs a category that defines the type of communication. Choosing the wrong category can get your template rejected by Meta.
| Category | When to use | Example |
| ------------------ | ------------------------------------------- | ----------------------------------------------------- |
| **UTILITY** | Transactional and operational communication | Order confirmation, delivery status, account update |
| **MARKETING** | Promotional communication | Campaign, offer, coupon, product launch |
| **AUTHENTICATION** | Security and identity validation | OTP code, login confirmation, two-factor verification |
## Template structure
Every template is composed of **components**. Each component has a role:
| Component | Required | What it does |
| ----------- | -------- | --------------------------------------------------------------- |
| **HEADER** | No | Initial context — can be text, image, video, or document |
| **BODY** | Yes | Main message content |
| **FOOTER** | No | Short complementary text (e.g., "Do not reply to this message") |
| **BUTTONS** | No | User actions (open URL, call, quick reply) |
### Placeholders
You can use dynamic variables in text with `{{1}}`, `{{2}}`, etc. When creating the template, you must send real examples for each placeholder — Meta uses these examples during review.
## Template flow
The API organizes templates by **business** (WABA — WhatsApp Business Account). Each business has its own templates, approval history, and limits.
Use the list WABAs endpoint to get the correct `businessId` for your token.
Choose the category, build the components with placeholders and examples, and submit for approval.
Meta reviews the template and returns a status: `PENDING`, `APPROVED`, or `REJECTED`.
With an approved template, you can use it to start conversations with customers outside the 24h window.
## Template status
| Status | Meaning |
| ---------- | -------------------------------------------------------------- |
| `PENDING` | Submitted for review, awaiting Meta approval |
| `APPROVED` | Approved and ready to use |
| `REJECTED` | Rejected — review the content and category before resubmitting |