Templates API — Create, Update, Delete

Templates define reusable message content. Create and manage them in the dashboard (/templates) or via the public REST API (/v1/templates) and the MCP server (templates_create / templates_update / templates_delete). When sending, reference the template by templateId and pass a variables object with matching keys.

Send this template via the API modal with a ready-made curl command — Every template has a ready-made API call — the editor's Send via API modal generates the exact curl with the templateId.

All requests use the x-api-key: ps_... header (or x-api-key-id). Base URL: https://pilotstatus.com.br/v1.

Template structure

Only body is required.

Component	Required	What it is
Header	optional	Text or one media item (image, video, PDF).
Body	required	Main text with `{{variable}}` placeholders.
Footer	optional	Short static line under the body.
Buttons	optional	Up to 10 interactive buttons.

Type	Value	Notes
`NONE`	—	Default.
`TEXT`	`text`	Up to 60 chars, 0 or 1 variable. No line breaks/emojis/formatting.
`IMAGE`	`url` or `base64`	JPG/PNG.
`VIDEO`	`url` or `base64`	MP4.
`DOCUMENT`	`url` or `base64`	PDF.

REST API: pass either header.url (public http(s) URL) or header.base64 (data URI) — base64 is re-hosted server-side automatically.
MCP: header.url only — base64 is not supported over MCP.

There is no LOCATION header.

Body

Up to 1024 characters.
Variables written as {{nome}} (named style).
The body must not start or end with a variable.
Emojis and multiple variables allowed.

Static text up to 60 characters. No variables.

Buttons

Up to 10 buttons total; quick-reply and CTA buttons can be mixed.

Type	Fields	Limit
`QUICK_REPLY`	`text`	up to 10
`URL`	`text`, `url` (static or dynamic)	up to 2
`PHONE_NUMBER`	`text`, `phone_number` (E.164)	up to 1
`COPY_CODE`	`example` (code to copy — only a sample on official numbers)	up to 1
`PAYMENT_REQUEST`	`text`, `paymentType`, `example` (PIX code)	up to 1

