Create and manage WhatsApp message templates in Paige

Message templates are pre-approved message formats that let your bot reach users proactively — outside of an active conversation window or as outbound notifications. Every template must be approved by Meta before it can be sent. Once approved, you call sendTemplate() in your bot code to deliver it to any number in your contact list.

New to templates? Understanding templates explains why WhatsApp makes you get them approved, and when to reach for one instead of a normal reply. This page is the hands-on how-to.

Template categories

When you create a template, you assign it to one of three categories. The category affects approval speed and how WhatsApp bills the message.

UTILITY

Transactional messages tied to a user action or request — order confirmations, appointment reminders, shipping updates, payment receipts. Approved in minutes in most cases.

MARKETING

Promotional messages, product announcements, offers, and campaigns. Approval typically takes longer than UTILITY. Subject to per-message marketing pricing.

AUTHENTICATION

One-time passcodes and verification messages. Used for 2FA and account verification flows. Tightly scoped and approved quickly.

If your message is tied to something the user initiated — a booking, an order, a sign-up — use UTILITY. UTILITY templates are approved in minutes and cost less to send.

Template components

A template is made up of components. The only required component is a BODY. You can optionally add a HEADER (text or media), a FOOTER, and BUTTONS.

BODY (required)

The main text of the message. Supports variables using {{1}}, {{2}} notation. Variable values are provided at send time.

{
  "type": "BODY",
  "text": "Hi {{1}}, your appointment on {{2}} has been confirmed."
}

HEADER (optional)

Displayed above the body. Can be plain text or a media type (image, video, document).

{
  "type": "HEADER",
  "format": "TEXT",
  "text": "Appointment Confirmed"
}

A picture, video or document header needs a sample file at the moment you create it — see Media headers need a sample file.

FOOTER (optional)

A short line of grey text displayed below the body. Does not support variables.

{
  "type": "FOOTER",
  "text": "Reply STOP to unsubscribe."
}

BUTTONS (optional)

Up to three buttons. Supported types are QUICK_REPLY (sends a reply back to your webhook), URL (opens a link), and PHONE_NUMBER (initiates a call).

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "URL",
      "text": "Track order",
      "url": "https://example.com/track/{{1}}"
    }
  ]
}

Placeholder rules

Two rules trip people up, both of them Meta’s:

Number them in order from `{{1}}`

Placeholders must run {{1}}, {{2}}, {{3}} with no gaps. A body using only {{2}}, or jumping from {{1}} to {{3}}, is rejected — you’ll see Body variables must be sequential starting at {{1}} (no gaps). A header or a URL button can hold one placeholder, and it must be {{1}}.

Give each one an example

Meta’s reviewers read your template as a message, not a form — so they need to see what real content looks like in it. When you build a template in the dashboard, a Variable examples card appears once your numbering is valid, with a box per placeholder. Fill in every one. The dialog won’t submit until you do. For a body reading Hi {{1}}, your order {{2}} has shipped, sensible examples are Jane and A-4471.

For a URL button, the example is just the bit that replaces the placeholder — not the whole address. For https://example.com/track/{{1}}, the example is A-4471, not https://example.com/track/A-4471. Meta rejects the full-URL version.

Creating a template

Three ways, depending on where you are.

Via the dashboard
Via the Code Agent
Via the Broadcasting assistant

Open Settings → Templates and click Create Template. Fill in the name, category, language, and body, add a header, footer, or buttons if you want them, and fill in an example for each placeholder.A live preview on the left shows the message as your customer will see it. Click Create Template to submit it to Meta.

The live preview is hidden on phones, so you’d be composing blind. Templates are worth doing at a desk.

Tell the Code Agent what template you need, and it creates and submits it.

“Create a UTILITY template called order_shipped in English. The body should say ‘Hi , your order has shipped and will arrive by .’”

Give the agent your example values in the same message — “use Jane, A-4471 and Friday as the examples”. If you don’t, it fills in generic placeholders like example1, and Meta’s reviewer sees those instead of anything meaningful. Approval is a human reading your message; realistic examples help.

Template names must be lowercase letters, numbers, and underscores only, and must start with a letter. For example: order_confirmation, appt_reminder_v2.

Templates live under Settings → Templates. They didn’t move to the Tools tab with the database and the rest — a template belongs to your WhatsApp number rather than your bot’s runtime.

Media headers need a sample file

Choose Add Header and then a picture, video or document, and the builder asks you to attach a sample file. This isn’t optional: Meta won’t review a template with a media header unless it can see an example of the kind of file it will carry. Pick something representative — one of your real product photos, a sample invoice PDF — and Paige uploads it as soon as you choose it. The filename appears under the picker once it’s done. The sample is only ever shown to Meta’s reviewers. Each message you send later carries its own file, not this one.

