Template Elements

Templates are composed of various text, media, and interactive elements, which can be mixed to build the best user experience. All options are accessible via the Messaging API and WhatsApp Manager. Some functionalities on the 360dialog Template Manager UI are restricted.

Variables

Any template that has one or more variables requires a sample in order to be submitted for review. You can add samples by including the example property in API request.

You can also include allow_category_change=true in your API request to avoid template rejection due to miscategorization. Including this parameter and value will allow Meta to assign whatever category they determine to be appropriate.

For example:

{
  "name": "sample",
  "category": "UTILITY",
  "components": [
    {
      "format": "TEXT",
      "text": "New request",
      "type": "HEADER"
    },
    {
      "type": "BODY",
      "text": "Hi {{1}}, thanks for getting in touch with {{2}}. We will process your request get back to you shortly",
      "example": {
        "body_text": [
          [
            "Emilia",
            "360dialog"
          ]
        ]
      }
    },
    {
      "text": "WhatsApp Business API provided by 360dialog",
      "type": "FOOTER"
    }
  ],
  "language": "en_US",
  "allow_category_change": true
}

Components

Headers

Headers are optional components that appear at the top of template messages. Headers support text, media (images, videos, documents), and locations. Templates are limited to one header component.

Text Headers

Syntax

{
  "type": "HEADER",
  "format": "TEXT",
  "text": "<TEXT>",

  # Required if <TEXT> string contains variables
  "example": {
    "header_text": [
      "<HEADER_TEXT>"
    ]
  }
}

Properties

Placeholder	Description	Example Value
<HEADER_TEXT>	Sample header text.	Summer Sale
<TEXT>	Text to appear in template header when sent. Supports 1 variable. If the string contains a variable, you must include the example property and a sample variable value. 60 characters maximum.	Our {{1}} is on!

Example

{
  "type": "HEADER",
  "format": "TEXT",
  "text": "Our {{1}} is on!",
  "example": {
    "header_text": [
      "Summer Sale"
    ]
  }
}

Media Headers

Media headers can be an image, video, or a document such as a PDF. The syntax for defining a media header is the same for all media types.

Syntax

{
  "type": "HEADER",
  "format": "<FORMAT>",
  "example": {
    "header_handle": [
      "<URL>"
    ]
  }
}

Properties

Placeholder	Description	Example Value
<FORMAT>	Indicates media asset type. Set to IMAGE, VIDEO, or DOCUMENT.	IMAGE
<URL>	Link to a file	https://www.gstatic.com/webp/gallery/1.jpg

Example

{
  "type": "HEADER",
  "format": "IMAGE",
  "example": {
    "header_handle": [
      "https://www.gstatic.com/webp/gallery/1.jpg"
    ]
  }
}

Location Headers

Location headers appear as generic maps at the top of the template and are useful for order tracking, delivery updates, ride hailing pickup/dropoff, locating physical stores, etc. When tapped, the app user's default map app will open and load the specified location.

Location headers can only be used in templates categorized as UTILITY or MARKETING. Real-time locations are not supported.

Syntax

{
  "type": "HEADER",
  "format": "LOCATION"
}

Properties

Property values cannot be customized.

Example

{
  "type": "HEADER",
  "format": "LOCATION"
}

Body

Body components are text-only components and are required by all templates. Templates are limited to one body component.

Syntax

{
  "type": "BODY",
  "text": "<TEXT>",
  
  # Required if <TEXT> string contains variables
  "example": {
    "body_text": [
      [
        <BODY_TEXT>
      ]
    ]
  }
}

Properties

Placeholder	Description	Example Value
<BODY_TEXT>	Array of sample strings. Number of strings must match the number of variables included in the string.	"the end of August","25OFF","25%"
<TEXT>	Text string. Supports multiple variables. If the string contains variables, you must include the example property and sample variable values. 1024 characters maximum.	Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.

Example

{
  "type": "BODY",
  "text": "Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.",
    "example": {
      "body_text": [
        [
          "the end of August","25OFF","25%"
        ]
      ]
    }
}

Footer

Footers are optional text-only components that appear immediately after the body component. Templates are limited to one footer component.

Syntax

{
  "type": "FOOTER",
  "text": "<TEXT>"
}

Properties

Placeholder	Description	Example Value
<TEXT>	Text to appear in template footer when sent. 60 characters maximum.	Use the buttons below to manage your marketing subscriptions

Example

{
  "type": "FOOTER",
  "text": "Use the buttons below to manage your marketing subscriptions"
}

Buttons

Buttons are optional interactive components that perform specific actions when tapped. Templates can have a mixture of up to 10 button components total, although there are limits to individual buttons of the same type as well as combination limits.

These limits are described below:

Examples of valid groupings	Examples of invalid groupings:
Quick Reply, Quick Reply Quick Reply, Quick Reply, URL, Phone URL, Phone, Quick Reply, Quick Reply	Quick Reply, URL, Quick Reply URL, Quick Reply, URL

