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

# Templates

> Meta's three template categories, authentication templates for one-time codes, Meta's template library, quality and pausing, the counts Meta keeps per template, and reading templates from your code.

Every message your code sends is an approved template. Create templates on the application's **Notifications → Templates** page with **New template** (with the writing assistant, from Meta's library, or from scratch), or in WhatsApp Manager. They all land in the same list, and Meta reviews each one. A template's header is text, an image or a document (a PDF, such as an invoice, a contract or an attendance sheet: see [Send a PDF attachment](https://docs.tawked.com/whatsapp/pdf-attachments.md)); an image or a document is reviewed with a sample, and each message carries its own file when it is sent. Tawked's store apps submit the templates their notifications use for you.

## Placeholder names

A placeholder's name is at most 20 characters, written in lowercase letters, digits and underscores and starting with a letter: `{{customer_name}}`, `{{start_date}}`. Meta approves a template with a longer name, such as `{{subscription_start_date}}` (23 characters), but then refuses every message sent from it, so Tawked refuses the name when the template is written. A template that already has one answers `422 unsupported_template` with `message` `long_placeholder_name` when you send it, and nothing is sent or charged: rename the placeholder in an edit or a new template.

The limit is on the placeholder's name only. A template's own name can be longer, and a placeholder's value can be up to 1024 characters.

## Categories

Meta sorts every template into one of three categories and prices its messages by category. Meta decides: a template it reads as another category is moved to that category, and the list shows the change.

| Category | For | Meta's rules |
| - | - | - |
| Utility | A message about something the customer did or asked for: an order, a booking, a payment. | No promotion. A utility template that reads as marketing is moved to Marketing. |
| Marketing | Offers, announcements, invitations to come back. | Only to customers who opted in. Give them a way to stop: an opt-out line in the footer or a "Stop" quick reply. |
| Authentication | One-time codes. | Meta writes the text. You choose the security sentence, the expiry and the button. |

A message that cannot be delivered right away is retried until its time-to-live runs out: 30 seconds to 15 minutes for authentication (10 minutes by default), 30 seconds to 12 hours for utility, 12 hours to 30 days for marketing.

## Authentication templates

A code sent from your own WhatsApp number. The text is Meta's, fixed in each language, never yours. In English:

* `*{{1}}* is your verification code.` The code goes in `{{1}}`, in bold.
* `For your security, do not share this code.` On or off.
* `Expires in 10 minutes.` 1 to 90 minutes, in the footer.

In Arabic, Meta writes «`*{{1}}*` هو كود التحقق الخاص بك. للحفاظ على أمانك، لا تشارك هذا الكود مع أي شخص.» and «تنتهي صلاحيتها خلال ١٠ دقائق.».

One button carries the code:

| Button | What the customer does | You provide |
| - | - | - |
| Copy code | Taps to copy the code, then pastes it into your app or site. | Nothing. |
| One-tap autofill | Taps once; WhatsApp hands the code to your Android app. | The app's package name and its 11-character signature hash. |
| Zero-tap | Nothing; your Android app receives the code in the background. | The same, and Meta's zero-tap terms accepted. |

Create one in the console with the **Authentication** category, then send it with one value, `code`: see [Authentication templates](https://docs.tawked.com/whatsapp/messages.md#authentication-templates). Only Meta receives the code; the console's log and Tawked Chat show `••••••` in its place. The message is priced like any other WhatsApp message; Meta bills authentication messages at its own authentication rate. Codes by SMS stay with [Tawked Verify](https://docs.tawked.com/quickstart.md).

## Meta's template library

Ready-made utility and authentication templates written by Meta, in **Notifications → Templates**, **Meta's library**. Filter by topic (account updates, customer feedback, order management, payments), use case, industry and language (Arabic or English), or search. **Use this template** asks for a name, the language, and one input per button: the link, with an example when it ends in `{{1}}`, or the phone number.

A library template's text is fixed. Meta usually approves it the moment it is created, and it is sent like any other template. Meta checks the values at send time against the kind of each placeholder (a date, an amount, an email address): a value that does not fit fails the send.

## Quality and pausing

Meta rates each template from how customers react to it, mostly blocks and reports in the last 7 days: **High**, **Medium**, **Low**, or not rated yet. A template whose quality falls is paused: 3 hours the first time, 6 hours the second, disabled the third. A paused template can be resumed from the list once its pause ends.

## Counts per template

The list shows what Meta counted for each approved template over the last 30 days: sent, delivered, read and clicks; the template's page shows them day by day. Meta counts every message sent with the template, from any tool on the number, WhatsApp Manager and Tawked Chat included. The counts appear once Meta's template insights are on for the WhatsApp Business Account, which Tawked asks Meta for when the number is connected.

## Reading templates from your code

Templates are written in the console; your code reads them. A key with Notifications set to read only or to send (`notifications:read`) makes both calls:

| Call | Does |
| - | - |
| [`GET /v1/whatsapp/templates`](https://docs.tawked.com/api-reference/whatsapp/list-templates) | Lists every template with its `id`, status and the placeholders a send must fill |
| [`GET /v1/whatsapp/templates/{template_id}`](https://docs.tawked.com/api-reference/whatsapp/get-a-template) | Reads one template in full |

`template_id` is Meta's id of one language of a template, the `id` of its row in the list. A template in two languages is two rows with two ids.

```bash theme={"dark"}
curl https://tawked.com/v1/whatsapp/templates/7000 \
  -H "Authorization: Bearer $TAWKED_KEY"
```

```json theme={"dark"}
{
  "id": "7000",
  "name": "order_received_v1",
  "language": "ar",
  "category": "UTILITY",
  "status": "APPROVED",
  "quality": "GREEN",
  "rejected_reason": null,
  "components": [
    { "type": "HEADER", "format": "TEXT", "text": "طلبك {{1}}", "buttons": [] },
    { "type": "BODY", "format": null, "text": "استلمنا طلبك رقم {{1}} بقيمة {{2}} ريال.", "buttons": [] },
    { "type": "BUTTONS", "format": null, "text": null, "buttons": [
      { "type": "URL", "text": "تتبع الطلب", "url": "https://flowers.example/orders/{{1}}", "phone_number": null }
    ] }
  ],
  "examples": { "header:1": "1042", "body:1": "1042", "body:2": "250", "button:0": "1042" },
  "placeholders": { "kind": "positional", "header": ["1"], "body": ["1", "2"], "buttons": [{ "index": 0, "type": "url" }] },
  "managed": false
}
```

`components` is the template as Meta holds it, and `placeholders` is what a [send](https://docs.tawked.com/whatsapp/messages.md) must fill. `rejected_reason` is Meta's reason when the status is `REJECTED`, so your code can tell why a template is not sendable. `managed` is false for a key you create. An id that is not on the number's WhatsApp Business Account answers `404 not_found`.

Creating, editing and deleting a template are not open to a key you create, full access included: `POST`, `PATCH` and `DELETE` under `/v1/whatsapp/templates` answer `403 insufficient_scope`. Write templates on **Notifications → Templates**.


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