WhatsApp Message Template Component Description

This topic provides an overview of the WhatsApp message template components required in the request payload when creating/editing a WhatsApp campaign or sending a WhatsApp template message via API. It details the structure and parameters of each component to help you construct compliant and effective messages.

Introduction

A WhatsApp message template consists of four primary components: Header, Body, Footer, and Buttons. Among these, the Header, Body, and Buttons components support placeholders for dynamic variables.

When creating/editing a WhatsApp campaign or sending a WhatsApp template message via the Yeastar P-Series PBX System API, you need to provide the values for the variables corresponding to the placeholders in the template, as well as any required button details (such as button type and button variable values, if applicable). The fixed text content is automatically sourced from the template itself.

To achieve this, construct a message object by replacing all placeholders with their corresponding variable values, serialize this message object into a JSON string, and then pass the escaped JSON string in the parameter msg_param (for WhatsApp message campaign) or whatsapp_msg_param (for WhatsApp message session).

Message template object structure

The PBX API uses the parameter msg_param or whatsapp_msg_param to deliver the required information for WhatsApp message templates. The parameter is a string containing a JSON-encoded object that defines the structure, components, and dynamic values of the message template.

Below is an example of the JSON structure for msg_param or whatsapp_msg_param parameter:

{
    "id": 579,
    "template_id": "1617698099069106",
    "name": "template202501",
    "language": {
        "code": "en"
    },
    "parameter_format": "POSITIONAL",
    "components": [
        {
            "type": "HEADER",                 //Template header
            "parameters": [
                {
                   ...
                }
            ]
        },
        {
            "type": "BODY",                   //Template body
            "parameters": [
                {
                    ...
                }
            ]
        },
        {                     
            "type": "BUTTONS",                 //Template button
            "parameters": [
                {
                    ...
                }
            ]
        }
    ]
}

The following table describes each parameter in the structure.


Parameter	Required	Type	Description
id	Yes	Integer	The ID of the message template in the PBX system.
template_id	Yes	String	The original template ID from the WhatsApp platform.
name	Yes	String	Template name.
language	Yes	Object<Template_Lang>	Template language.
parameter_format	Yes	String	Whether placeholders are referenced by position or by variable name. Valid value: `POSITIONAL`: Placeholders are referenced by their position, such as `{{1}}`, `{{2}}`. `NAMED`: Placeholders are referenced by their variable names, such as `{{name}}`, `{{code}}`.
components	No	Array<Components>	The list of message components (Header, Body, and Button). Note: This parameter is REQUIRED if the template include variables or buttons. If the template contains only static text (no variables or buttons), this parameter can be left empty.

Template_Lang


Parameter	Required	Type	Description
code	Yes	String	The language code used for the template.

Components

Note: The required fields within componnets parameter depend on the specific requirements of the chosen WhatsApp message template.


Parameter	Type	Description
type	String	The type of the component. Valid value: `HEADER` `BODY` `BUTTONS`
parameters	Array <Object>	The list of values for the placeholders (variables) in the component. Each placeholder in the template requires a specific value when sending a message. You can use this parameter to specify the values that will replace the placeholders in the template. For more information about the parameters in each components, see the following sections: Header component object Body component object Button component object

Header component object

The Header component object defines the parameters used when the component type is set to HEADER.

The Header component supports the following types:

Text header
Media header (image, video, document)
Location header

Text header


Parameter	Type	Description
type	String	The type of the element. Valid value: `TEXT`.
text	String	The text content that will replace the corresponding placeholder (variable) in the element.
parameter_name	String	The name of the placeholder (variable). Note: This parameter is REQUIRED when the `parameter_format` is `NAMED`. You can obtain the required parameter name from the desired WhatsApp template using Get WhatsApp Message Templates.

For example:

Named parameter example

 {
      "type": "HEADER",
      "parameters": [
            {
                 "type": "TEXT",
                 "text": "Gold",
                 "parameter_name": "membershiptype"
            }
          ]
  }

