Send WhatsApp Templated Message V2

Published on Aug 6, 2025

14 minute(s) read

Post

/v2/whatsapp/sendtemplatedmessage/{ENCRYPTED_STREAM_ID}

This API sends a generated WhatsApp template from the WhatsApp Business Account (WABA) to a single recipient or to multiple recipients (up to 20).

Key New Capabilities of V2 version

Marketing and Utility Templates may have a header with text or added media (attached document, image, or video), a footer, and a call for action or quick reply buttons.
The API can also create CommBox object(s), support subchannels, and enable scheduled publishing by adding unix timestamp code to the schedule field (see the 'Send a template with text' example).

Send Templated Message + Object data

Sending any templated WhatsApp message with Object data also creates a conversation (Object) on the CommBox platform.

Note: Adding the ManagerId field with the agent’s Id (optional) will ensure the agent is reflected in various reports. Objects without a managerId will display conversations as being initiated by 'customer'.

The required and optional fields are described here: https://www.commbox.io/api/#operation/Create_Object

Send Templated Message with an Attached Media

There are two ways to do so:

Sending a Templated Message with a link to the file. Example below: 'Send a template with an attachment (doc)'.

OR
Use the /whatsapp/uploadmedia/ API endpoint to upload the file to WhatsApp servers and then fetch the uploaded file ID from the response for sending a templated message with the attachment ID. See the 'Send a template with an attachment ID (video)' example.

Authentication Templates

See the Examples for sending an authentication template.

For more information:

https://help.commbox.io/docs/creating-new-whatsapp-authentication-templates

https://developers.facebook.com/docs/whatsapp/updates-to-pricing/new-template-guidelines/#authentication-templates

Security

HTTP

Type bearer

API key is needed to authorize requests. You can get your API key via the management console.
A Bearer Token is needed to be set in the Authorization header of every API call.
For additional support you can contact us.

Path parameters

ENCRYPTED_STREAM_ID

Required

CommBox generated encryption for the channel

Body parameters

Send a template with text

{
  "data": [
    {
      "schedule": 1739365010,
      "template_data": {
        "to": "19172537000",
        "template": {
          "name": "Text Template",
          "language": {
            "code": "en"
          },
          "components": []
        }
      }
    }
  ]
}

Send a template with text + Object data

{
  "data": [
    {
      "template_data": {
        "to": "19172537000",
        "template": {
          "name": "Text Template",
          "language": {
            "code": "en"
          },
          "components": []
        }
      },
      "object_data": {
        "createChildObject": true,
        "SubStreamId": 0,
        "StatusId": 1,
        "ManagerId": 78121,
        "Content": {},
        "User": {
          "UniqueId": "01234567",
          "LastName": "Doe",
          "FirstName": "John",
          "Phone1": "19172537000",
          "Email": "John.D@gmail.com",
          "Remarks": "Returning customer"
        }
      }
    }
  ]
}

Send a template with 2 body parameters

{
  "data": [
    {
      "template_data": {
        "to": "19172537000",
        "template": {
          "name": "Basic WA template",
          "language": {
            "code": "en"
          },
          "components": [
            {
              "type": "body",
              "parameters": [
                {
                  "type": "text",
                  "text": "Hellooooo"
                },
                {
                  "type": "text",
                  "text": "my friend"
                }
              ]
            }
          ]
        }
      }
    }
  ]
}

Send a template with header & body parameters

{
  "data": [
    {
      "template_data": {
        "to": "972537280000",
        "template": {
          "name": "Text Header & Body",
          "language": {
            "code": "he"
          },
          "components": [
            {
              "type": "header",
              "parameters": [
                {
                  "type": "text",
                  "text": "text1"
                }
              ]
            },
            {
              "type": "body",
              "parameters": [
                {
                  "type": "text",
                  "text": "text2"
                }
              ]
            }
          ]
        }
      }
    }
  ]
}

Send a template with header & body parameters + Object data

