Text templates

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.

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.

Esempio di codice

{
  "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.

Esempio di codice

{
  "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.

Esempio di codice

{
  "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:

Esempio di codice

{
  "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.

Esempio di codice

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

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.

Esempio di codice

{
  "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.

Esempio di codice

{
  "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:

copy-code-action
link-action
call-phone-number-action
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.

Esempio di codice

"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:

Esempio di codice

{
  "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": "+14155551234"
          }
        },
        {
          "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"
  }
}

The optional shortLinks object enables link shortening and click tracking for the template's URLs. The domain must be "default" or a short link domain registered in your workspace. See Short Links in Message Templates.

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"

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