Positional parameter example

{
      "type": "HEADER",
      "parameters": [
            {                             //{{1}} in header
                 "type": "TEXT",
                 "text": "Gold"
            }
          ]
  }

Media header


Parameter	Type	Description
type	String	The type of the element. Valid value: `IMAGE` `VIDEO` `DOCUMENT`
file_list	Array	The information of the media file. Note: You need to first upload the file using the Upload Files for Messaging, then get the file information from the response.

For example:

Image object

 {
      "type": "HEADER",
      "parameters": 
      [
         {
            "type": "IMAGE",
            "file_list": [
                        {
                            "id": "993d9780ec2c4a3f81f59fa78a40ecb6",
                            "name": "demo.png",
                            "uri": "20250805/993d9780ec2c4a3f81f59fa78a40ecb6",
                            "type": "image/png",
                            "size": 5651
                        }
                    ]
          }
      ]
 }

Video object

 {
      "type": "HEADER",
      "parameters": 
      [
         {
            "type": "VIDEO",
                    "file_list": [
                        {
                            "id": "dfb5077f93e040b381da8d9a597c4743",
                            "name": "demo.mp4",
                            "uri": "20250805/dfb5077f93e040b381da8d9a597c4743",
                            "type": "video/mp4",
                            "size": 1745551
                        }
                    ]
          }
      ]
  }

Document object

 {
      "type": "HEADER",
      "parameters": 
      [
         {
            "type": "DOCUMENT",
                    "file_list": [
                       {
                          "id": "d71a2a146a5146fcb0b1464e293ea38e",
                          "name": "demo.csv",
                          "uri": "20250801/d71a2a146a5146fcb0b1464e293ea38e",
                          "type": "text/csv",
                          "size": 56890
                      }
                    ]
          }
      ]
 }

Location header


Parameter	Type	Description
type	String	The type of the element. Valid value: `LOCATION`.
location	Object<Location_Info>	The detailed location information.

Location_Info


Parameter	Type	Description
name	String	Name of the location.
address	String	Address of the location.
latitude	String	Location latitude in decimal degrees.
longitude	String	Location longitude in decimal degrees.

For example:

 {
       "type": "HEADER",
       "parameters": [
            {
               "type": "LOCATION",
               "location": {
                    "name": "Madison Square Garden",
                    "address": "4 Pennsylvania Plaza, Suite 105, New York, NY 10001",
                    "latitude": "40.7505045",
                    "longitude": "-73.9934387"
                   }
              }
         ]
}

Body component object

The Body component object defines the parameters used when the component type is set to BODY.

Note: Only text parameter is supported in the Body component.


Parameter	Type	Description
type	String	The type of the element. Valid value: `TEXT`.
text	String	The text content that will replace the corresponding placeholder (variable) in the element.
parameter_name	String	The name of the placeholder (variable). Note: This parameter is REQUIRED when the `parameter_format` is `NAMED`. You can obtain the required parameter name from the desired WhatsApp template using Get WhatsApp Message Templates.

For example:

Named parameter example

 {
      "type": "BODY",
      "parameters": [
            {
                 "type": "TEXT",
                 "text": "Gold",
                 "parameter_name": "membershiptype"
             },
             {
                 "type": "TEXT",
                 "text": "2025-08-30",
                 "parameter_name": "expirydate"
             },
             {
                  "type": "TEXT",
                  "text": "2025-09-30",
                  "parameter_name": "renewdeadline"
             }
          ]
  }

Positional parameter example

 {
      "type": "BODY",
      "parameters": [
            {                             //{{1}} in body
                 "type": "TEXT",
                 "text": "Gold"
             },
             {                            //{{2}} in body 
                 "type": "TEXT",
                 "text": "2025-08-30"
             },
             {                            //{{3}} in body
                  "type": "TEXT",
                  "text": "2025-09-30"
             }
          ]
  }

Button component object

The Button component object defines the parameters used when the component type is set to BUTTON.