{
  "data": [
    {
      "template_data": {
        "to": "972537280801",
        "template": {
          "name": "ren_text_header_body",
          "language": {
            "code": "he"
          },
          "components": [
            {
              "type": "header",
              "parameters": [
                {
                  "type": "text",
                  "text": "text1"
                }
              ]
            },
            {
              "type": "body",
              "parameters": [
                {
                  "type": "text",
                  "text": "text2"
                }
              ]
            }
          ]
        }
      },
      "object_data": {
        "createChildObject": true,
        "SubStreamId": 0,
        "StatusId": 1,
        "ManagerId": 78121,
        "Content": {},
        "User": {
          "UniqueId": "01234567",
          "LastName": "Doe",
          "FirstName": "John",
          "Phone1": "97253720000",
          "Email": "John.Doe@gmail.com",
          "Remarks": "some remark for user"
        }
      }
    }
  ]
}

Send a template with 3 body parameters + Object data

{
  "data": [
    {
      "template_data": {
        "to": "972537280801",
        "template": {
          "name": "multiple_params_in_body",
          "language": {
            "code": "en_GB"
          },
          "components": [
            {
              "type": "body",
              "parameters": [
                {
                  "type": "text",
                  "text": "https://www.commbox.io"
                },
                {
                  "type": "text",
                  "text": "https://www.commbox.io2"
                },
                {
                  "type": "text",
                  "text": "https://www.commbox.io3"
                }
              ]
            }
          ]
        }
      },
      "object_data": {
        "createChildObject": true,
        "SubStreamId": 0,
        "StatusId": 1,
        "ManagerId": 78121,
        "Content": {},
        "User": {
          "UniqueId": "01234567",
          "LastName": "Doe",
          "FirstName": "John",
          "Phone1": "97253720000",
          "Email": "john.doe@gmail.com",
          "Remarks": "some remark for user"
        }
      }
    }
  ]
}

Send a template with an attachment (image)

{
  "data": [
    {
      "template_data": {
        "to": "19172537000",
        "template": {
          "name": "header_image",
          "language": {
            "code": "en"
          },
          "components": [
            {
              "type": "header",
              "parameters": [
                {
                  "type": "image",
                  "image": {
                    "link": "https://picsum.photos/200"
                  }
                }
              ]
            },
            {
              "type": "body",
              "parameters": [
                {
                  "type": "text",
                  "text": "hello"
                }
              ]
            }
          ]
        }
      }
    }
  ]
}

Send a template with an attachment (image) + Object data

{
  "data": [
    {
      "template_data": {
        "to": "19172537000",
        "template": {
          "name": "test_wisspp_4",
          "language": {
            "code": "en"
          },
          "components": [
            {
              "type": "header",
              "parameters": [
                {
                  "type": "image",
                  "image": {
                    "link": "https://picsum.photos/200"
                  }
                }
              ]
            }
          ]
        }
      },
      "object_data": {
        "createChildObject": true,
        "SubStreamId": 0,
        "StatusId": 1,
        "ManagerId": 78121,
        "Content": {},
        "User": {
          "UniqueId": "01234567",
          "LastName": "Doe",
          "FirstName": "John",
          "Phone1": "97253720000",
          "Email": "John.Doe@gmail.com",
          "Remarks": "some remark for user"
        }
      }
    }
  ]
}

Send a template with an attachment (image) ID + Object data

{
  "data": [
    {
      "template_data": {
        "to": "19172537000",
        "template": {
          "name": "image1",
          "language": {
            "code": "en"
          },
          "components": [
            {
              "type": "header",
              "parameters": [
                {
                  "type": "image",
                  "image": {
                    "id": "614927520593182"
                  }
                }
              ]
            },
            {
              "type": "body",
              "parameters": [
                {
                  "type": "text",
                  "text": "JPG"
                }
              ]
            }
          ]
        }
      },
      "object_data": {
        "createChildObject": true,
        "SubStreamId": 0,
        "StatusId": 13,
        "ManagerId": 78121,
        "Content": {},
        "User": {
          "UniqueId": "01234567",
          "LastName": "Doe",
          "FirstName": "John",
          "Phone1": "97253720000",
          "Email": "john.doe@gmail.com",
          "Remarks": "some remark for user"
        }
      }
    }
  ]
}

Send a template with an attachment (doc)