Buttons are defined within a single buttons component object, packed into a single buttons array. For example, this template uses a phone number button and a URL button:

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "PHONE_NUMBER",
      "text": "Call",
      "phone_number": "15550051310"
    },
    {
      "type": "URL",
      "text": "Shop Now",
      "url": "https://www.luckyshrub.com/shop/"
    }
  ]
}

If you include a button with a variable that is a URL, it must be URL-encoded.

If a template has more than three buttons, two buttons will appear in the delivered message and the remaining buttons will be replaced with a See all options button. Tapping the See all options button reveals the remaining buttons.

Phone Number Buttons

Phone number buttons call the specified business phone number when tapped by the app user. Templates are limited to one phone number button.

Syntax

{
  "type": "PHONE_NUMBER",
  "text": "<TEXT>",
  "phone_number": "<PHONE_NUMBER>"
}

Properties

Placeholder	Description	Example Value
<PHONE_NUMBER>	Alphanumeric string. Business phone number to be (display phone number) called when the user taps the button. 20 characters maximum.	15550051310
<TEXT>	Button label text. 25 characters maximum.	Call

Example

{
  "type": "PHONE_NUMBER",
  "text": "Call",
  "phone_number": "15550051310"
}

URL Buttons

URL buttons load the specified URL in the device's default web browser when tapped by the app user. Templates are limited to two URL buttons.

If you include a button with a variable that is a URL, it must be URL-encoded.

Syntax

{
  "type": "URL",
  "text": "<TEXT>",
  "url": "<URL>",

  # Required if <URL> contains a variable
  "example": [
    "<EXAMPLE>"
  ]
}

Properties

Placeholder	Description	Example Value
<EXAMPLE>	URL of website. Supports 1 variable. If using a variable, add sample variable property to the end of the URL string. The URL loads in the device's default mobile web browser when the customer taps the button. 2000 characters maximum.	https://www.luckyshrub.com/shop?promo=summer2023 The API does not accept Cyrillic characters in URLs within button elements. Please ensure your URLs contain only Latin characters.
<TEXT>	Button label text. Supports 1 variable. If using a variable, must include the example property and a sample value. 25 characters maximum.	Shop Now
<URL>	URL of website that loads in the device's default mobile web browser when the button is tapped by the app user. Supports 1 variable, appended to the end of the URL string. 2000 characters maximum.	https://www.luckyshrub.com/shop?promo={{1}} The API does not accept Cyrillic characters in URLs within button elements. Please ensure your URLs contain only Latin characters.

Example

{
  "type": "URL",
  "text": "Shop Now",
  "url": "https://www.luckyshrub.com/shop?promo={{1}}",
  "example": [
    "summer2023"
  ]
}

Example Request - Limited Time Offer

An example request to create a marketing template with the following components:

• an image header with a sample value

• a text body with variables and sample values

• a text footer

• a phone number button

• a URL button

{
  "name": "limited_time_offer_tuscan_getaway_2023",
  "language": "en_US",
  "category": "MARKETING",
  "components": [
    {
      "type": "HEADER",
      "format": "IMAGE",
      "example": {
        "header_handle": [
          "4::aW..."
        ]
      }
    },
    {
      "type": "BODY",
      "text": "Hi {{1}}! For a limited time only you can get our {{2}} for as low as {{3}}. Tap the Offer Details button for more information.",
      "example": {
        "body_text": [
          [
            "Pablo","Tuscan Getaway package","800"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "Offer valid until May 31, 2023"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "PHONE_NUMBER",
          "text": "Call",
          "phone_number": "15550051310"
        },
        {
          "type": "URL",
          "text": "Shop Now",
          "url": "https://www.luckyshrub.com/shop?promo={{1}}",
          "example": [
            "summer2023"
           ]
        }
      ]
    }
  ]
}

SPM Buttons

Single-product message (SPM) buttons are specific, non-customizable buttons that can be mapped to a product in your product catalog. When tapped, they load details about the product, which it pulls from your catalog. Users can then add the product a card and place an order. See Single-Product Message Templates and Product Card Carousel Templates.

Quick Reply Buttons

Quick reply buttons are custom text-only buttons that immediately message you with the specified text string when tapped by the app user. A common use case-case is a button that allows your customer to easily opt-out of any marketing messages.

Templates are limited to 10 quick reply buttons. If using quick reply buttons with other buttons, buttons must be organized into two groups: quick reply buttons and non-quick reply buttons. If grouped incorrectly, the API will return an error indicating an invalid combination.

Examples of valid groupings:

• Quick Reply, Quick Reply

• Quick Reply, Quick Reply, URL, Phone

• URL, Phone, Quick Reply, Quick Reply

Examples of invalid groupings:

• Quick Reply, URL, Quick Reply

• URL, Quick Reply, URL

When using the Cloud API or On-Premises API to send a template that has multiple quick reply buttons, you can use the index property to designate the order in which buttons appear in the template message.

Syntax

{
  "type": "QUICK_REPLY",
  "text": "<TEXT>"
}

Properties

Placeholder	Description	Example Value
<TEXT>	Button label text. 25 characters maximum.	Unsubscribe

Example

{
  "type": "QUICK_REPLY",
  "text": "Unsubscribe from Promos"
}

Example Request - Seasonal Promotion

An example request to create a marketing template with the following components:

• a text header with a variable and sample value

• a text body with variables and sample values

• a text footer

• two quick-reply buttons

{
  "name": "seasonal_promotion",
  "language": "en_US",
  "category": "MARKETING",
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Our {{1}} is on!",
      "example": {
        "header_text": [
          "Summer Sale"
        ]
      }
    },
    {
      "type": "BODY",
      "text": "Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.",
      "example": {
        "body_text": [
          [
            "the end of August","25OFF","25%"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "Use the buttons below to manage your marketing subscriptions"
    },
    {
      "type":"BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Unsubscribe from Promos"
        },
        {
          "type":"QUICK_REPLY",
          "text": "Unsubscribe from All"
        }
      ]
    }
  ]
}

