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.
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 -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" }]
}
}'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;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 -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" } }'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 -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"'" }'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, Update project template (PATCH, with any of name, status, definition and sampleValues) and Delete project template.
curl "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/templates" \
-H "Authorization: Bearer $POLYMORFA_KEY"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);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.