{
  "data": [
    {
      "template_data": {
        "to": "972537280999",
        "template": {
          "name": "doc1",
          "language": {
            "code": "en"
          },
          "components": [
            {
              "type": "header",
              "parameters": [
                {
                  "type": "document",
                  "document": {
                    "link": "https://denverzoo.org/wp-content/uploads/2018/09/African-lion.pdf",
                    "filename": "African-lion.pdf"
                  }
                }
              ]
            },
            {
              "type": "body",
              "parameters": [
                {
                  "type": "text",
                  "text": "hello"
                }
              ]
            }
          ]
        }
      }
    }
  ]
}

Send a template with an attachment (doc) + Object data

{
  "data": [
    {
      "template_data": {
        "to": "972537280000",
        "template": {
          "name": "doc1",
          "language": {
            "code": "en"
          },
          "components": [
            {
              "type": "header",
              "parameters": [
                {
                  "type": "document",
                  "document": {
                    "link": "https://denverzoo.org/wp-content/uploads/2018/09/African-lion.pdf",
                    "filename": "African-lion.pdf"
                  }
                }
              ]
            },
            {
              "type": "body",
              "parameters": [
                {
                  "type": "text",
                  "text": "hello"
                }
              ]
            }
          ]
        }
      },
      "object_data": {
        "createChildObject": true,
        "SubStreamId": 0,
        "StatusId": 1,
        "ManagerId": 78121,
        "Content": {},
        "User": {
          "UniqueId": "01234567",
          "LastName": "Doe",
          "FirstName": "Ron",
          "Phone1": "19172537000",
          "Email": "john.doe@gmail.com",
          "Remarks": "some remark for user"
        }
      }
    }
  ]
}

Send a template with an attachment (doc) ID + Object data

{
  "data": [
    {
      "template_data": {
        "to": "972537280000",
        "template": {
          "name": "header_doc",
          "language": {
            "code": "en"
          },
          "components": [
            {
              "type": "header",
              "parameters": [
                {
                  "type": "document",
                  "document": {
                    "id": "550197337025434",
                    "filename": "file-sample_150kB.pdf"
                  }
                }
              ]
            },
            {
              "type": "body",
              "parameters": [
                {
                  "type": "text",
                  "text": "PDF"
                }
              ]
            }
          ]
        }
      },
      "object_data": {
        "createChildObject": true,
        "SubStreamId": 0,
        "StatusId": 13,
        "ManagerId": 78121,
        "Content": {},
        "User": {
          "UniqueId": "01234567",
          "LastName": "Doe",
          "FirstName": "John",
          "Phone1": "97253720000",
          "Email": "John.Doe@gmail.com",
          "Remarks": "Just checking"
        }
      }
    }
  ]
}

Send a template with an attachment (video)

{
  "data": [
    {
      "template_data": {
        "to": "19172537000",
        "template": {
          "name": "header_video",
          "language": {
            "code": "en"
          },
          "components": [
            {
              "type": "header",
              "parameters": [
                {
                  "type": "video",
                  "video": {
                    "link": "http://techslides.com/demos/sample-videos/small.mp4"
                  }
                }
              ]
            },
            {
              "type": "body",
              "parameters": [
                {
                  "type": "text",
                  "text": "hello"
                }
              ]
            }
          ]
        }
      }
    }
  ]
}

Send a template with an attachment (video) + Object data

{
  "data": [
    {
      "template_data": {
        "to": "19172537000",
        "template": {
          "name": "header_video",
          "language": {
            "code": "en"
          },
          "components": [
            {
              "type": "header",
              "parameters": [
                {
                  "type": "video",
                  "video": {
                    "link": "http://techslides.com/demos/sample-videos/small.mp4"
                  }
                }
              ]
            },
            {
              "type": "body",
              "parameters": [
                {
                  "type": "text",
                  "text": "hello"
                }
              ]
            }
          ]
        }
      },
      "object_data": {
        "createChildObject": true,
        "SubStreamId": 0,
        "StatusId": 1,
        "ManagerId": 78121,
        "Content": {},
        "User": {
          "UniqueId": "01234567",
          "LastName": "Doe",
          "FirstName": "Ron",
          "Phone1": "972537280000",
          "Email": "Ron.Doe@gmail.com",
          "Remarks": "Sending video files is great"
        }
      }
    }
  ]
}

Send a template with an attachment (video) ID + Object data

