Text templates

A text template can contain a header, body, footer and buttons.

Text templates are the most common WhatsApp template type. They consist of text-based headers, bodies, footers, and optional interactive buttons.

Block Structure

Block	Required	Max per template	Description
Text header	No	1	Text displayed at the top of the message (max 60 characters, no rich formatting)
Text body	Yes	1	Main message content (max 1024 characters)
Text footer	No	1	Text displayed below the body (max 60 characters, no rich formatting)
Buttons	No	10 total	Interactive action or quick reply buttons

Text templates can also use an image or file header instead of a text header. See Image Template Blocks and File & Video Template Blocks for those header types.

Here's how a text template with header, body, footer, and action buttons renders on WhatsApp:

The link preview card at the top is automatically generated by WhatsApp when the template includes a link button.

---

Header

Headers are optional elements displayed at the top of the message. For text templates, headers support only plain text with a maximum of 60 characters. Rich formatting and emojis are not supported in headers.

{
  "type": "text",
  "role": "header",
  "text": {
    "text": "My header"
  }
}

Body

The body is the only mandatory block. It supports up to 1024 characters and can include variables using the {{variable_key}} syntax.

{
  "type": "text",
  "role": "body",
  "text": {
    "text": "Hello {{firstName}}, your order #{{orderNumber}} has been shipped!"
  }
}

Body truncation (marketing templates)

For templates with the MARKETING category, WhatsApp truncates the body after approximately 5 lines and shows a "Read more" link. The user must tap it to see the full message. UTILITY templates are not truncated.

Keep this in mind when writing marketing body copy -- put the most important information in the first few lines to ensure it's visible without tapping.

Footer

Footers are optional and appear below the body. Maximum 60 characters, no rich formatting or emojis.

{
  "type": "text",
  "role": "footer",
  "text": {
    "text": "Reply STOP to unsubscribe"
  }
}

---

Buttons

Buttons are optional interactive elements appended after the footer. Templates support up to 10 buttons total, but there are restrictions on the number and combination of each type.

Action buttons

Action buttons trigger a specific action when tapped (opening a URL, calling a phone number, or copying a code).

Link button

Opens a URL in the user's default browser. Up to 2 link buttons per template. The button text has a maximum of 20 characters.

The URL can include a variable suffix for dynamic tracking:

{
  "type": "link-action",
  "linkAction": {
    "text": "View order",
    "url": "https://example.com/orders/{{orderId}}"
  }
}

Phone number button

Dials a phone number when tapped. 1 phone number button per template. Button text max 25 characters, phone number max 20 characters.

{
  "type": "call-phone-number-action",
  "callPhoneNumberAction": {
    "text": "Call support",
    "phoneNumber": "[phone]"
  }
}

Copy code button

Copies a code to the user's clipboard. 1 copy code button per template. When used, the body must also contain the same variable.

{
  "type": "copy-code-action",
  "copyCodeAction": {
    "code": "{{code}}"
  }
}

Quick reply buttons

Quick reply buttons send a predefined response back to you when tapped. Up to 10 quick reply buttons per template.

{
  "type": "reply-action",
  "replyAction": {
    "text": "Yes, confirm",
    "payload": "confirm_order"
  }
}

The payload is the value returned when the user taps the button.

---

Button Ordering Rules

When combining button types, they must follow this specific order:

1. copy-code-action

2. link-action

3. call-phone-number-action

4. reply-action

Quick reply buttons and non-quick-reply (action) buttons must be grouped separately. They cannot be interleaved.

Valid combinations:

• Quick Reply, Quick Reply

• Quick Reply, Quick Reply, Link, Phone

• Link, Phone, Quick Reply, Quick Reply

Invalid combinations:

• Quick Reply, Link, Quick Reply

• Link, Quick Reply, Link

Button limits

Button type	Maximum per template
copy-code-action	1
link-action	2
call-phone-number-action	1
reply-action	10

---

Button Rendering Behavior

WhatsApp displays buttons differently depending on the total count and types used.

3 or fewer buttons

When a template has 3 or fewer buttons, all buttons are shown directly below the message:

