Creating WhatsApp Broadcast Message Templates via API

November 26, 2024

Before sending a WhatsApp Broadcast, you must have a message template. This FAQ will guide you through template submission using API. You can use API requests to streamline the process and integrate it into your existing workflow or applications.

Before we start, here are what you need:

Read the API documentation here
Qiscus App ID and Qiscus Secret Key (get from Omnichannel dashboard > Settings > App Information)
Channel ID, Template Name, Category, and Language
Ensure the components that you will be submitted in the template. The template can handle these components:
- Header (optional):
  - Text with 1 variable
  - Media (Image/Video/Document) variable
- Body:
  - Text with up to 15 variable
- Footer (optional):
  - Text
- Buttons (optional):
  - Call To Action
    - Call Phone Number
    - Visit Website
      - Static
      - Dynamic with 1 variable
  - Quick Reply
    - Up to 3 text buttons
- Code Delivery (only for Authentication category)
  - Copy Code
  - Auto-Fill
Additional notes
- The maximum template content including variables:
  - Header 60 characters
  - Body 1024 characters

Payload Options

Request Body

fields	type	required	description
category	string	true	There are 3 categories in META as of June 1, 2023: 1. AUTHENTICATION 2. MARKETING 3. UTILITY
channel_id	integer	true	wa channel id
have_template	boolean	false	if set to true you must fill `namespace` params
name	string	false	template name
namespace	string	true, if have template	wa namespace to test
hsm_details	array	array of `hsm_detail` object	Contains information about the content details of the WhatsApp template

hsm_details object

fields	type	required	description
language	string	true	WhatsApp template language
content	string	true	content / body of wa message template
header_type	string	false	accepted_values: `text, image, document, video`
header_content	string	false	wa message template header content
header_default_value	string	true if header_type is `image` or `document` or `video`	wa message template header content
buttons	array	array of `button` object	Contains button information
footer	string	false	Text for footer
header_sample	array	true	Sample of variable value in the header
body_sample	array	true	Sample of variable value in the body

buttons object

fields	type	required	description
type	string	true	Values: PHONE_NUMBER, URL, and QUICK_REPLY
text	string	true	The text to be displayed on the button
url	string	false	The URL that will be visited on clicking the button. Variables can be used to create dynamic links
phone_number	string	false	The phone number that will be called on clicking the button
example	array	true	Provides an example of possible data for your template This helps us during the review and approval process, so we can understand what kind of message you plan to send. Make sure these are examples and do not include any confidential or personal information

hsm_details object (AUTHENTICATION)

fields	type	required	description
add_security_recommendation	boolean	false	Optional. You can include a security recommendation in the template or not
language	string	true	WhatsApp template language
code_expiration_minutes	string	false	Optional. You can add code expiration in the template or not
button_type	string	true	The button type must be "OTP"

1. Body only, no variable

This example uses a simple template that only has content in the body section, without headers, buttons, or variables. Below is the API request.

Example template:

Request:

curl --location 'https://omnichannel.qiscus.com/api/v3/admin/hsm/create' 
--header 'Qiscus-App-Id: {{app_id}}' 
--header 'Qiscus-Secret-Key: {{secret_key}}' 
--header 'Content-Type: application/json' 
--data '{
   "have_template": false,
   "name": "test",
   "category": "UTILITY",
   "channel_id": {{channel_id}},
   "namespace": null,
   "hsm_details": [
      {
        "header_type": null,
        "header_content": null,
        "header_default_value": null,
        "content": "Hello there!nnPlease reply this message to get a follow up",
        "language": "en",
        "footer": null,
        "body_sample": null,
        "buttons": null
      }
    ]
}'

Note: The language code will be different for each language. Please refer here to see the codes.

2. Body with multiple text variables

The body is possible to handle up to 15 text variables.

Example template:

Request:

