Creating a template via API

Creating a template is described in the API documentation in the /addTemplate method.

You can also create a template from the 'Dev Toolkit → 'Test Requests' section in your personal account.

General part of the request:

name	The name of the template. Name can only contain lower case letters, digits and underscores.
allow_category_change	The 'Allow category changes' checkbox. Instead of rejecting the template, we will automatically change its category type.
category	Template type: MARKETING, UTILITY or AUTHENTICATION
language	Template language. The selected language must match the text in the template being created. Otherwise, the meta template may be rejected.
components	Array of Template components

Example:

{
  "token": "{{token}}",
  "name": "test_marketing_2024",
  "allow_category_change": false,
  "category": "MARKETING",
  "language": "ru",
  "components": [
    //objects of the template body
  ]
}

Let's look at the structure of the template category.

Marketing and Services Templates

HEADER

Headers are optional components that appear at the top of template messages.

Headers support TEXT, media (IMAGE, VIDEO или DOCUMENT). Templates are limited to one header component.

Each type is described in the table below.

TEXT

Set 'format' to 'TEXT' to define the header as text.

Rules for filling:

• Text may have a maximum of 60 characters.

• Text can contain only one variable.

• If the header contains a variable, it is required to specify an example in header_text.

Example of text without a variable:

{
    "type": "HEADER",
    "format": "TEXT",
    "text": "Hello"
}

Example of text with a variable:

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

IMAGE

Set 'format': 'IMAGE' to output an image in the header. Make sure you output the 'example' object with a link to the image in the 'header_handle'.

{
  "type": "HEADER",
  "format": "IMAGE",
  "example": {
      "header_handle": [
      "https://img-example-link.com/delicious-orange-23.jpg"
    ]
  }
}

VIDEO

Set 'format': 'VIDEO' to output an image in the header. Make sure you output the 'example' object with a link to the video in the 'header_handle'.

 {
      "type": "HEADER",
      "format": "VIDEO",
      "example": {
        "header_handle": [
          "https://video-example-link.com//banner.mp4"
        ]
      }
  }

DOCUMENT

Set 'format': 'DOCUMENT' to output an image in the header. Make sure you output the 'example' object with a link to the document in the 'header_handle'.

{
      "type": "HEADER",
      "format": "DOCUMENT",
      "example": {
        "header_handle": [
          "https://doc-example-link.com/reyshi.pdf"
        ]
    }
}

BODY

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

Rules for filling:

• Body component is required.

• Propetry 'text' can contain a maximum of 1024 characters.

• If there are variables in the text, it is required to specify examples of the variables in the 'example' section of the 'body_text' array. The number of lines in body_text must be equal to the number of variables in the text line.

• The number of variables is not limited by Meta.

• You cannot specify only a variable in the text. For example, Meta will not accept the format of the text "text": "{{1}}".

{
  "type": "BODY",
  "text": "Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.",
  "example": { // does not need to be specified if there are no variables in text
      "body_text": [
        [
          "the end of August", // example of the first variable
          "25OFF", // example of a second variable
          "25%" // example of a third variable
        ]
      ]
    }
}

FOOTER

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

{
    "type": "FOOTER",
    "text": "text for footer"
}

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.

What kind of buttons:

• Quick Reply.

  Quick reply buttons are custom text-only buttons that immediately message you with the specified text string when tapped by the app user. The text on the button can be written in any way you like.

• URL Button.

  URL buttons load the specified URL in the device's default web browser when tapped by the app user.

• Phone Number Button.

  Phone number buttons call the specified business phone number when tapped by the app user.

• Catalog Button (only available in the Marketing category).

  When a customer taps the View catalog button in a catalog template message, your product catalog appears within WhatsApp.

The URL and Phone button does not send a reply to the chat like the quick reply button.

Quantity limitation:

• Templates are limited to 10 quick reply buttons.

• Templates are limited to 2 URL buttons.

• Templates are limited to 1 Phone Number button.

• Only the Catalog button can be used in the Catalog template.

• Templates can have a mixture of up to 10 button components total

Examples of valid groupings:	Examples of invalid groupings:
Quick Reply, Quick Reply, 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

As you can see, you need to consider the order in which you enter the button type and the quantity of allowable buttons. For example, you can't add a Quick Reply button first, then a URL button, and then a Quick Reply button again.

QUICK REPLY

