> For the complete documentation index, see [llms.txt](https://docs.dapta.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dapta.ai/ai-text-agents/channels/message-templates.md).
# WhatsApp message templates
Create, submit, import and send WhatsApp templates, and get them approved for the line you actually send from.
Use **Text Agents → Templates** to manage the messages your business sends first. Connect a [WhatsApp line](/ai-text-agents/channels/connect-your-agent-with-whatsapp.md) in the same workspace before you start, and make sure you have permission to edit and send.
New to templates? Start with the types, then come back here to build one.
{% content-ref url="/pages/mLlFi104TPasFu4fCFKM" %}
[Which template type do you need](/ai-text-agents/channels/template-types.md)
{% endcontent-ref %}
## Approval belongs to the sending account
One template in Dapta can be **registered** with more than one sending account — a Meta WhatsApp Business Account, or the account behind a legacy line. Approval is granted per registration, not to the template as a whole — so a template approved for one account is not automatically approved for another.
Three things have to line up before a send works: the **line** you send from, the **account** it belongs to, and an **approved registration** of the template for that account. A template you can see in the library is not necessarily usable on the line selected in Inbox or in a Sequence.
## Create and submit a template
Meta reviews every template before you can use it. Most rejections come from formatting details you can avoid on the first submission. Go to **Text Agents → Templates** and click **New**.
The editor shows the form beside a live WhatsApp preview, in three sections: **Settings**, **Composer** and **WhatsApp lines**.
The form beside a live WhatsApp preview.
**Step 1: Give it a name.**
In **Settings**, write the **Template name** in your own words, the way you want to find it later, for example `Order confirmation`. Dapta formats it for WhatsApp automatically and shows the result under **Saved as**. The name is internal: your customers never see it. It can't be changed after you create the template.
***
**Step 2: Choose the language.**
Pick the language the message is written in, and create one template per language. If the text is in Spanish and you choose English, Meta rejects it.
***
**Step 3: Choose the template type.**
**Standard** sends one message, with an optional title, footer note and buttons. **Carousel** sends 2 to 10 cards the customer swipes through, each with its own image or video. A carousel must use the **Marketing** category.
***
**Step 4: Choose the right category.**
**Marketing**, **Utility** or **Authentication**, based on what the message does, not on what it costs. A promotion labelled Utility is rejected, or Meta moves it to Marketing. If in doubt, see [Which template type do you need](/ai-text-agents/channels/template-types.md).
***
**Step 5: Add a title, if you need one.**
In **Composer**, under **Add to your template**, click **Title**. It is shown at the top in bold and can be a text, an image, a video or a document. A text title has up to 60 characters and at most one custom field, with no bold or italic.
For an image, a video or a document, choose the **Attachment source**:
* **Upload file**: an image (jpg, jpeg or png, up to 5 MB), a video (mp4, up to 16 MB) or a document (pdf, up to 16 MB). The file is also saved in **Template Files** so you can reuse it.
* **Use public URL**: paste a public `https://` link to the file. WhatsApp downloads the file from that address when the template is submitted, so it must stay reachable without a login. Links that start with `http://`, and addresses without a real domain such as `localhost` or a private network address, are rejected.
Switching between the two options cancels an upload that is still in progress. The file you choose is the template's default: when you send the template, you can replace it with another file from the same host.
***
**Step 6: Write the text.**
Under **Text**, write the main message, up to 1,024 characters. Select words to make them bold or italic. To personalise it, type `/` and insert a custom field, such as the contact's first name. Each custom field is replaced with the contact's data when the message is sent. Click a field to edit it.
For a **Carousel**, build each card under **Carousel cards** with **Add card**: its image or video (uploaded or from a public URL), its text and its buttons. Every card uses the same kind of media and the same buttons. The full rules are in [Which template type do you need](/ai-text-agents/channels/template-types.md).
***
**Step 7: Give every custom field a sample.**
Click **Custom fields** at the top of **Composer** and write a realistic **Sample** for each field, such as `Maria` for the first name or `Acme` for the company. WhatsApp uses the samples to review your template, and the preview shows them. Never use a real customer's data. **Import from agent** brings in the fields an agent already uses, so your sequences fill them with the same data.
***
**Step 8: Add a footer note and buttons, if you need them.**
Under **Add to your template**:
* **Footer note**: a short line of plain text, up to 60 characters, with no custom fields. For example, `Reply STOP to unsubscribe`.
* **Buttons**: up to 3, each a **Reply** (quick reply), a **Link** to your website or a **Phone** number to call, with up to 25 characters of text. A template can have at most 2 link buttons and 1 phone button. Move buttons up or down to set their order, and keep quick replies together, before or after the link and call buttons.
***
**Step 9: Check the preview.**
The WhatsApp preview beside the form shows the message the way your customer will see it, with the samples in place of the custom fields. Read it as they would: it should make sense, the fields should fit the sentence, and nothing should be left blank.
***
**Step 10: Choose the line and submit for approval.**
In **WhatsApp lines**, choose the lines to submit the template with. WhatsApp approves it for each line's account separately, and only approved lines can send it. If your workspace has a single line, it is selected automatically.
Click **Submit for approval**. If anything is still missing, the button stays locked and **Before you submit** lists what is left; click the button to jump to the missing fields. Not finished yet? **Save draft**, the save button beside it, keeps your work.
Read each line's result separately: if some succeed and others fail, keep the ones that worked and fix the rest individually.
### Get it approved the first time
| Do this | Avoid this |
| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Put text before the first variable and after the last one. | Starting or ending the message with a variable, like `{{contact_name}}, hi`. |
| Put text between one variable and the next. | Two variables in a row, like `{{first_name}} {{last_name}}`. |
| Give every variable a name: `{{contact_name}}`. | An empty variable, like `{{}}`. |
| Few variables, plenty of fixed text. | A message that is mostly variables: Meta cannot tell what you will send. |
| A realistic example for every variable. | Empty examples, or a real customer's data. |
| A category that matches the content. | Labelling an offer as Utility to pay less. |
| A clear message about who is writing and why. | Vague or threatening messages, or asking for sensitive data such as passwords or card numbers. |
| Public links on your own domain. | Link shorteners, or files behind a login. |
{% hint style="info" %}
If Meta rejects it, read the reason on the template, fix it and submit again. Meta's review usually takes from a few minutes up to 24 hours.
{% endhint %}
## Import what you already have, and keep statuses fresh
* **Import** (Import from Meta), in the templates toolbar, brings templates from your connected Meta accounts into the workspace. The result distinguishes created, attached, updated and errors — read it rather than assuming everything came across. You can fix the errors and run it again.
* **Sync status** refreshes approval states. Check **Last synced**, and the rejection reason when there is one.
* **Add line**, in the template's **WhatsApp lines** section, registers an existing template with another eligible account. Use it when a template is approved somewhere but missing for the line you need.
Importing and syncing move information around. Neither one grants approval.
In the templates table, the **Status** column shows one chip per sending account: its status and the last six characters of the account's ID. Hover over or click the chips to open **Status by account**, with each account's name, status and rejection reason, and a **Copy ID** button. Use **Filters** to narrow the table by name, status, category, language, last use or creation date.
| Status | What to do |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Draft** | Finish it and submit. |
| **Pending** | Wait, then sync. Do not schedule anything on it yet. |
| **In appeal** | It can't be sent until the appeal is approved. Wait, then sync. |
| **Approved** | Confirm this registration matches the line you will actually send from. |
| **Rejected** | Read the reason, fix the content, submit again. If the template cannot be edited, use **Duplicate to Edit**. |
| **Paused** or **Disabled** | A restriction from WhatsApp. Fix the underlying problem — copying the template to send anyway makes it worse. Sequences that use a paused template pause automatically. |
| **Unknown** | WhatsApp no longer confirms this template, so it can't be sent. Sync again, or duplicate it and submit the copy for approval. |
**Duplicate to Edit** creates a separate template that needs its own approval. Sequences pointing at the original keep pointing at the original. **Duplicate**, in the templates table, does the same and asks you to name the copy.
## Send one by hand from Inbox
1. Open **Text Agents → Inbox → New conversation**.
2. Under **Send from**, choose the WhatsApp line, then type the recipient's number in international format.
3. Pick one of the templates offered for that line, fill its custom fields and, if you need to, replace the header file with another one from the same host.
4. Check the recipient, the preview and the sending line, then click **Send** once.
5. The conversation appears under **Awaiting first reply** until the person answers.
Inside an existing conversation, **Send template** does the same thing with that conversation's line. Which controls appear depends on the line and the state of the conversation.
## The 24-hour window
Every incoming customer message opens — or refreshes — a 24-hour window in which your agent can reply freely. Outside it, reaching someone takes an approved template, and sending that template does not reopen the window: only the customer's reply does.
This is WhatsApp's rule, and it is separate from your agent's [conversation timeout](/ai-text-agents/setting-up-your-text-agent/conversation-behavior.md) and from a [Sequence's schedule](/ai-text-agents/campaigns/message-logic-and-limits.md). Meta's own reference is its [customer service window](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing/non-template-messages) page.
What a message inside or outside that window costs depends on how your line is connected. See [WhatsApp billing: legacy and direct lines](/ai-text-agents/channels/whatsapp-billing-and-meta-charges.md).
## When a send fails
Template pickers only offer the templates the chosen line can send, including the ones saved in folders. Blank custom fields are caught before anything is sent, a sequence can't start with a template its line can't use, and send errors name the template or the custom field that failed.
| Problem | Check |
| -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **No templates are approved for this line yet.** | Workspace, which account the line belongs to, the template's language, its approval status and when it was last synced. |
| One registration works, another does not | The failing account's error. Do not delete the registration that works. |
| **This template is no longer available on this line. Choose another one.** | The template can no longer be sent from that line. Check its status for that line, then pick another template or fix the original. |
| Missing custom fields or media | Fill every requested value and match the header format. |
| Status refresh fails | Treat the last known status as unconfirmed, check your access and retry. |
| The send fails, or you cannot tell | Open the conversation history before retrying, so you do not send it twice. For support, note the line, the template, the time and the exact error. |
*Source review: October 13, 2026. Approval and account access determine what is available.*
{% content-ref url="/pages/Yd8Dr1GnzSTVXV8kBdd6" %}
[Inbox](/ai-text-agents/inbox.md)
{% endcontent-ref %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.dapta.ai/ai-text-agents/channels/message-templates.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
