Skip to content
Shortcut: /, ⌘K or Ctrl+K

Message templates

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

View as Markdown

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.

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.

Create a template#

API

Call Create project template with a name and a definition:

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
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;
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"]] } }
    ]
  }'

TypeScript:

The TemplateDefinition type lists every field a definition accepts.

Preview a template#

API

Preview project template renders the template with the values you send:

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
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 takes the Number to submit through:

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
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:

NumberResult
Any other Number, such as Linked Devicessubmission.status is APPROVED and submission.autoApproved is true. Nothing is sent to Meta.
Meta Cloud APIsubmission.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, Update project template (PATCH, with any of name, status, definition and sampleValues) and Delete project template.

cURL
curl "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/templates" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
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);
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"

Send a template#

Send an approved template with content.template, giving its name, language and components. See Send messages.

See also#