Template Definition

A template definition is the JSON document that describes a template's content. It is the required definition field of the Create Template (POST /v3/templates) and Update Template (PUT /v3/templates/{id}) requests. The dashboard template builder displays the same JSON via its View JSON action.

Create template request

There is no name field on create: the display name is derived from the template's content. To rename a template afterwards, send name on Update Template (PUT /v3/templates/{id}).

Request headers

Beyond the x-api-key header that authenticates every call, the template endpoints accept two optional headers:

GET and DELETE ignore Idempotency-Key, which is why it is not offered on them. A profile-scoped request echoes the profile back in the X-Profile-Id response header, and the template's owner is reported as customer_id on the template itself.

Definition object

Channel support

MMS is the one channel that renders no header, footer, or buttons at all: it is a carrier message carrying a subject, text, and attachments, with nowhere to put them.

Header object

Text headers must not contain newlines, emojis, or formatting markup (*, _, ~). AUTHENTICATION templates do not use headers; Sent excludes any header from them automatically.

Body object

The body carries the message copy. Pick one of two authoring strategies:

• a shared multiChannel body on its own, or
• an explicit sms + whatsapp pair, with both present.

rcs and mms are optional on top of either strategy.

Body content object

MMS body content object

The mms body is the body content object plus the two members only MMS has: a subject line and attachments.

An mms body must carry body text, at least one media item, or both. One that carries neither renders to nothing and is rejected at authoring time with "MMS body must carry body text, at least one media item, or both." A template saved with more than one media item before the one-attachment limit still sends, carrying only its first.

MMS media item

Media URLs are never templated. A variable is substituted in template and subject but copied verbatim in url, so an attachment cannot be assembled from caller input.

A per-send media_urls on POST /v3/messages replaces this list rather than adding to it, which lets a template hold a default creative while a caller sends something recipient-specific. See Sending MMS for the sending side.

Footer object

Footers must not contain variables, newlines, emojis, or formatting markup (*, _, ~).

Buttons array

A template holds a maximum of 10 buttons. Button IDs must be unique. Per-type limits: maximum 1 COPY_CODE, 1 PHONE_NUMBER, 2 URL, and 10 QUICK_REPLY buttons.

Button props object

Variable object

Variables use a numbered placeholder syntax in template text: {{0:variable}} for text variables and {{4:link}} for links, where the number is the variable's id and the word after the colon is its type. This is the canonical form, and the one the dashboard builder writes.

Two shorter forms are also accepted in header and body text, and resolve to the same variable:

Variable props object

Authentication configuration

AUTHENTICATION templates accept an authenticationConfig object:

An AUTHENTICATION body must declare exactly one text variable (the code) and must not contain links or emojis.

Content rules and limits

Length limits are validated at save time against the stored text, with {{...}} placeholders unsubstituted. Counting is encoding-blind: each UTF-16 code unit counts as one character (the behavior of .NET's string.Length and JavaScript's String.prototype.length), so characters in the Basic Multilingual Plane count as 1 and most emoji count as 2. There is no post-substitution validation; a body within the limit can render into a longer message once variables expand. For how rendered length maps to SMS segments, see SMS Encoding & Message Length.

Meta requires every variable to carry surrounding context, so body text must additionally satisfy all of these rules. A body that fails any of them is refused at save time:

• At least one letter before the first variable and after the last. Trailing punctuation does not count: ... {{1:variable}}. fails the rule.
• At least (2 × variable count) + 1 words once the placeholders are removed.
• No two variables adjacent with only whitespace between them.
• The text cannot begin or end with a newline, run more than two line breaks together, or run more than four spaces together.

For example, Hello {{0:variable}}! Welcome to {{1:variable}}. We are glad to have you on board. passes: it has two variables, so at least five words are required, and the copy after the final variable contains letters.

AUTHENTICATION bodies are exempt from these rules and are held to Meta's authentication format instead.

Template statuses

Review routing depends on your account:

• With a connected WhatsApp Business Account, Meta reviews the template. A Meta APPROVED or PENDING verdict applies to every channel (SMS, WhatsApp, and RCS); a REJECTED verdict applies to the WhatsApp channel only.
• Without a connected WhatsApp Business Account, Sent's compliance team reviews the template, and each channel is approved or rejected individually.

