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 Cloud One Business Communication Suite 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:
|
| components | No | Array<Components> | The list of message components (Header, Body, and Button).Note:
|
Template_Lang
| Parameter | Required | Type | Description |
|---|---|---|---|
| code | Yes | String | The language code used for the template. |
ComponentsNote: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:
|
| 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
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
| 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:
|
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:
|
| 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:
|
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:
|
| text | String | The text content that will replace the corresponding placeholder (variable) in the template. Note:
|
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:
|
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\"