Dynamic URL button: URL ends with a variable (e.g. https://loja.com/promo/{{link}}) — one variable max, never in the domain. Sample value goes in examples. On send, it is filled by its name (variables.link). A template created in Meta’s console with a numbered placeholder (https://ctlnk.io/{{1}}) is filled by button_<N> instead — see Button placeholders in templates created in Meta.
Copy-code: value goes on the button as example (array, e.g. ["PROMO10"]), alphanumeric only, up to 15 chars. Not for PIX keys or e-mails — for PIX, use the PAYMENT_REQUEST button below. On an official number this example is only a sample: the code the customer copies goes in variables as button_<N> on every send — see Copy-code buttons on official numbers.

PIX payment button (`PAYMENT_REQUEST`)

WhatsApp Pay Brazil payment button: the customer taps it and copies the PIX code. This is the right way to ship PIX copy-and-paste — COPY_CODE caps at 15 alphanumeric characters, while a real BR Code runs 100-400 characters with punctuation. The code is a per-send value: put a variable in the button’s example and pass the real code in variables at send time, like any other variable.

{ "type": "PAYMENT_REQUEST", "text": "Copy Pix code",
  "paymentType": "pix_dynamic_code", "example": ["{{codigo_pix}}"] }

This button requires Meta to have enabled payments on your WhatsApp Business Account. Enablement is gradual and per-account — Meta’s own wording is “this feature is rolling out and might not be available yet for your WhatsApp Business account”. On an account without it, Meta refuses the template with 100 / subcode 2388128 (“Button at index 0 has unexpected type (PAYMENT_REQUEST)”). There is no API field to check this — the only way to know is to try creating one.

The PIX code variable is required at send time. If it is missing the send is refused rather than delivered: without the parameter Meta would fall back to the sample code stored on the template, and the customer would pay the wrong account.

ORDER_DETAILS (the itemized order card) can be built, previewed and saved — see Itemized order card.

Buttons are allowed together with a video or document (PDF) header.

Variables & examples (required)

When creating/updating via REST or MCP you must include an examples object mapping every variable used (body + header text + dynamic URL) to a real sample value. The copy-code value is the only exception (it lives on the button).

400 { "code": "TEMPLATE_EXAMPLES_REQUIRED", "details": { "missing": ["desconto"] } }

After saving, GET /v1/templates/{id} returns all detected keys in the top-level variables array (a string[]) — supply all of them in variables on send. There is no latestVersion object in the public API response.

Button placeholders in templates created in Meta

A template created in Meta’s WhatsApp Manager and synced into Pilot Status (source: "META") with positional placeholders numbers a dynamic URL button’s variable on its own: in https://ctlnk.io/{{1}}, that {{1}} is not the body’s {{1}}. Send its value as variables["button_<N>"], where N is the button’s position in the template’s button list, starting at 1 — every button counts, static ones included. Pass only the variable part (the URL suffix), not the full URL:

"variables": { "1": "Maria", "2": "R$ 10,00", "3": "21/09/2026", "button_1": "Gggkf" }

GET /v1/templates and GET /v1/templates/{id} list the key in variables — ["1", "2", "3", "button_1"] for the template above.
A send without it, or with an empty value, is refused with 400 MISSING_TEMPLATE_VARIABLES (or INVALID_TEMPLATE_VARIABLE_VALUE) naming the key, instead of being accepted and failing later with Meta 131008.
Named placeholders are unchanged: a button created in Pilot Status as https://loja.com/promo/{{link}} is filled by variables.link.
The same button_<N> key carries the code of a copy-code button on an official number — see below.

Copy-code buttons on official numbers

For Meta, the code typed on a COPY_CODE button at creation is only an example; the code the customer copies is a required parameter of every send. So on a template approved by Meta (source: "META" — every template on an official number, created in Meta’s console or in Pilot Status), a copy-code button whose value has no {{variable}} (a fixed example such as PROMO10) takes its code as variables["button_<N>"], with the same rule: N is the button’s position in the template’s button list, starting at 1, every button counts. For buttons [QUICK_REPLY, COPY_CODE] with the example PROMO10:

"variables": { "button_2": "BLACKFRIDAY" }

GET /v1/templates and GET /v1/templates/{id} list the key in variables — button_4 for the promo_cupom template in Create via REST API.
A send without it, or with an empty value, is refused with 400 MISSING_TEMPLATE_VARIABLES (or INVALID_TEMPLATE_VARIABLE_VALUE) naming the key. The example keeps its creation limit (15 alphanumeric characters); for the code sent, Meta’s limit is 20 characters.
A copy-code button whose example is a named variable (["{{cupom}}"]) is still filled by variables.cupom. An authentication (OTP) template’s code button still takes the body’s code.
Unofficial (web/QR) numbers: the copy code is generated per send there too — write it on the button as a {{variable}} (e.g. ["{{cupom}}"]) and fill it in variables.

Character limits

Component	Limit	Rules
Header (text)	60	No line breaks/emojis/formatting; at most 1 variable.
Body	1024	Can’t start or end with a variable.
Footer	60	No variables.
Button label	25	—
Copy-code value	15	Alphanumeric only.
PIX code (`PAYMENT_REQUEST`)	2000	Punctuation allowed; a real BR Code runs 100-400.

Create via REST API

curl -X POST https://pilotstatus.com.br/v1/templates \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_token_here" \
  -d '{
  "name": "promo_cupom",
  "category": "MARKETING",
  "language": "pt_BR",
  "body": {
    "header": { "type": "IMAGE", "url": "https://cdn.exemplo.com/banner.png" },
    "body":   { "text": "Oi {{nome}}! Use e ganhe {{desconto}} de desconto." },
    "footer": { "text": "Promoção por tempo limitado" },
    "buttons": [
      { "type": "QUICK_REPLY",  "text": "Quero!" },
      { "type": "URL",          "text": "Comprar", "url": "https://loja.com/promo/{{link}}" },
      { "type": "PHONE_NUMBER", "text": "Falar",   "phone_number": "+5511999998888" },
      { "type": "COPY_CODE",    "example": ["PROMO10"] }
    ]
  },
  "examples": { "nome": "Maria", "desconto": "10%", "link": "abc123" }
}'

{ "id": "tmpl_123", "name": "promo_cupom", "category": "MARKETING", "metaStatus": "PENDING" }

body may be an object (recommended), a JSON string, or plain text (body-only templates).
Edit with PUT /v1/templates/{id} (same shape); remove with DELETE /v1/templates/{id} — for a Meta template this also asks Meta to delete it, and the response depends on Meta’s answer (see Delete).
GET /v1/templates / GET /v1/templates/{id} return source (META | PILOT_STATUS), metaStatus (APPROVED | PENDING | REJECTED | DISABLED | null), metaLanguage, and sendable — on a Meta number only META templates with metaStatus: "APPROVED" are sendable.

Delete

DELETE /v1/templates/{id} no longer always returns success. For a Meta template the deletion is forwarded to Meta, and the outcome depends on what Meta does:

Outcome	HTTP	Body	Local row
Removed on both sides	`200`	`{ "deleted": true, "id": "tmpl_123" }`	removed
Meta refused the deletion	`409`	bilingual message naming the template and the reason	kept
Template genuinely absent on Meta (real 404)	`200`	`{ "deleted": true, "id": "tmpl_123" }`	removed