Header type	Formats	Size limit
Picture	JPEG, PNG	5 MB
Video	MP4, 3GP	16 MB
Document	PDF, Word, Excel, PowerPoint, plain text	100 MB

If the file is too big, the wrong type, or isn’t really the kind of file its name suggests, Paige tells you straight away rather than letting Meta reject the whole template. Very occasionally — when a lot of people are uploading at once — Paige asks you to try again in a few seconds. Just pick the file again.

You can create these templates, but you can’t send them yet. Paige has no way to pick the file that goes with each message — not from the Conversations template picker, not from the chat assistant, and not in the Broadcasts wizard. In the Broadcasts wizard they’re listed but greyed out, with a note that they need a picture, video or document at send time. A media-header template you just created hasn’t gone missing; it simply can’t be broadcast yet. Use a text-only template for a broadcast in the meantime.

Template approval

After you submit a template, Meta reviews it. Approval times vary by category:

UTILITY — typically approved within minutes
AUTHENTICATION — typically approved within minutes
MARKETING — can take hours to a few days

Your template appears straight away with a yellow PENDING badge, turning green when Meta approves it. You’ll be told the moment that happens. A toast appears wherever you are in the project, and the badge in Settings → Templates updates itself — no reloading and no checking back. If Meta rejects the template instead, the toast says so and gives you the reason, with a View action that takes you straight to the template.

This is worth knowing if you’re planning a broadcast around a new template: you can submit it and carry on working, rather than watching the page. Approval times still vary by category, so leave room for a MARKETING template to take a day or two.

Templates that are rejected can be edited and resubmitted, but the name cannot be changed. If your template was rejected, review Meta’s messaging policies, adjust the content, and resubmit.

Listing your templates

To see the current status of all templates for your project, ask the AI agent:

“List my templates.”

Or view them directly in the Templates section of your project dashboard.

Sending a template by hand

You don’t need code to send a template to one person. Open the Conversations tab, pick the contact, open the chevron at the bottom-left of the reply box and click Send template. Fill in any placeholders and send — this is how you reach someone whose 24-hour window has closed. Paige also keeps a standard conversation starter template for exactly that job. See The conversation starter.

Sending a template in bot code

Once a template is approved, use sendTemplate() in your bot code to send it.

const { sendTemplate } = require("../services/messages");

// Send a template with no variables
await sendTemplate(to, "welcome_message", "en");

// Send a template with body variables
await sendTemplate(to, "appointment_reminder", "en", [
  {
    type: "body",
    parameters: [
      { type: "text", text: contactName },
      { type: "text", text: appointmentDate },
    ],
  },
]);

// Send a template with a header variable and a URL button variable
await sendTemplate(to, "order_shipped", "en", [
  {
    type: "header",
    parameters: [{ type: "text", text: "Order Update" }],
  },
  {
    type: "body",
    parameters: [
      { type: "text", text: contactName },
      { type: "text", text: orderNumber },
      { type: "text", text: deliveryDate },
    ],
  },
  {
    type: "button",
    sub_type: "url",
    index: "0",
    parameters: [{ type: "text", text: orderNumber }],
  },
]);

Parameters:

to — recipient phone number (e.g. "27821234567")
templateName — the exact name of the approved template
languageCode — language code used when the template was created (e.g. "en", "en_US", "pt_BR")
components — array of component objects providing variable values at send time

Variable indices in the components array at send time must match the {{1}}, {{2}} placeholders in the template definition, in order.

Deleting a template

To delete a template, navigate to the Templates section in your project dashboard and click the delete action next to the template. Deleting a template removes it from your WhatsApp Business Account on Meta. This action cannot be undone.

AI agents

Flows

Flow templates

Broadcasts

Conversations

Preview

Tools

Settings

Create and manage WhatsApp message templates in Paige

Template categories

UTILITY

MARKETING

AUTHENTICATION

Template components

Placeholder rules

Number them in order from `{{1}}`

Give each one an example

Creating a template

Media headers need a sample file

Template approval

Listing your templates

Sending a template by hand

Sending a template in bot code

Deleting a template

​Template categories

UTILITY

MARKETING

AUTHENTICATION

​Template components

​Placeholder rules

​Number them in order from {{1}}

​Give each one an example

​Creating a template

​Media headers need a sample file

​Template approval

​Listing your templates

​Sending a template by hand

​Sending a template in bot code

​Deleting a template

Template categories

Template components

Placeholder rules

Number them in order from `{{1}}`

Give each one an example

Creating a template

Media headers need a sample file

Template approval

Listing your templates

Sending a template by hand

Sending a template in bot code

Deleting a template