Logo
Home Submit Request Login

Creating WhatsApp Broadcast Message Templates via API

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:

mceclip1.png

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:

mceclip2.png

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:

mceclip3.png

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:

mceclip4.png

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:

mceclip5.png

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:

mceclip8.png

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:

mceclip7.png

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:

mceclip9.png

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:

Screenshot_20230529_170611_Chrome.jpg

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
      }
    ]
}'

Need further assistance?

Our helpful customer support team is available to help you with any inquiries you may have

Contact Us