More than 3 buttons

When a template has more than 3 buttons, WhatsApp shows the first 2 buttons inline and collapses the rest behind a "See all options" link:

Tapping "See all options" opens a bottom sheet showing all buttons, with quick reply buttons grouped separately from action buttons:

Link preview

When a template includes a link-action button, WhatsApp automatically generates a link preview card at the top of the message bubble. This preview is fetched by WhatsApp from the button URL -- you do not control its content. See the hero image above for an example.

---

Variables

Variables use the {{key}} syntax and must be declared in the variables array at the template level. Each variable requires example values for Meta's review process.

"variables": [
  {
    "key": "firstName",
    "description": "The customer's first name",
    "type": "string",
    "format": "none",
    "examplesLocale": {
      "en": {
        "exampleValueStrings": ["John"]
      }
    }
  }
]

---

Complete Example

A full text template with header, body, footer, and buttons:

{
  "defaultLocale": "en",
  "deployments": [
    {
      "key": "whatsappTemplateName",
      "platform": "whatsapp",
      "value": "seasonal_promo"
    },
    {
      "key": "whatsappCategory",
      "platform": "whatsapp",
      "value": "MARKETING"
    },
    {
      "key": "whatsappAllowCategoryChange",
      "platform": "whatsapp",
      "value": "true"
    }
  ],
  "variables": [
    {
      "key": "customerName",
      "description": "Customer's first name",
      "type": "string",
      "format": "none",
      "examplesLocale": {
        "en": {
          "exampleValueStrings": ["Jane"]
        }
      }
    },
    {
      "key": "discountCode",
      "description": "Promotional discount code",
      "type": "string",
      "format": "none",
      "examplesLocale": {
        "en": {
          "exampleValueStrings": ["SPRING25"]
        }
      }
    }
  ],
  "platformContent": [
    {
      "locale": "en",
      "type": "text",
      "platform": "whatsapp",
      "channelGroupIds": [
        "3f979241-dea3-4f55-b7bb-d769eec27e51"
      ],
      "blocks": [
        {
          "type": "text",
          "role": "header",
          "text": {
            "text": "Spring Sale is Here!"
          }
        },
        {
          "type": "text",
          "role": "body",
          "text": {
            "text": "Hi {{customerName}}, our biggest Spring Sale is now live! Use code {{discountCode}} for 25% off everything. Don't miss out -- sale ends this Sunday."
          }
        },
        {
          "type": "text",
          "role": "footer",
          "text": {
            "text": "Reply STOP to unsubscribe"
          }
        },
        {
          "type": "link-action",
          "linkAction": {
            "text": "Shop the sale",
            "url": "https://example.com/spring-sale"
          }
        },
        {
          "type": "call-phone-number-action",
          "callPhoneNumberAction": {
            "text": "Call us",
            "phoneNumber": "[phone]"
          }
        },
        {
          "type": "reply-action",
          "replyAction": {
            "text": "Browse deals",
            "payload": "browse_deals"
          }
        },
        {
          "type": "reply-action",
          "replyAction": {
            "text": "Not interested",
            "payload": "opt_out"
          }
        }
      ]
    }
  ],
  "supportedPlatforms": ["whatsapp"],
  "shortLinks": {
    "enabled": true,
    "domain": "brd1.us"
  }
}

---

Deployments Reference

All WhatsApp templates require these deployments:

Key	Required	Description	Values
whatsappTemplateName	Yes	The template name registered with Meta	Lowercase, underscores only (e.g., seasonal_promo)
whatsappCategory	Yes	The template category. AUTHENTICATION can only be used with Authentication Template Blocks.	MARKETING or UTILITY (or AUTHENTICATION for authentication templates only)
whatsappAllowCategoryChange	Yes	Whether Meta can reassign the category. Always set to "true" -- Meta enforces category changes regardless of this setting. This field is still required by the API but may be deprecated in a future release.	"true"

---

Related

• Image Template Blocks -- Templates with image headers

• File & Video Template Blocks -- Templates with document or video headers

• Creating WhatsApp Message Templates -- Full template creation workflow