Approval is tracked per channel. A message sends on a channel only when the template is approved for that channel; sends against unapproved templates return status BLOCKED. Status changes are delivered as templates webhook events carrying the template ID, status, reason, and the channel leg the decision applies to. Each channel is reviewed independently and reports separately, so expect one event per leg. channel is omitted when the decision applies to the template as a whole rather than to one leg; that event is the broader news, because a template-wide rejection blocks every channel whatever the individual legs say.

What a status allows you to change

Update Template (PUT /v3/templates/{id}) treats name differently from the rest of the template. The display name is editable in every status. The content fields and resubmission are gated:

A template is also treated as in review, and so frozen, when its own status is not PENDING but any of its channels is still awaiting a verdict. The 409 carries the message "This template is in review; its definition, category and language are frozen until the review completes".

From PAUSED, DISABLED, or REVOKED, an edit to definition, category, or language is refused with a 400 whose details.request reads "Template (except display name) cannot be updated unless it is in draft or rejected status". To change the content of a paused or taken-down template, create a new one.

Editing an approved template

An approved template can be edited in place; this is a live edit. The new content is stored immediately, and sending submit_for_review: true re-opens review, which returns the affected channels to PENDING. Those channels stop sending until they are approved again, and the previously approved content is not sent in the meantime. Plan for a gap, or keep a second approved template to send from while the edit is in review.

How much of the template goes back to PENDING depends on how your account is reviewed, so watch the per-channel templates webhook events rather than reading the template-level status alone.

Sent-provisioned templates are read-only

Templates that Sent provisions into your account (the pre-built OTP and verification templates that come with light onboarding) are read-only. They accept only submit_for_review; any other field is refused with 400 VALIDATION_001 and the detail "This template is read-only. Only 'submit for review' is allowed." To send different content, create your own template.

Relatedly, the sent_ prefix is reserved for these templates, so a name beginning with sent_ is refused on a template of your own. Pick any other name.

Example

A complete POST /v3/templates request body with a header, a multi-channel body using text variables and a dynamic link, a footer, and two buttons:

{
  "category": "UTILITY",
  "language": "en_US",
  "submit_for_review": false,
  "definition": {
    "header": {
      "type": "text",
      "template": "Order {{0:variable}}: Delivery Update",
      "variables": [
        {
          "id": 0,
          "name": "orderNumber",
          "type": "variable",
          "props": {
            "variableType": "text",
            "sample": "12345"
          }
        }
      ]
    },
    "body": {
      "multiChannel": {
        "type": "text",
        "template": "Hi {{0:variable}},\nYour Acme order {{1:variable}} has been shipped and is expected to arrive {{2:variable}} between {{3:variable}}.\nYou can track your package or update your delivery preferences at {{4:link}} before the driver arrives.",
        "variables": [
          {
            "id": 0,
            "name": "customerName",
            "type": "variable",
            "props": {
              "variableType": "text",
              "sample": "Lucas"
            }
          },
          {
            "id": 1,
            "name": "orderNumber",
            "type": "variable",
            "props": {
              "variableType": "text",
              "sample": "#12345"
            }
          },
          {
            "id": 2,
            "name": "arrivalDate",
            "type": "variable",
            "props": {
              "variableType": "text",
              "sample": "tomorrow (Oct 11)"
            }
          },
          {
            "id": 3,
            "name": "arrivalTime",
            "type": "variable",
            "props": {
              "variableType": "text",
              "sample": "2 PM – 4 PM"
            }
          },
          {
            "id": 4,
            "name": "orderLink",
            "type": "link",
            "props": {
              "url": "https://example.com",
              "shortUrl": "",
              "alt": "Tracking Page"
            }
          }
        ]
      }
    },
    "footer": {
      "type": "text",
      "template": "Thank you for shopping with Acme.",
      "variables": []
    },
    "buttons": [
      {
        "id": 1,
        "type": "URL",
        "props": {
          "text": "Track your order",
          "urlType": "static",
          "url": "https://www.example.com/track"
        }
      },
      {
        "id": 2,
        "type": "PHONE_NUMBER",
        "props": {
          "text": "Acme customer support",
          "countryCode": "US",
          "phoneNumber": "+112345678"
        }
      }
    ]
  }
}

The endpoint responds with the standard response envelope; the created template's fields are documented on the Create Template endpoint page.