A 200 { "deleted": true, "id" } is the only response that means the template is really gone — removed on Meta and locally.
A 409 means nothing was removed: Meta rejected the deletion (e.g. the system token lacks permission on the WABA), so the template still exists on Meta and its name stays reserved. The local row is kept, and the message names the template and the reason. Fix the underlying permission and retry.
If Meta reports the template does not exist (a genuine 404 / “template does not exist”), the stale local row is removed and you still get 200 { "deleted": true, "id" }.

Carousel templates

A carousel template is an approved template whose body carries a carousel block: a horizontally-scrollable strip of 2–10 media cards, each with its own image, body line and buttons. Carousel templates are Meta-only and always category MARKETING — on a Meta number the create is submitted to Meta as a CAROUSEL component. Unlike the session carousel (interactive, quick-reply only — a URL button there returns 400), a template carousel card may mix QUICK_REPLY and URL buttons in the same card.

The `carousel` block

It sits inside body next to body.text — the message shown above the cards (the carousel body).

Field	What it is
`cardTemplate`	The shared skeleton every card must match: one `hasBody` decision and one `buttons` list (types + order).
`cardTemplate.hasBody`	`true`/`false` — whether every card carries a body line. Body is all-or-nothing across cards.
`cardTemplate.buttons`	The button types and order every card repeats, e.g. `[{ "type": "QUICK_REPLY" }, { "type": "URL" }]`.
`cards`	2–10 cards. Each card only fills its own `media`, `body` text and button values (`text`, `payload`, `url`).

Caps (validated at create and update)

The same caps and media rules apply to POST (create) and PUT (update) — validation is no longer skipped.

Rule	Limit
Cards	2–10
Buttons per card	≤ 2
Card body	≤ 160 chars
Message body (`body.text`, above the cards)	≤ 1024 chars
Button label (`text`)	≤ 20 chars
Button payload / id	≤ 256 chars
Body	all-or-nothing — every card has a body, or none does
Buttons	every card repeats the exact types and order from `cardTemplate.buttons`

Card media — each card.media.url must be a public https URL ending in .png, .jpg, .jpeg or .webp, with no query string. Meta accepts an unreachable image with 200 and then delivers nothing, so the URL is fetched and refused before submission with a typed error naming the offending card.

A top-level header is not allowed with carousel (media lives on each card), and card buttons replace top-level buttons.

Create a carousel template

curl -X POST https://pilotstatus.com.br/v1/templates \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_your_token_here" \
  -d '{
  "name": "lancamentos_carrossel",
  "category": "MARKETING",
  "language": "pt_BR",
  "body": {
    "body": { "text": "Confira nossos lançamentos da semana!" },
    "carousel": {
      "cardTemplate": {
        "hasBody": true,
        "buttons": [{ "type": "QUICK_REPLY" }, { "type": "URL" }]
      },
      "cards": [
        {
          "media": { "format": "IMAGE", "url": "https://cdn.exemplo.com/tenis.png" },
          "body": "Runner sneakers — $59",
          "buttons": [
            { "type": "QUICK_REPLY", "text": "I want it", "payload": "SKU-1" },
            { "type": "URL",         "text": "See product", "url": "https://loja.com/p/tenis" }
          ]
        },
        {
          "media": { "format": "IMAGE", "url": "https://cdn.exemplo.com/jaqueta.png" },
          "body": "Wind jacket — $89",
          "buttons": [
            { "type": "QUICK_REPLY", "text": "I want it", "payload": "SKU-2" },
            { "type": "URL",         "text": "See product", "url": "https://loja.com/p/jaqueta" }
          ]
        }
      ]
    }
  }
}'

{ "id": "tmpl_car_1", "name": "lancamentos_carrossel", "category": "MARKETING", "metaStatus": "PENDING" }

Every card here repeats the QUICK_REPLY + URL pair declared in cardTemplate.buttons, in that order. A card that omits a button, reorders them, or changes a type is rejected before dispatch.

Approval

Meta numbers: templates are submitted to Meta for review (“Submit to Meta” in /templates, or on save). Categories, language and status follow Meta’s rules.
Unofficial (Pilot Status web) numbers: templates are created locally and immediately usable — no approval step.

Not supported

LOCATION (header or button), CATALOG/MPM, LIMITED_TIME_OFFER, OTP autofill/one-tap/zero-tap, and VOICE_CALL buttons. (Session carousel — the non-template kind — is covered in the Send message reference.) FLOW buttons are supported on Meta numbers — see Sending a Flow. ORDER_DETAILS (the itemized order card) can be built, previewed and saved — see Itemized order card for the behavior per number type. The NAMED parameter_format is supported: a template authored in Meta’s console with named variables ({{customer_name}}) imports with the right variables and sends with parameter_name on each parameter.

Submit & rejection errors

Link/URL buttons accept a single variable that must be at the end of the URL and never in the domain; call buttons need the country code (e.g. +55).

Checked before submitting to Meta

