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.

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}}
    ]
  }
}

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

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 
}
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"
        }
      ]
    }
  ]
}
PreviousWork with APINextCreate a Carousel template

Last updated