# Create and Manage WhatsApp Templates

> Create, edit and delete a WhatsApp number's message templates with the Mojeeb Public API, from text and media headers to buttons and verification-code templates, and follow Meta's review until a template can be sent.

A template is a message Meta approves in advance, so you can send it to a customer at any time. With the Public API your systems can create a WhatsApp number's templates, edit them and delete them, as on the dashboard's WhatsApp page. Meta reviews every new template and every change before it can be sent.

## How do I create a template?

Find the number's connection `id` as for [listing templates](./list-templates), then `POST` the template:

```bash
curl -X POST https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID/connections/YOUR_CONNECTION_ID/whatsapp-templates \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "name":          "order_shipped",
    "language":      "en",
    "category":      "utility",
    "body":          "Hi {{1}}, your order {{2}} is on its way.",
    "body_examples": { "1": "Sara", "2": "A-100" },
    "footer":        "Acme Clinics",
    "buttons": [
      { "type": "url", "text": "Track order", "url": "https://example.com/track/{{1}}", "example": "A-100" }
    ]
  }'
```

The answer is `201` with the template, usually `status: pending`. Every field is in the [Create a template reference](../api-reference/create-whats-app-template).

## How do variables and samples work?

Write variables as `{{1}}`, `{{2}}` and so on, in order, or as lower-case names such as `{{first_name}}`, with one style across the header and the body. Meta reviews a template with sample values, so give one for each variable: `body_examples` maps each body variable to a sample, keyed the way a send's `parameters` are (`"1"` or `"first_name"`), and `header.example` is the sample for a text header's one variable.

## How do I add an image, video or document header?

Set `header.format` and give `header.media_url`, an https link to a sample file. Mojeeb downloads it once and hands it to Meta for the review. When you send the template, you can send a different file with `template.header_media_url`. The link must answer with the file itself, with the file's type as its `Content-Type`, from a public address; redirects aren't followed. The [reference](../api-reference/create-whats-app-template) lists the file types and the size Mojeeb accepts.

## Which buttons can a template have?

Quick replies, links (`url`, which may end with a `{{1}}` that a send fills in), one phone number and one copy-code button. Keep the quick replies together, before or after the other buttons. Location headers, carousels, limited-time offers, and catalog and Flow buttons are made in WhatsApp Manager, because Mojeeb can't send them yet.

## How do I create a verification-code template?

Set `category` to `authentication` and describe the code button in `otp`. `copy_code` lets the customer copy the code; `one_tap` and `zero_tap` hand it to your Android app, listed in `supported_apps`. Meta writes the message itself in the template's language, and you choose only whether it adds a security line and when the code expires:

```json
{
  "name": "login_code",
  "language": "en",
  "category": "authentication",
  "otp": { "type": "copy_code", "add_security_recommendation": true, "code_expiration_minutes": 10 }
}
```

To send it, give the code as the body's `"1"` and as the button's `otp_code`; see [Send a WhatsApp Template](./send-template).

## How do I know when Meta approves it?

Read the template with `GET` on its `id` ([Get a template](../api-reference/get-whats-app-template)) until `status` is no longer `pending`. `approved` can be sent; `rejected` says why in `rejected_reason`. Meta's review can take up to a day, so check every few minutes rather than every second: the template endpoints share a small rate limit, which [Rate Limits](../rate-limits) explains.

## How do I edit a template?

`PUT` its whole content to its `id`. Meta replaces every part on an edit, so send everything it should say, not only the change. The name and language never change; leave `category` out to keep it. A media header sent without `media_url` keeps its sample; one that changes format needs `media_url`. Meta lets you edit an approved template once a day and ten times a month, and reviews each edit; content that equals what Meta already holds isn't sent and uses no edit. An authentication template, `message_send_ttl_seconds` or a new `media_url` always counts as a change, because Meta's list doesn't show them to compare. See the [Edit a template reference](../api-reference/update-whats-app-template).

## How do I delete a template?

`DELETE` it by `id`. This removes that one language version; its other languages stay. Deleting an approved or paused template locks its name at Meta for 30 days, so add `?acknowledge_name_lock=true`; without it the API answers `409 template_delete_locks_name` with the date. A deleted template can't be restored. See the [Delete a template reference](../api-reference/delete-whats-app-template).

## Why was my template refused?

Nothing is sent to Meta until the template follows Meta's rules that Mojeeb can check:

- `422 invalid_request_body`: a part its category doesn't take, a variable without a sample, or buttons in the wrong order. `param` names the field, such as `buttons[1].url`.
- `422 template_header_media_url_invalid`: Mojeeb couldn't download the header's sample; the message says why.
- `422 template_rejected`: Meta refused the template, and the message is Meta's reason. An edit Meta wouldn't take, such as a new category for an approved template, is refused the same way before it reaches Meta.
- `409 template_name_taken`: the number already has a template with this name in this language.
- `409 template_status_not_allowed`, `template_edit_limit_reached` or `template_in_use_by_broadcast`: the template can't change right now.

[Errors](../errors) lists every code.

## Common questions

### Can I retry a create that timed out?

Yes. If the first one reached Meta, the retry answers `409 template_name_taken`, because the name now exists in that language. Read the list to find it. A create needs no `Idempotency-Key`.

### Do templates created through the API show in the dashboard?

Yes. Templates live at Meta, on the number's WhatsApp Business Account, so the dashboard's WhatsApp page and WhatsApp Manager show them all, however they were made.

### Which scopes do these calls need?

`whatsapp_templates:write` to create, edit and delete templates, and `whatsapp:read` to read them. Every key holds both today; see [Authentication](../authentication).

### Can an AI assistant create templates?

Yes. Through the [MCP server](../mcp) an assistant can create, read and edit templates, but never delete them.