Copy Code Buttons

Copy code buttons copy a text string (defined when the template is sent in a template message) to the device's clipboard when tapped by the app user. Templates are limited to one copy code button.

Syntax

{
  "type": "COPY_CODE",
  "example": "<EXAMPLE>"
}

Properties

Placeholder	Description	Example Value
<EXAMPLE>	String to be copied to device's clipboard when tapped by the app user. Maximum 15 characters.	250FF

Example

{
  "type": "COPY_CODE",
  "example": "250FF"
}

OTP Buttons

One-time password (OTP) buttons are a special type of URL button used with authentication templates. See Authentication Templates.

Flows Buttons

Flows buttons are for sending Flows Messages as templates. Templates are limited to one Flows button.

Syntax

{
  "type": "FLOW",
  "text": "<TEXT>",
  "flow_id": "<FLOW_ID>",
  "flow_action": "<FLOW_ACTION>",
  "navigate_screen": "<NAVIGATE_SCREEN>"
}

Properties

Placeholder	Description	Example Value
<TEXT>	Button label text. 25 characters maximum.	Sign up
<FLOW_ID>	Unique identifier of the Flow provided by WhatsApp. The Flow must be published.	123456789012345
<FLOW_ACTION>	navigate or data_exchange. Use navigate to predefine the first screen as part of the template message. Use data_exchange for advanced use-cases where the first screen is provided by your endpoint. Default: navigate	navigate
<NAVIGATE_SCREEN>	Required only if flow_action is navigate. The id of the first screen of the Flow.	flow_json_first_screen

Example

{
  "type": "FLOW",
  "text": "Sign up",
  "flow_id": "123456789012345",
  "flow_action": "navigate",
  "navigate_screen": "flow_json_first_screen"
}

Example Requests

Seasonal Promotion

An example request to create a marketing template with the following components:

• a text header with a variable and sample value

• a text body with variables and sample values

• a text footer

• two quick-reply buttons

{
  "name": "seasonal_promotion",
  "language": "en_US",
  "category": "MARKETING",
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Our {{1}} is on!",
      "example": {
        "header_text": [
          "Summer Sale"
        ]
      }
    },
    {
      "type": "BODY",
      "text": "Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.",
      "example": {
        "body_text": [
          [
            "the end of August","25OFF","25%"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "Use the buttons below to manage your marketing subscriptions"
    },
    {
      "type":"BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Unsubscribe from Promos"
        },
        {
          "type":"QUICK_REPLY",
          "text": "Unsubscribe from All"
        }
      ]
    }
  ]
}'

Order Confirmation

An example request to create a utility template with the following components:

• a document header with a sample value

• a text body with variables and sample values

• a phone number button

• a URL button

{
  "name": "order_confirmation",
  "language": "en_US",
  "category": "UTILITY",
  "components": [
    {
      "type": "HEADER",
      "format": "DOCUMENT",
      "example": {
        "header_handle": [
          "4::YX..."
        ]
      }
    },
    {
      "type": "BODY",
      "text": "Thank you for your order, {{1}}! Your order number is {{2}}. Tap the PDF linked above to view your receipt. If you have any questions, please use the buttons below to contact support. Thank you for being a customer!",
      "example": {
        "body_text": [
          [
            "Pablo","860198-230332"
          ]
        ]
      }
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "PHONE_NUMBER",
          "text": "Call",
          "phone_number": "15550051310"
        },
        {
          "type": "URL",
          "text": "Contact Support",
          "url": "https://www.luckyshrub.com/support"
        }
      ]
    }
  ]
}'