Parameter	Type	Description
type	String	The type of the button element. Valid value: `URL` `FLOW` `COPY_CODE` `QUICK_REPLY`
text	String	The text content that will replace the corresponding placeholder (variable) in the template. Note: This parameter is REQUIRED only for the following buttons: URL button that include a variable COPY CODE button For other button types, this parameter can be left empty.

For example:

  {
            "type": "BUTTONS",
            "parameters": [                        // Assemble an array of multiple buttons in order.
               {
                    "type": "URL",
                    "text": "summer2024"
                },
                {
                    "type": "FLOW",
                    "text": ""
                },
                {
                    "type": "COPY_CODE",
                    "text": "codeA"
                },
                {
                    "type": "QUICK_REPLY",
                    "text": ""
                }
            ]
        }

Complete template parameter example

This example demonstrates how to construct and pass the full set of parameters for a marketing template message.


Component	Template Content
Header	Location header.
Body	Text body with the campaign details: `You are invited to our {{campaign}}! Show this code at the entrance to get your exclusive gift: {{code}} Event time: {{date}}`
Footer	Plain text: `Remember to bring your code!` Note: The Footer does not need to be included in the parameter, as it will be automatically retrieved from the template.
Button	The following buttons are included in the template: A quick-reply button `Interest` A URL button with a variable appended at the end of the URL `https://www.example.com/sales?promo={{1}}`

In this case, the content of the msg_param or whatsapp_msg_param parameter should be:

{
"id":1781,
"template_id":"1713250439356384",
"name":"summer_sale_event",
"language":{"code":"en"},
"components":
  [
    {                                             //Location header
	  "type":"HEADER",
	  "parameters":
	    [
		 {
		   
		  "type":"LOCATION",
		  "location":
		    {
			  "name":"Madison Square Garden",
			  "address":"4 Pennsylvania Plaza, Suite 105, New York, NY 10001",
			  "latitude":"40.7505045",
			  "longitude":"-73.9934387"
			},
		 }
		]
    },
	{                                           //Named text body
	  "type":"BODY",
	  "parameters":
	    [
		  {"type":"TEXT","text":"Summer Sale Event","parameter_name": "campaign"},
		  {"type":"TEXT","text":"AD8J398","parameter_name": "code"},
		  {"type":"TEXT","text":"2025-8-5","parameter_name": "date"}
		]
    },
	{                                            //Buttons
	  "type":"BUTTONS",
	  "parameters":
	    [
		  {"type":"QUICK_REPLY","text":""},
		  {"type":"URL","text":"summer_2025"}
		]
    }
  ],
"parameter_format":"NAMED"
}

You need to convert the above object to an escaped JSON string when passing it as the value of the msg_param or whatsapp_msg_param parameter:

"msg_param":"{\"id\":1781,\"template_id\":\"1713250439356384\",\"name\":\"summer_sale_event\",\"language\":{\"code\":\"en\"},\"components\":[{\"type\":\"HEADER\",\"parameters\":[{\"type\":\"LOCATION\",\"location\":{\"name\":\"Madison Square Garden\",\"address\":\"4 Pennsylvania Plaza, Suite 105, New York, NY 10001\",\"latitude\":\"40.7505045\",\"longitude\":\"-73.9934387\"}}]},{\"type\":\"BODY\",\"parameters\":[{\"type\":\"TEXT\",\"text\":\"Summer Sale Event\",\"parameter_name\":\"campaign\"},{\"type\":\"TEXT\",\"text\":\"AD8J398\",\"parameter_name\":\"code\"},{\"type\":\"TEXT\",\"text\":\"2025-8-5\",\"parameter_name\":\"date\"}]},{\"type\":\"BUTTONS\",\"parameters\":[{\"type\":\"QUICK_REPLY\",\"text\":\"\"},{\"type\":\"URL\",\"text\":\"summer_2025\"}]}],\"parameter_format\":\"NAMED\"}"