{
  "data": [
    {
      "template_data": {
        "to": "972537280000",
        "template": {
          "name": "header_video",
          "language": {
            "code": "en"
          },
          "components": [
            {
              "type": "header",
              "parameters": [
                {
                  "type": "video",
                  "video": {
                    "id": "27f8b007-7750-418e-9852-b4f8b7f95b9f"
                  }
                }
              ]
            },
            {
              "type": "body",
              "parameters": [
                {
                  "type": "text",
                  "text": "Video_20221023_111733_014.mp4"
                }
              ]
            }
          ]
        }
      },
      "object_data": {
        "createChildObject": true,
        "SubStreamId": 0,
        "StatusId": 13,
        "ManagerId": 78121,
        "Content": {},
        "User": {
          "UniqueId": "01234567",
          "LastName": "Lin",
          "FirstName": "Robert",
          "Phone1": "972537280000",
          "Email": "Lin.R34@gmail.com",
          "Remarks": "Deal of the day"
        }
      }
    }
  ]
}

Send a Call-to-Action template with 'Call a phone number' button

{
  "data": [
    {
      "template_data": {
        "to": "972537280000",
        "template": {
          "name": "Call_a_phone_num_btn",
          "language": {
            "code": "en"
          },
          "components": []
        }
      }
    }
  ]
}

Send a Call-to-Action template with 'Call a phone number' button + Object data

{
  "data": [
    {
      "template_data": {
        "to": "972537280000",
        "template": {
          "name": "Call_a_phone_num_btn",
          "language": {
            "code": "en"
          },
          "components": []
        }
      },
      "object_data": {
        "createChildObject": true,
        "SubStreamId": 0,
        "StatusId": 1,
        "ManagerId": 78121,
        "Content": {},
        "User": {
          "UniqueId": "01234567",
          "LastName": "Doe",
          "FirstName": "John",
          "Phone1": "9725372800000",
          "Email": "John.Doe@gmail.com",
          "Remarks": "Contatcts buttons are great"
        }
      }
    }
  ]
}

Send a Call-to-Action template with 'Call a phone number' + 'Visit a website' buttons

{
  "data": [
    {
      "template_data": {
        "to": "972537280000",
        "template": {
          "name": "Call_and_Visit_a_Website_btns",
          "language": {
            "code": "en"
          },
          "components": []
        }
      }
    }
  ]
}

Send a Call-to-Action template with 'Call a phone number' + 'Visit a website' buttons + Object data

{
  "data": [
    {
      "template_data": {
        "to": "972537280000",
        "template": {
          "name": "Call_and_Visit_a_Website_btns",
          "language": {
            "code": "en"
          },
          "components": []
        }
      },
      "object_data": {
        "createChildObject": true,
        "SubStreamId": 0,
        "StatusId": 1,
        "ManagerId": 78121,
        "Content": {},
        "User": {
          "UniqueId": "01234567",
          "LastName": "Doe",
          "FirstName": "John",
          "Phone1": "9725372800000",
          "Email": "John.Doe@gmail.com",
          "Remarks": "Contatcts buttons are great"
        }
      }
    }
  ]
}

Send a Call-to-Action template with a Static URL button

{
  "data": [
    {
      "template_data": {
        "to": "972537280000",
        "template": {
          "name": "static_url",
          "language": {
            "code": "en"
          },
          "components": [
            {
              "type": "body",
              "parameters": [
                {
                  "type": "text",
                  "text": "Name"
                }
              ]
            }
          ]
        }
      }
    }
  ]
}

Send a Call-to-Action template with a Static URL button + Object data

{
  "data": [
    {
      "template_data": {
        "to": "19172537000",
        "template": {
          "name": "static_url",
          "language": {
            "code": "en"
          },
          "components": [
            {
              "type": "body",
              "parameters": [
                {
                  "type": "text",
                  "text": "Name"
                }
              ]
            }
          ]
        },
        "object_data": {
          "createChildObject": true,
          "SubStreamId": 0,
          "StatusId": 1,
          "ManagerId": 78121,
          "Content": {},
          "User": {
            "UniqueId": "01234567",
            "LastName": "Fox",
            "FirstName": "Johnny",
            "Phone1": "9725372800000",
            "Email": "john.fox53@gmail.com",
            "Remarks": "Static URL is great"
          }
        }
      }
    }
  ]
}

Send a Call-to-Action template with a Dynamic URL button