curl --location 'https://omnichannel.qiscus.com/api/v3/admin/hsm/create' 
--header 'Qiscus-App-Id: {{app_id}}' 
--header 'Qiscus-Secret-Key: {{secret_key}}' 
--header 'Content-Type: application/json' 
--data '{
   "have_template": false,
   "name": "test",
   "category": "MARKETING",
   "channel_id": {{channel_id}},
   "namespace": null,
   "hsm_details": [
      {
        "header_type": null,
        "header_content": null,
        "header_default_value": null,
        "content": "Halo {{1}},nKami ingin menginformasikan bahwa {{2}} mendapatkan akses free trial WhatsApp Business API dan Qiscus Multichannel selama 90 hari. Silahkan balas pesan ini untuk informasi lebih lanjut :)nnTerima kasih",         "language": "id",
        "footer": null,
        "body_sample": [
            "Alena",
            "Alena"
        ],
        "buttons": null
      }
    ]
}'

3. Header with a text variable

Unlike the body section, the header only can contain 1 text variable.

Example template:

Request:

curl --location 'https://omnichannel.qiscus.com/api/v3/admin/hsm/create' 
--header 'Qiscus-App-Id: {{app_id}}' 
--header 'Qiscus-Secret-Key: {{secret_key}}' 
--header 'Content-Type: application/json' 
--data '{
   "have_template": false,
   "name": "test",
   "category": "UTILITY",
   "channel_id": {{channel_id}},
   "namespace": null,
   "hsm_details": [
      {
        "header_type": "text",
        "header_content": "Hi {{1}}, semoga sehat selalu",
        "header_default_value": "var_1",
        "content": "Melalui pesan ini kami mengingatkan anda untuk selalu minum air putih minimal {{1}} gelas 230ml perhari atau {{2}} liter per hari",         "language": "id",
        "footer": null,
        "header_sample": [
            "Alena"
        ],
        "body_sample": [
            "1",
            "2"
        ],
        "buttons": null
      }
    ]
}'

4. Header with an image variable

Example template:

Request:

curl --location 'https://omnichannel.qiscus.com/api/v3/admin/hsm/create' 
--header 'Qiscus-App-Id: {{app_id}}' 
--header 'Qiscus-Secret-Key: {{secret_key}}' 
--header 'Content-Type: application/json' 
--data '{
    "have_template": false,
    "name": "test",
    "category": "MARKETING",
    "channel_id": {{channel_id}},
    "namespace": null,
    "hsm_details": [
        {
            "content": "Hallo {{1}},nSelamat bergabung bersama kami.",
            "language": "id",
            "header_type": "image",
            "header_default_value": "https://dnlbo7fgjcc7f.cloudfront.net/qiscuscs-5xm3wgs5fc1p/image/upload/e3TJWa_OVi/Qiscus-logo-(1).jpg",
            "footer": null,
            "header_sample": "https://dnlbo7fgjcc7f.cloudfront.net/qiscuscs-5xm3wgs5fc1p/image/upload/e3TJWa_OVi/Qiscus-logo-(1).jpg",
            "body_sample": [
                "Alena"
            ],
            "buttons": null
        }
    ]
}'

Note: The image URL must be direct, not shortened URL.
(e.g. https://dnlbo7fgjcc7f.cloudfront.net/qiscuscs-5xm3wgs5fc1p/image/upload/e3TJWa_OVi/Qiscus-logo-(1).jpg)

5. Header with a video variable

Example template:

Request:

curl --location 'https://omnichannel.qiscus.com/api/v3/admin/hsm/create' 
--header 'Qiscus-App-Id: {{app_id}}' 
--header 'Qiscus-Secret-Key: {{secret_key}}' 
--header 'Content-Type: application/json' 
--data '{
    "have_template": false,
    "name": "test",
    "category": "MARKETING",
    "channel_id": {{channel_id}},
    "namespace": null,
    "hsm_details": [
        {
            "content": "Hai {{1}}. Berikut kami kirimkan video penjelasan mengenai Qiscus Multichannel Chat. Apabila masih ada yang perlu ditanyakan, silahkan balas chat ini. Terima kasih",
            "language": "id",
            "header_type": "video",
            "header_default_value": "https://dnlbo7fgjcc7f.cloudfront.net/qiscuscs-5xm3wgs5fc1p/video/upload/L2OfN2Ak5N/324804406_587771213418150_4554692429922815692_n.mp4",
            "footer": null,
            "header_sample": "https://dnlbo7fgjcc7f.cloudfront.net/qiscuscs-5xm3wgs5fc1p/video/upload/L2OfN2Ak5N/324804406_587771213418150_4554692429922815692_n.mp4",
            "body_sample": [
                "Alena"
            ],
            "buttons": null
        }
    ]
}'

