Templates

Create

Template language is a string WhatsApp language code such as pt_BR or en_US. Do not send Meta's nested {"code":"pt_BR"} object shape.

Template button type accepts QUICK_REPLY, URL, PHONE_NUMBER, OTP, or standalone COPY_CODE. Standalone COPY_CODE is marketing-only, limited to one button, has no text, and requires a non-empty example of at most 20 characters. Authentication uses the separate nested shape type: "OTP" with otp_type: "COPY_CODE". FLOW, MPM, SPM, CATALOG, and VOICE_CALL remain unsupported.

Authentication uses Meta's fixed OTP authoring contract: exactly one {"type":"BODY"} with optional add_security_recommendation and no text, an optional FOOTER with code_expiration_minutes from 1 to 90, no HEADER, and exactly one OTP button. Free-form BODY.text is valid only for marketing and utility templates.

A direct send supplies type: "button", sub_type: "copy_code", the zero-based index, and exactly one {"type":"coupon_code","coupon_code":"WINTER25"} parameter. COPY_CODE batches are rejected with template_param_mismatch because the batch contract has no per-recipient button parameters. For Pix use interactive.order_details and pix_dynamic_code.

parameter_format is uppercase POSITIONAL or NAMED. Omit it on create for the compatible POSITIONAL default: positional tokens use {{1}}, {{2}}, and the existing positional example fields.NAMED accepts unique {{[a-z][a-z0-9_]*}} tokens in BODY, text HEADER, and dynamic URL buttons. BODY and text HEADER use exact named example arrays: one non-empty { param_name, example } entry for every token and no missing, duplicate, or extra name; URL buttons have no authoring example array.

The stable template_named_placeholder_unsupported error applies only when a default or explicit POSITIONAL BODY, text HEADER, or dynamic URL button uses a named token such as {{full_name}}. Its corrective message offers parameter_format: 'NAMED' with named examples where applicable, or sequential positional tokens. It remains category-independent and is judged before the variable-placement rule.

{
  "name": "order_tracking_update",
  "language": "pt_BR",
  "category": "utility",
  "parameter_format": "NAMED",
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Pedido {{order_id}}",
      "example": {
        "header_text_named_params": [
          { "param_name": "order_id", "example": "ORD-123" }
        ]
      }
    },
    {
      "type": "BODY",
      "text": "Olá {{customer_name}}, pedido {{order_id}}.",
      "example": {
        "body_text_named_params": [
          { "param_name": "customer_name", "example": "Ana" },
          { "param_name": "order_id", "example": "ORD-123" }
        ]
      }
    },
    {
      "type": "BUTTONS",
      "buttons": [
        { "type": "URL", "text": "Acompanhar", "url": "https://example.com/orders/{{order_id}}" }
      ]
    }
  ]
}

A marketing or utility BODY whose trimmed text starts or ends with a format-valid variable (positional {{n}} or named {{name}}) returns 400 template_variable_position_invalid, with error.param of the form components.0.text. Meta rejects that shape after review, so it is refused at authoring time instead. Only BODY components and only their outer edges are checked; the trim removes invisible characters as well as whitespace, so a zero-width space cannot mask an edge variable. Newly authored authentication templates carry no free-form BODY text: the fixed OTP component contract is validated before this rule. The pure checker exemption remains only for legacy stored authentication JSON.

Component text is capped at 4096 characters for BODY and 1024 for a text HEADER or FOOTER, counted in UTF-16 code units. Longer text returns 400 invalid_template_request — invalid_update_request on PATCH, invalid_duplicate_requeston a category- or format-overriding duplicate — with error.param of the form components.0.text, and an over-cap component reports only its length. The caps sit well above Meta's own limits (1024, 60, and 60), which still apply at review.

A BODY or text HEADER placeholder that is positional except for spaces or invisible characters inside the braces ({{ 1 }}) returns 400 invalid_template_request — or the PATCHand duplicate twins — with error.param of the form components.0.text; the message quotes the token and the {{n}} to write instead. Write every variable as {{1}} with nothing else inside the braces.

Request body

Response

Generate draft

Generation returns an editable, non-persisted draft. Omitted parameter_format defaults to POSITIONAL; a NAMED request returns the same format and must use the same named BODY/TEXT HEADER examples when later created.

Request body

Response

List

Every item returns uppercase parameter_format. This is live authoring state; an approved send resolves the submitted version's immutable format rather than accepting a format from the send request.

Query

Response

Retrieve

The returned parameter_format is POSITIONAL or NAMED. It can change only while the template is draft or rejected; a submitted version keeps the format it captured at submit.

Response

Update

Omit parameter_format to retain the live draft/rejected format, or set it toPOSITIONAL or NAMED with components that satisfy that format. Validation runs on the merged template — the stored draft with this patch applied — so error.param can name a component the request did not send. A category or format-only patch can therefore surface exact named-example, compatibility, or variable-placement errors from stored components. Submitted and approved versions are not rewritten by PATCH.

Request body

Response

Delete

Soft-deletes a local-only draft, rejected, or orphaned template and returns its updated public record. Templates still live on Meta (submitted, approved, paused, or disabled) return 409 and must be removed upstream first.

Response

Duplicate

Omit parameter_format to inherit the source format, or override it withPOSITIONAL or NAMED. A category or format override re-validates copied components, including exact named examples and the stable compatibility error for named tokens under POSITIONAL. Without either override, the copy inherits the source components and format as an editable draft. An approved source remains immutable; the duplicate is the new authoring surface.

Request body

Response

Submit for Meta approval

Submit snapshots the current components and parameter_format into an immutable version. Approved sends validate and serialize against that version even if a later editable live template changes.

Response

Analytics

Response

Estimate cost

Request body

Response