{
  "data": [
    {
      "template_data": {
        "to": "972537280000",
        "template": {
          "name": "dynamic_url",
          "language": {
            "code": "en"
          },
          "components": [
            {
              "type": "button",
              "sub_type": "url",
              "index": 0,
              "parameters": [
                {
                  "type": "text",
                  "text": "api"
                }
              ]
            },
            {
              "type": "body",
              "parameters": [
                {
                  "type": "text",
                  "text": "name"
                }
              ]
            }
          ]
        }
      }
    }
  ]
}

Send a Call-to-Action template with a Dynamic URL button + Object data

{
  "data": [
    {
      "template_data": {
        "to": "19172537000",
        "template": {
          "name": "url_dyn",
          "language": {
            "code": "en"
          },
          "components": [
            {
              "type": "button",
              "sub_type": "url",
              "index": 0,
              "parameters": [
                {
                  "type": "text",
                  "text": "api"
                }
              ]
            },
            {
              "type": "body",
              "parameters": [
                {
                  "type": "text",
                  "text": "name"
                }
              ]
            }
          ]
        },
        "object_data": {
          "createChildObject": true,
          "SubStreamId": 0,
          "StatusId": 1,
          "ManagerId": 78121,
          "Content": {},
          "User": {
            "UniqueId": "01234567",
            "LastName": "Fox",
            "FirstName": "Johnny",
            "Phone1": "9725372800000",
            "Email": "john.fox53@gmail.com",
            "Remarks": "Dynamic URL is great"
          }
        }
      }
    }
  ]
}

Send a Quick Reply template with 3 buttons

{
  "data": [
    {
      "template_data": {
        "to": "972537280000",
        "template": {
          "name": "3 buttons",
          "language": {
            "code": "en"
          },
          "components": [
            {
              "type": "body",
              "parameters": [
                {
                  "type": "text",
                  "text": "name"
                }
              ]
            }
          ]
        }
      }
    }
  ]
}

Send a Quick Reply template with 3 buttons + Object data

{
  "data": [
    {
      "template_data": {
        "to": "972537280000",
        "template": {
          "name": "3 buttons",
          "language": {
            "code": "en"
          },
          "components": [
            {
              "type": "body",
              "parameters": [
                {
                  "type": "text",
                  "text": "name"
                }
              ]
            }
          ]
        },
        "object_data": {
          "createChildObject": true,
          "SubStreamId": 0,
          "StatusId": 1,
          "ManagerId": 78121,
          "Content": {},
          "User": {
            "UniqueId": "01234567",
            "LastName": "Doe",
            "FirstName": "John",
            "Phone1": "9725372800000",
            "Email": "John.Doe@gmail.com",
            "Remarks": "Quick Reply with 3 Buttons is great"
          }
        }
      }
    }
  ]
}

Send an authentication template

{
  "data": [
    {
      "template_data": {
        "to": "972537280000",
        "template": {
          "name": "auth_template",
          "language": {
            "code": "en"
          },
          "components": [
            {
              "type": "button",
              "sub_type": "url",
              "index": 0,
              "parameters": [
                {
                  "type": "text",
                  "text": "name"
                }
              ]
            },
            {
              "type": "body",
              "parameters": [
                {
                  "type": "text",
                  "text": "name"
                }
              ]
            }
          ]
        }
      }
    }
  ]
}

Send an authentication template + Object data

{
  "data": [
    {
      "template_data": {
        "to": "972537280000",
        "template": {
          "name": "auth_template",
          "language": {
            "code": "en"
          },
          "components": [
            {
              "type": "button",
              "sub_type": "url",
              "index": 0,
              "parameters": [
                {
                  "type": "text",
                  "text": "COPY"
                }
              ]
            },
            {
              "type": "body",
              "parameters": [
                {
                  "type": "text",
                  "text": "455455"
                }
              ]
            }
          ]
        }
      },
      "object_data": {
        "createChildObject": true,
        "SubStreamId": 0,
        "StatusId": 1,
        "ManagerId": 387123,
        "Content": {},
        "User": {
          "UniqueId": "01234567",
          "LastName": "Fox",
          "FirstName": "David",
          "Phone1": "9725372800000",
          "Email": "david.fox53@gmail.com",
          "Remarks": "Looking for a new device"
        }
      }
    }
  ]
}