Note: The video URL must be direct, not shortened URL.

(e.g. https://dnlbo7fgjcc7f.cloudfront.net/qiscuscs-5xm3wgs5fc1p/video/upload/L2OfN2Ak5N/324804406_587771213418150_4554692429922815692_n.mp4)

6. Header with a document variable

Example template:

Request:

curl --location 'https://omnichannel.qiscus.com/api/v3/admin/hsm/create' 
--header 'Qiscus-App-Id: {{app_id}}' 
--header 'Qiscus-Secret-Key: {{secret_key}}' 
--header 'Content-Type: application/json' 
--data '{
    "have_template": false,
    "name": "test",
    "category": "MARKETING",
    "channel_id": {{channel_id}},
    "namespace": null,
    "hsm_details": [
        {
            "content": "Hai {{1}}nUntuk maklumat lanjut sila semak e-mel anda",
            "language": "ms",
            "header_type": "document",
            "header_default_value": "https://dnlbo7fgjcc7f.cloudfront.net/qiscuscs-5xm3wgs5fc1p/docs/upload/e7k3NazGPb/363489922_670463838453720_4305949552448801085_n.pdf",
            "footer": "#EnablingConversations",
            "header_sample": "https://dnlbo7fgjcc7f.cloudfront.net/qiscuscs-5xm3wgs5fc1p/docs/upload/e7k3NazGPb/363489922_670463838453720_4305949552448801085_n.pdf",
            "body_sample": [
                "Alena"
            ],
            "buttons": null
        }
    ]
}'

Note: The document URL must be direct, not shortened URL.

(e.g. https://dnlbo7fgjcc7f.cloudfront.net/qiscuscs-5xm3wgs5fc1p/docs/upload/e7k3NazGPb/363489922_670463838453720_4305949552448801085_n.pdf)

7. Button - Call To Action

If you're using Call To Action button, there are 3 options of action type when creating the template:

Call phone number
Visit website (static URL)
Visit website (dynamic URL): only add a custom suffix of the URL

You can only have 2 Call To Action Buttons (Call phone number & Visit website static/dynamic).

Example template:

Request:

curl --location 'https://omnichannel.qiscus.com/api/v3/admin/hsm/create' 
--header 'Qiscus-App-Id: {{app_id}}' 
--header 'Qiscus-Secret-Key: {{secret_key}}' 
--header 'Content-Type: application/json' 
--data '{
    "have_template": false,
    "name": "test",
    "category": "UTILITY",
    "channel_id": {{channel_id}},
    "namespace": null,
    "hsm_details": [
        {
            "content": "Halo, Kami sudah menyelesaikan keluhan Anda terkait {{1}}.nJika Anda masih punya pertanyaan silakan kirim chat lagi.",
            "language": "id",
            "header_type": "text",
            "header_content": "Yth. {{1}}",
            "header_default_value": "var_1",
            "footer": "Qiscus Support Team",
            "header_sample": "var_1",
            "body_sample": [
                "Issue"
            ],
            "buttons": [ 
              {
               "type": "PHONE_NUMBER",
               "text": "Call CS",
               "phone_number": "+6285641706678"
             },
             { 
               "type": "URL", 
               "text": "Our Whitepaper", 
               "url": "https://www.qiscus.com/{{1}}", 
               "example": [ 
                   "https://www.qiscus.com/whitepaper" 
               ] 
              } 
            ]
        }
    ]
}'

