# Message templates

> Create, preview and submit project message templates, then list, update and delete them.

A project template is a reusable message with variables. Create it once,
preview it and send it from any Number in the project. Meta Cloud API Numbers
also need Meta's approval before they send it; other Numbers need no review.

Project templates are addressed by project slug. Reading and previewing need
`templates:read`; creating, updating, deleting and submitting need
`templates:manage`. The Platform API also lists and edits a project's template
drafts by `projectId` at `/platform/templates`; see
[List message templates](https://docs.polymorfa.com/api/templates/list-message-templates).

The Graph API manages a WhatsApp Business Account's templates at Meta instead
of project templates: create, list and delete under `/{wabaId}/message_templates`,
with Meta's request shapes. Creating one submits it to Meta for review, so the
Graph API has no separate preview or submit step.

To let your own users manage templates in your app, see the
[template components](https://docs.polymorfa.com/ui-kit/templates).

## Create a template

**API:**

Call [Create project template](https://docs.polymorfa.com/api/templates/create-project-template)
with a `name` and a `definition`:

```bash cURL
curl -X POST "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/templates" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order_ready",
    "definition": {
      "version": 1,
      "kind": "standard",
      "category": "UTILITY",
      "language": "en_US",
      "body": "Hello {{name}}, your order is ready.",
      "variables": [{ "name": "name", "type": "text", "example": "Ada" }]
    }
  }'
```

```typescript TypeScript
const created = await messaging.templates.create("<project-slug>", {
  name: "order_ready",
  definition: {
    version: 1,
    kind: "standard",
    category: "UTILITY",
    language: "en_US",
    body: "Hello {{name}}, your order is ready.",
    variables: [{ name: "name", type: "text", example: "Ada" }],
  },
});

const templateId = created.data.data.id;
```

```bash Graph API
curl -X POST "https://api.polymorfa.com/graph/whatsapp/v26.0/$WABA_ID/message_templates" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-order-ready-1" \
  -d '{
    "name": "order_ready",
    "language": "en_US",
    "category": "UTILITY",
    "components": [
      { "type": "BODY", "text": "Hello {{1}}, your order is ready.", "example": { "body_text": [["Ada"]] } }
    ]
  }'
```

**Graph API:** Meta Cloud API Numbers: Supported. Linked Devices Numbers: Not supported.

[Create message template](https://docs.polymorfa.com/api/graph/templates/create-message-template)
needs `messages:write` and a Meta Cloud API Number under the WhatsApp Business
Account. An account with only Linked Devices Numbers returns capability error
`131026`. It takes an optional `Idempotency-Key`; see
[Idempotent requests](https://docs.polymorfa.com/api/idempotent-requests#messaging-writes). After an
uncertain result, list the templates before you submit another create.

*TypeScript:*

The `TemplateDefinition` type lists every field a definition accepts.

## Preview a template

**API:**

[Preview project template](https://docs.polymorfa.com/api/templates/preview-project-template)
renders the template with the `values` you send:

```bash cURL
curl -X POST "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/templates/$TEMPLATE_ID/preview" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "values": { "name": "Grace" } }'
```

```typescript TypeScript
const preview = await messaging.templates.preview("<project-slug>", templateId, {
  values: { name: "Grace" },
});
console.log(preview.data.data);
```

Polymorfa renders the preview. It does not ask Meta to validate the template.

## Submit a template for approval

**API:**

[Submit project template for approval](https://docs.polymorfa.com/api/templates/submit-project-template-for-approval)
takes the Number to submit through:

```bash cURL
curl -X POST "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/templates/$TEMPLATE_ID/submit" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "session": "'"$SESSION_ID"'" }'
```

```typescript TypeScript
await messaging.templates.submit("<project-slug>", templateId, {
  session: "<number-id>",
});
```

The same call accepts every Number, so one integration handles both
connection types. Check `submission` in the response:

| Number | Result |
| --- | --- |
| Any other Number, such as Linked Devices | `submission.status` is `APPROVED` and `submission.autoApproved` is `true`. Nothing is sent to Meta. |
| Meta Cloud API | `submission.status` is `PENDING`: Meta received the submission and has not decided yet. Meta's decision arrives in the `template.status` event. |

Polymorfa validates the saved definition for both connection types. An
incomplete or invalid definition returns `400`, and passing local validation
does not guarantee Meta's approval. If the request times out, read the
template before you submit it again.

## List, update and delete templates

**API:**

Use [List project templates](https://docs.polymorfa.com/api/templates/list-project-templates),
[Update project template](https://docs.polymorfa.com/api/templates/update-project-template)
(`PATCH`, with any of `name`, `status`, `definition` and `sampleValues`) and
[Delete project template](https://docs.polymorfa.com/api/templates/delete-project-template).

```bash cURL
curl "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/templates" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

```typescript TypeScript
const templates = await messaging.templates.list("<project-slug>");
for (const template of templates.data.data) console.log(template.name, template.status);

await messaging.templates.update("<project-slug>", templateId, {
  sampleValues: { name: "Ada" },
});

await messaging.templates.delete("<project-slug>", templateId);
```

```bash Graph API
curl "https://api.polymorfa.com/graph/whatsapp/v26.0/$WABA_ID/message_templates" \
  -H "Authorization: Bearer $POLYMORFA_KEY"

curl -X DELETE "https://api.polymorfa.com/graph/whatsapp/v26.0/$WABA_ID/message_templates?name=order_ready" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Idempotency-Key: delete-order-ready-1"
```

**Graph API:** Meta Cloud API Numbers: Partly supported. Linked Devices Numbers: Not supported.

[List message templates](https://docs.polymorfa.com/api/graph/templates/list-message-templates)
returns the account's templates with Meta's `status`, `quality_score` and
`rejected_reason`; an account with no templates returns an empty list.
[Delete message template](https://docs.polymorfa.com/api/graph/templates/delete-message-template)
deletes a template by `name` and takes an optional `Idempotency-Key`. Updating
a template is not offered through the Graph API. An account with only Linked
Devices Numbers returns capability error `131026`, not an empty list or a
successful deletion.

## Send a template

Send an approved template with `content.template`, giving its `name`,
`language` and `components`. See [Send messages](https://docs.polymorfa.com/messaging/send#templates).

## See also

- [Send messages](https://docs.polymorfa.com/messaging/send#templates)
- [Template components](https://docs.polymorfa.com/ui-kit/templates)
- [Send a campaign](https://docs.polymorfa.com/campaigns/send)
- [Project templates API reference](https://docs.polymorfa.com/api/templates/list-project-templates)