Cause	Fix	Meta code
Body starts/ends with a variable	Add literal text at the edges	`2388299`
Button combination over limits	≤10 total, ≤10 quick-reply, ≤2 URL, ≤1 call, ≤1 copy-code	`100`
Call button without country code	Use E.164 (`+55 21 99999-8888`)	`192`
Link button on placeholder domain (example.com…)	Use your real business URL	`368/1346003`
Variable in the URL domain	Variable only at the end of the path	`100`
More than one URL variable / not at end	One variable, at the end	`100`
Copy-code with symbols/spaces or >15 chars	Alphanumeric ≤15	`100`
Footer contains a variable	Remove it	`2388073`
Text header with emoji/line break/formatting/2+ variables	Plain text, ≤1 variable	`2388047`
Field over character limit	Header 60, body 1024, footer 60, button 25	`2388040`

API-side validation

Cause	Fix	Meta code
Too many variables vs fixed text	Add wording or reduce variables	`2388293`

Meta rejected the submission

Cause	Fix	Meta code
Media header but number missing Meta App ID	Set App ID in number settings	—
Invalid parameter (Meta reason shown)	Review indicated field	`100`
Content flagged abusive (usually button URL domain)	Review button links	`368/1346003`
Display name not approved yet	Wait for Meta approval	`131037`
Required parameter missing (e.g. an unfilled button variable)	Supply every template variable — for a numbered button placeholder in a template created in Meta’s console, as `button_<N>`	`131008`
Payment button not enabled for this WABA	Wait for Meta to enable payments	`100/subcode 2388128`
URL button invalid link/variable	Check link and `{{…}}`	`100`
Media upload to Meta failed	Header file reachable + valid format	—
Header file too large / unsupported	Image ≤5MB JPEG/PNG, video ≤16MB MP4, PDF ≤10MB	`131002/131003`
Number temporarily blocked (policy)	Resolve with Meta	`368`
Token missing WhatsApp permissions	Reconnect number granting permissions	`10/200/3`
Token invalid/expired	Update System Token	`190`
WABA inaccessible/removed	Reconnect the number on Meta	`100/subcode 33`

Rejected after review

Reason	Meta code
Threatening/abusive/policy-violating content	`ABUSIVE_CONTENT`
Category doesn’t match content	`INCORRECT_CATEGORY`
Formatting: bad/adjacent variables, missing examples	`INVALID_FORMAT`
Utility template with promotional content	—
Looks like a scam (generic, fake urgency)	`SCAM`
Selected language ≠ written text	—

Blocks when sending (even approved)

Cause	Meta code
Business verification not completed	`141010`
No payment method / outstanding invoice on WABA	`131042 / 141006`
Template permanently disabled after repeated pauses	`132016`
Template not approved yet	— (Pilot Status refuses it before calling Meta: `META_TEMPLATE_NOT_APPROVED`)
Variable count ≠ approved template	`132000`
Template paused for quality drop	`132015`

Common error when sending

404 — template without an approved version (doesn’t exist for the key, or Meta template has no approved version yet).

Overview

Messaging

Templates

Numbers

Phone Lines

Conversations & Data

Webhooks

Voice Calls

API Layer

Account & Billing

Branding & Embedding

Templates API — Create, Update, Delete

Category

Template structure

Header

Body

Footer

Buttons

PIX payment button (`PAYMENT_REQUEST`)

Variables & examples (required)

Button placeholders in templates created in Meta

Copy-code buttons on official numbers

Character limits

Create via REST API

Delete

Carousel templates

The `carousel` block

Caps (validated at create and update)

Create a carousel template

Approval

Not supported

Submit & rejection errors

Checked before submitting to Meta

API-side validation

Meta rejected the submission

Rejected after review

Blocks when sending (even approved)

Common error when sending

​Category

​Template structure

​Header

​Body

​Footer

​Buttons

​PIX payment button (PAYMENT_REQUEST)

​Variables & examples (required)

​Button placeholders in templates created in Meta

​Copy-code buttons on official numbers

​Character limits

​Create via REST API

​Delete

​Carousel templates

​The carousel block

​Caps (validated at create and update)

​Create a carousel template

​Approval

​Not supported

​Submit & rejection errors

​Checked before submitting to Meta

​API-side validation

​Meta rejected the submission

​Rejected after review

​Blocks when sending (even approved)

​Common error when sending

Category

Template structure

Header

Body

Footer

Buttons

PIX payment button (`PAYMENT_REQUEST`)

Variables & examples (required)

Button placeholders in templates created in Meta

Copy-code buttons on official numbers

Character limits

Create via REST API

Delete

Carousel templates

The `carousel` block

Caps (validated at create and update)

Create a carousel template

Approval

Not supported

Submit & rejection errors

Checked before submitting to Meta

API-side validation

Meta rejected the submission

Rejected after review

Blocks when sending (even approved)

Common error when sending