For Visit website (static URL), you can use button type URL and remove example.

{ 
        "type": "URL", 
        "text": "Our Whitepaper", 
        "url": "https://www.qiscus.com/", 
        "example": null
}

8. Button - Quick Reply

The template can contain max 3 Quick Reply buttons.

Example template:

Request:

curl --location 'https://omnichannel.qiscus.com/api/v3/admin/hsm/create' 
--header 'Qiscus-App-Id: {{app_id}}' 
--header 'Qiscus-Secret-Key: {{secret_key}}' 
--header 'Content-Type: application/json' 
--data '{
    "have_template": false,
    "name": "test",
    "category": "MARKETING",
    "channel_id": {{channel_id}},
    "namespace": null,
    "hsm_details": [
        {
            "content": "Hello, we are handling your complain related to {{1}}.nIf you have any other problem let us know.",
            "language": "en",
            "header_type": "text",
            "header_content": "Mr/Mrs {{1}},",
            "header_default_value": "var_1",
            "footer": "Qiscus Support Team",
            "header_sample": "var_1",
            "body_sample": [
                "Issue"
            ],
            "buttons": [
              {
                 "text": "All Okay",
                 "type": "QUICK_REPLY"
              },
              {
                 "text": "More questions",
                 "type": "QUICK_REPLY"
              }
           ]
        }
    ]
}'

9. Code Delivery - Copy Code (OTP)

Example template:

Request:

curl --location 'https://omnichannel.qiscus.com/api/v3/admin/hsm/create' 
--header 'Qiscus-App-Id: {{app_id}}' 
--header 'Qiscus-Secret-Key: {{secret_key}}' 
--header 'Content-Type: application/json' 
--data '{
    "have_template": false,
    "name": "test",
    "category": "AUTHENTICATION",
    "channel_id": {{channel_id}},
    "namespace": null,
    "hsm_details": [
        {
            "content": {
                "add_security_recommendation": true
             },
            "language": "en",
            "header_type": null,
            "header_content": null,
            "header_default_value": null,
            "footer": {
                "code_expiration_minutes": "10"
             },
            "header_sample": null,
            "body_sample": null,
            "buttons": [
              {
                 "type": "OTP",
                 "otp_type": "COPY_CODE",
                 "text": "Copy code"
              }
           ]
        }
    ]
}'

Multiple Language

For submitting more than 1 language in a template, you can add more hsm_details object

curl --location 'https://omnichannel.qiscus.com/api/v3/admin/hsm/create' 
--header 'Qiscus-App-Id: {{app_id}}' 
--header 'Qiscus-Secret-Key: {{secret_key}}' 
--header 'Content-Type: application/json' 
--data '{
   "have_template": false,
   "name": "test",
   "category": "UTILITY",
   "channel_id": {{channel_id}},
   "namespace": null,
   "hsm_details": [
      {
        "header_type": null,
        "header_content": null,
        "header_default_value": null,
        "content": "Hello there!nnPlease reply this message to get a follow up",
        "language": "en",
        "footer": null,
        "body_sample": null,
        "buttons": null
      },
      {
        "header_type": null,
        "header_content": null,
        "header_default_value": null,
        "content": "Halo!nnMohon balas pesan ini",
        "language": "id",
        "footer": null,
        "body_sample": null,
        "buttons": null
      }
    ]
}'

Before we start, here are what you need:

Payload Options

1. Body only, no variable

2. Body with multiple text variables

3. Header with a text variable

4. Header with an image variable

5. Header with a video variable

6. Header with a document variable

7. Button - Call To Action

8. Button - Quick Reply

9. Code Delivery - Copy Code (OTP)

Multiple Language

Need further assistance?