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

Definition object

Channel support

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 channel-specific content. multiChannel applies to every channel unless a channel-specific override is present.

Body content object

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.

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.

Body text must additionally satisfy these rules:

• Must not start or end with a newline, and must not contain more than two consecutive line breaks or more than four consecutive spaces.
• Must contain at least one letter before the first variable and after the last variable; variables cannot be adjacent without text between them.
• Word count must be at least (2 × variable count) + 1.

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, channel, status, and reason.

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": "body",
        "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.