Expand All

object

schedule

string

(Optional) Enter a Unix timestamp code for the desired scheduled date. Leaving it empty will send the template immediately.

integer

The recipient's phone number in international format

template

object

Template configuration

name

string

Name of the approved WhatsApp template

language

object

Specifies the language of the template

code

string

Language code used by Meta. For example 'en_us'

componentsA

object

Components may include the body, header, footer, and buttons of the template

type

string

The type of component. In this example 'body'

parameters

object

Represents a single parameter for the placeholder

type

string

The type of parameter. WhatsApp supports "text", "image", “video”, and "document" parameters.

text

string

the text entered in the parameter for example "John"

componentsB

object

Components may include the body, header, footer, and buttons of the template

type

string

The type of component. In this example 'header'

parametersA

object

Represents a single parameter for the placeholder

type

string

The type of parameter (e.g. image). WhatsApp supports "text", "image", “video”, and "document" parameters.

image

object

Link

string

The URL for the image attachment (e.g. https://picsum.photos/200).

string

Instead of the link, enter media id provided by META when using the Whatsapp_uploadMedia API (e.g. 1628862997611773)

parametersB

object

Represents a single parameter for the placeholder

type

string

The type of parameter. WhatsApp supports "text", "image", “video”, and "document" parameters.

video

object

Link

string

The URL for the video attachment (e.g http://example.com/video.mp4).

parametersC

object

Represents a single parameter for the placeholder

type

string

The type of parameter. WhatsApp supports "text", "image", “video”, and "document" parameters.

document

object

Link

string

The URL of the PDF attachment (e.g. https://denverzoo.org/wp-content/uploads/2018/09/African-lion.pdf).

filename

string

The file's name (e.g. African-lion.pdf)

object_data

object

createChildObject

boolean Required

Exampletrue

streamId

integer Required

The channel's ID

SubStreamId

integer Required

The subchannel's ID. When there are no subchannels, value is 0

Example0

StatusId

integer Required

Status of conversation - see Enums

Example1

ManagerId

integer Required

ID of the agent

Example78121

Content

object Required

Content of the message

User

object Required

UniqueId

string

Unique identifier of the customer such as Social Security number or national ID, or a unique ID generated by the organization

Example01234567

LastName

string

ExampleDoe

FirstName

string

ExampleJohn

Phone1

string Required

Phone number including country code

Example442079834000

string (email) Required

ExampleJohn.D@gmail.com

Remarks

string

ExampleReturning customer

Responses

200

Operation successful

Expand All

object

status

string

Example200

description

string

ExampleOperation successful

response_time

string

Example2024-08-06T07:51:52.2581942Z

data

Array of object

object

recipient

string

Recipient number

Example972546663529

string

ExamplegBEGlyVGZjUpAgmyuqAHfxbHmnQ

status

integer (int32)

Example200

object_id

integer (int64)

Object ID. This is a commbox generated number (optional)

Example38383744

206

Provider returned failure

Expand All

object

status

string

Example206

description

string

ExampleMissing template parameter

response_time

string

Example2024-08-06T07:51:52.2581942Z

data

Array

OneOf

object

recipient

string

Recipient number

Example972546663529

string

ExamplegBEGlyVGZjUpAgmyuqAHfxbHmnQ

status

integer (int32)

Example200

object_id

integer (int64)

Object ID. This is a commbox generated number (optional)

Example38383744

object

recipient

string

Recipient number

Example972546663529

status

integer (int32)

Example400

failed

object

Exampleinvalid — Not a valid WhatsApp user

400

Provider returned failure

Expand All

object

status

string

Example400

description

string

ExampleMissing parameter template_name

response_time

string

Example2024-08-06T07:51:52.2581942Z

data

Array

OneOf

object

recipient

string

Recipient number

Example972546663529

status

integer (int32)

Example400

failed

object

Exampleinvalid — Not a valid WhatsApp user

401

Unauthorized - The supplied credentials, if any, are not sufficient to access the resource

404

Not found - The requested resource is not found

429

Too Many Requests - Too many requests have been made in a short period of time (Throttling)

500

Server Error - The server could not return the representation due to an internal server error

501

Not Implemented - The requested operation is not supported

Was this article helpful?