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

# Message templates

> Create, preview, and submit project message templates with MessagingClient.

A project template is a reusable message with variables. Create it once, preview
it, and send it from any Number. Cloud API Numbers also need Meta's approval
before they send it. Templates are addressed by project slug.

| Task | Permission |
| - | - |
| List, read, and preview templates | `templates:read` |
| Create, update, delete, and submit templates | `templates:manage` |

## Create a template

```typescript theme={null}
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;
```

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

## Preview a template

```typescript theme={null}
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

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

The same submit call accepts every Number. Linked-device Numbers return
`submission.status` `APPROVED` and `submission.autoApproved` `true` without
Meta review. Cloud API Numbers return `submission.status` `PENDING`: Meta
received the submission and has not yet approved it. Polymorfa validates the
saved definition for both connection types. Meta reports the Cloud API decision
in the `template.status` webhook. If the request times out, read the template
before you submit it again.

## List, update, and delete templates

```typescript theme={null}
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);
```

To send an approved template, see
[Send a template](/sdks/typescript/messages#send-a-template).


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