Creating WhatsApp Broadcast Message Templates via API

  • Updated

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!\n\nPlease 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 :)\n\nTerima 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/ramo-29lun8b1ulepsaio/image/upload/PIOjGPkBGX/Qiscus-logo-(1).jpg",
            "footer": null,
            "header_sample": "https://dnlbo7fgjcc7f.cloudfront.net/ramo-29lun8b1ulepsaio/image/upload/PIOjGPkBGX/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/ramo-29lun8b1ulepsaio/image/upload/PIOjGPkBGX/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/ramo-29lun8b1ulepsaio/video/upload/3H0Ol2CmdR/324804406_587771213418150_4554692429922815692_n.mp4",
            "footer": null,
            "header_sample": "https://dnlbo7fgjcc7f.cloudfront.net/ramo-29lun8b1ulepsaio/video/upload/3H0Ol2CmdR/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/ramo-29lun8b1ulepsaio/video/upload/3H0Ol2CmdR/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/ramo-29lun8b1ulepsaio/docs/upload/BGlL6sykTo/363489922_670463838453720_4305949552448801085_n.pdf",
            "footer": "#EnablingConversations",
            "header_sample": "https://dnlbo7fgjcc7f.cloudfront.net/ramo-29lun8b1ulepsaio/docs/upload/BGlL6sykTo/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/ramo-29lun8b1ulepsaio/docs/upload/BGlL6sykTo/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!\n\nPlease 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!\n\nMohon balas pesan ini",
        "language": "id",
        "footer": null,
        "body_sample": null,
        "buttons": null
      }
    ]
}'

Was this article helpful?

Comments

0 comments

Please sign in to leave a comment.