WABA Templates — API Create and Send Template

Create Template

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

VIDEO

DOCUMENT

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

PHONE NUMBER

Untitled

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

BUTTONS

Full example of sending an Authentication template

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

Sending a template via API

Sending a template is described in the API documentation in the /sendTemplate method.

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

To send a template, you need to know the namespace, name and language of the template. To get this information, call the 'Get list of templates' method (/templates).

Some properties that can cause problems in the /sendTemplate method.

Свойства	Описание
template	It's the name of the template
language	policy: write "deterministiс" code: language from the /templates method
Object with type "body"	Text message. Can be omitted if there are no variables in the text.
Object with type "button"	You can display only buttons with sub_type ‘url’ or ‘catalog’ in the body. Other types of buttons can be omitted when sending the template

Send Marketing or Utility templates

In requests, you should only send the objects that you have specified in the created template. For example, if there is no HEADER in the template, do not send it. Objects are also omitted if:

• Header object of type Text without variable;

• Body without variable;

• Quick reply buttons and number buttons are always omitted;

• URL button without variable.

Header objects of type IMAGE, VIDEO, DOCUMENT always contain the full link to the media document. Note that the link to the media document must contain the format of the document.

Example of sending a Document with URL button

Structure:

• Header of document type

• Body contains 2 variables

• Two URL buttons, the second of which contains a variable.

If a URL button does not have a variable, omit it from the request. For example, in this request, the first URL button with index 0 is omitted, but the second button is output. Note also that the index of the second button is already 1.

{
  "namespace": "{{namespace}}",
  "template": "delivery_tracking",
  "language": {
    "policy": "deterministic",
    "code": "ru"
  },
  "params": [
    {
      "type": "header",
      "parameters": [
        {
          "type": "document", // document object
          "document": {
            "link": "https://test.com/reyshi.pdf" //link to the document. Please note that the link must specify the format of the document
          }
        }
      ]
    },
    {
      "type": "body",
      "parameters": [
        {
          "type": "text",
          "text": "Андрей" // first variable in BODY
        },
        {
          "type": "text",
          "text": "№003478" // second variable in BODY
        }
      ]
    },
    {
      "type": "button", // second URL button
      "sub_type": "url",
      "index":1, // index is numbered starting from zero, the second button has index 1
      "parameters": [
        {
          "type": "text",
          "text": "/reyshi" // link variable
        }
      ]
    }
  ],
  "phone": "{{phone}}"
}

Example of sending a Text Header with all types of buttons

Structure:

• Header of Text type with one variable

• The body of the message does not contain a variable. Therefore, it is omitted in the query.

• 4 buttons. The first button is quick reply, the second is phone button, the third is URL button with variable, the fourth is URL button without variable.

{
  "namespace": "{{namespace}}",
  "template": "utility_all_buttons_2024_05",
  "language": {
    "policy": "deterministic",
    "code": "en"
  },
  "params": [
    {
      "type": "header",
      "parameters": [
        {
          "type": "text",
          "text": "Anna" // header variable
        }
      ]
    },
    {
      "type": "button", // third button, a URL button with a variable
      "sub_type": "url",
      "index": 2, // third button index
      "parameters": [
        {
          "type": "text",
          "text": "inbox" // link variable
        }
      ]
    }
  ],
  "phone": "{{phone}}"
}

Send the "Authentication" template

Example of sending an authentication template

Example of sending a code copy button

{
  "namespace": "{{namespace}}",
  "template": "auth_2",
  "language": {
    "policy": "deterministic",
    "code": "ru"
  },
  "params": [
        {
      "type": "body",
      "parameters": [
        {
          "type": "text",
          "text": "05425" // code displayed in the message body
        }
      ]
    },
    {
      "type": "BUTTON",
      "sub_type": "URL",
      "index": 0,
      "parameters": [
        {
          "type": "TEXT",
          "text": "05425" // the code that will be copied
        }
      ]
    }
  ],
  "phone": "[phone]"
}