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

# WhatsApp Template Tools

> Reference for the templates:manage tools — list, create, update, delete, and sync WhatsApp message templates through Meta.

The `templates:manage` scope unlocks five tools for working with WhatsApp message templates. Sapot Chat proxies these to the Meta WhatsApp Cloud API, so the tools speak Meta's component schema and inherit Meta's approval workflow.

<Warning>
  Creating, updating, and deleting templates requires a **WhatsApp Cloud API inbox** and an **admin-level** agent token. Other WhatsApp providers (360dialog / Twilio) can still `sync` and `list` templates, but not run CRUD through these tools.
</Warning>

## Before you start

* **Inbox**: every tool takes an `inbox_id`. For CRUD it must be a WhatsApp Cloud API inbox.
* **Categories**: Meta requires one of `MARKETING`, `UTILITY`, or `AUTHENTICATION`.
* **Approval is out of band**: new and edited templates come back `PENDING`. Meta approves (or rejects) asynchronously — you cannot force approval through the API. Re-list later to see the updated `status`.
* **`template_id` is Meta's id**, not the template name. Read it as the `id` field on a template object returned by `list_whatsapp_templates`. Deletes, however, are **by name** (see below).

## list\_whatsapp\_templates

List an inbox's WhatsApp templates, fetched live from Meta. Optional filters narrow the set Meta-side.

| Argument   | Type   | Required | Description                                                        |
| ---------- | ------ | -------- | ------------------------------------------------------------------ |
| `inbox_id` | int    | yes      | A WhatsApp Cloud API inbox id.                                     |
| `name`     | string | no       | Filter by template name.                                           |
| `status`   | string | no       | Filter by status, e.g. `APPROVED`, `PENDING`, `REJECTED`.          |
| `category` | string | no       | Filter by category, e.g. `MARKETING`, `UTILITY`, `AUTHENTICATION`. |

**Returns** `{templates: [...Meta template objects...], paging: {...}}`.

## create\_whatsapp\_template

Submit a new template to Meta for approval.

| Argument                | Type            | Required | Description                                                       |
| ----------------------- | --------------- | -------- | ----------------------------------------------------------------- |
| `inbox_id`              | int             | yes      | A WhatsApp Cloud API inbox id.                                    |
| `name`                  | string          | yes      | Template name — lowercase snake\_case; Meta's naming rules apply. |
| `category`              | string          | yes      | `MARKETING`, `UTILITY`, or `AUTHENTICATION`.                      |
| `components`            | list of objects | yes      | Meta component objects (body, header, footer, buttons).           |
| `language`              | string          | no       | Meta language code (default `en`).                                |
| `allow_category_change` | bool            | no       | Let Meta reclassify the category during review.                   |

**Returns** `{template: {id, name, status, category}}`. `status` is usually `PENDING`.

<Info>
  `components` follow Meta's component schema. A minimal body-only example:

  ```json theme={null}
  [{"type": "BODY", "text": "Hi {{1}}, your order {{2}} has shipped."}]
  ```

  Header, footer, and button components follow the same schema as the Meta API.
</Info>

## update\_whatsapp\_template

Edit an existing template's category and/or components. This re-submits the template to Meta.

| Argument      | Type            | Required | Description                                                               |
| ------------- | --------------- | -------- | ------------------------------------------------------------------------- |
| `inbox_id`    | int             | yes      | A WhatsApp Cloud API inbox id.                                            |
| `template_id` | string          | yes      | The Meta template id (the `id` from a template object, **not** its name). |
| `category`    | string          | no       | New category.                                                             |
| `components`  | list of objects | no       | New component objects.                                                    |

**Returns** Meta's edit response.

<Warning>
  Editing an **approved** template sends it back to `PENDING` — the previous version stops being usable until Meta re-approves the edit.
</Warning>

## delete\_whatsapp\_template

Delete a template from Meta by name.

| Argument        | Type   | Required | Description                                                                    |
| --------------- | ------ | -------- | ------------------------------------------------------------------------------ |
| `inbox_id`      | int    | yes      | A WhatsApp Cloud API inbox id.                                                 |
| `template_name` | string | yes      | The template's **name**. Meta deletes by name, removing **all** its languages. |

**Returns** `{}` on success.

<Note>
  Delete is the one tool keyed on the **name**, not the Meta id — and it removes every language variant registered under that name.
</Note>

## sync\_whatsapp\_templates

Pull the latest templates from Meta into the inbox's cached template list.

| Argument   | Type | Required | Description          |
| ---------- | ---- | -------- | -------------------- |
| `inbox_id` | int  | yes      | A WhatsApp inbox id. |

**Returns** `{message: "..."}`.

<Tip>
  The sync **runs asynchronously** in the background. Call `list_whatsapp_templates` a moment afterwards to see the refreshed set — the `sync` response itself only confirms the job was enqueued.
</Tip>

## Typical workflow

<Steps>
  <Step title="Draft and submit">
    Build the `components` per Meta's schema, then `create_whatsapp_template`. Expect `status: PENDING`.
  </Step>

  <Step title="Wait for Meta">
    Approval happens out of band. Poll with `list_whatsapp_templates(status="APPROVED")` — you cannot force it.
  </Step>

  <Step title="Refresh the cache">
    If templates were changed in Meta Business Manager directly, `sync_whatsapp_templates`, then re-list.
  </Step>
</Steps>

## Errors you may see

| Response                                                             | Meaning                                                              |
| -------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `Access token is missing the required scope: templates:manage`       | The key wasn't granted `templates:manage`. Mint or re-scope the key. |
| `403` on create/update/delete                                        | The inbox isn't WhatsApp Cloud API, or the token isn't admin-level.  |
| `Agent action quota exceeded for the current billing period` (`429`) | Your plan's metered agent-action allowance is exhausted.             |

Only allowed, successful (2xx) calls count against your plan's quota; denied or failed requests never consume it.

## Connect

```bash theme={null}
claude mcp add --transport http sapot https://mcp.sapot.ai/mcp --header "Authorization: Bearer YOUR_AGENT_KEY" --header "X-Sapot-Account-Id: YOUR_ACCOUNT_ID"
```

<CardGroup cols={2}>
  <Card title="Authentication & Scopes" icon="key" href="/ai-agents/authentication">
    How agent keys authenticate and the default-deny scope model.
  </Card>

  <Card title="The Agent Skill" icon="sparkles" href="/ai-agents/agent-skill">
    Install the companion skill so the agent drives these tools correctly.
  </Card>
</CardGroup>