Quick reply buttons are custom text-only buttons that immediately message you with the specified text string when tapped by the app user. The text on the button can be written in any way you like. There is a limit of 25 characters.

 {
    "type": "QUICK_REPLY",
    "text": "Yes"
 }

URL

Property "text" : button label text. Supports 1 variable. 25 characters maximum.

If using a variable, must include the example property and a sample value.

Property "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. The API does not accept Cyrillic characters in URLs within button elements. Please ensure your URLs contain only Latin characters

If you specify a variable, you must specify an example in 'example'.

{
    "type": "URL",
    "text": "Shop Now",
    "url": "https://www.luckyshrub.com/shop?promo={{1}}",
    "example": [ // will be filled when a variable is added to the url. 
        "summer2023" // variable {{1}}
   ]
}

PHONE NUMBER

Property "phone_number": business phone number to be (display phone number) called when the user taps the button. 20 characters maximum.

Property "text" : button label text. 25 characters maximum.

Properties "phone_number" and "text" are required.

{
  "type": "PHONE_NUMBER",
  "text": "my number",
  "phone_number": "77777777777"
}

Untitled

Only one button can be added to the 'Catalog' template. It is mandatory to write "View catalog" in the 'text'. Depending on the language of the template, the text of the button will be translated into the specified language.

 {
   "type": "CATALOG",
   "text": "View catalog"
 }

Example Request

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

{
  "token": "{{token}}",
  "name": "test_marketing_2024",
  "allow_category_change": false,
  "category": "MARKETING",
  "language": "ru",
  "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"
        }
      ]
    }
  ]
}'

Authentication Template

Authentication templates include optional add-ons like security disclaimers and expiry warnings. In addition, authentication templates must have a one-time password button (copy code or one-tap).

The components value in the request must be an array of objects that describes each component that makes up the template. Authentication templates must have the following components:

• a single body component

• a single footer component. Footer is not required .

• a single OTP Button component

BODY

It consist of:

• Fixed preset text: <VERIFICATION_CODE> is your verification code. Don't fill the ‘text’ property.

• An optional security disclaimer: For your security, do not share this code.

If you want to add the text 'For your security, do not share this code', set 'add_security_recommendation': true. Set to false to exclude the string.

The selected template language determines the language of the text displayed to the user.

{
    "type": "BODY", 
    "add_security_recommendation": true 
}

FOOTER

Footer is not required .

It consist of:

• An optional expiration warning: This code expires in <NUM_MINUTES> minutes.

Specify an integer in 'code_expiration_minutes' to do this. You can enter minutes from 1 to 90.

If omitted, the code expiration warning will not be displayed in the delivered message.

{
  "type": "FOOTER", 
  "code_expiration_minutes": 5
}

BUTTONS

Authentication templates must include either a copy code or one-tap autofill button. These buttons have ‘type’: ‘OTP’.

Property "otp_type" - indicates button type. Set to COPY_CODE if you want the template to use a copy code button, or ONE_TAP to have it use a one-tap autofill button.

Only one button can be specified.

Свойство "text" - copy code button text. Note that even if your template is using a one-tap autofill button, this value must still be supplied. If Meta's unable to validate your handshake the authentication template message will display a copy code button with this text instead. Maximum 25 characters.

For type ONE_TAP, the following fields must also be filled in:

• autofill_text - one-tap button text. Maximum 25 characters.

• package_name - your Android app's package name.

• signature_hash - your app signing key hash. See Meta's Official documentation for App Signing Key Hash.

An example of a code copy button:

   {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "OTP",
          "otp_type": "COPY_CODE",
          "text": "Скопировать"
        }
      ]
    }

An example of a one-touch autofill button:

  { 
    "type": "BUTTONS",
    "buttons": [
      {
        "type": "OTP",
        "otp_type": "ONE_TAP",
        "text": "Copy Code",
        "autofill_text": "Autofill", // One-tap buttons only
        "package_name": "com.example.myapplication", // One-tap buttons only
        "signature_hash": "K8a%2FAINcGX7" // One-tap buttons only
      }
    ]
  }

Full example of sending an Authentication template

{
  "token": "{{token}}",
  "name": "auth_2024",
  "allow_category_change": false,
  "category": "AUTHENTICATION",
  "language": "ru",
  "components": [
   {
    "type": "BODY",
    "add_security_recommendation": true
  },
  {
    "type": "FOOTER", 
    "code_expiration_minutes": 5
  },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "OTP",
          "otp_type": "COPY_CODE",
          "text": "Copy Code"
        }
      ]
    }
  ]
}