WhatsApp Business API

This document will show more flexible functionalities regarding Qiscus WhatsApp Business API that chatbot normally want. By using these APIs, you will be able to use more type of messages and control it from your own system. Sessions messages, Template Messages, as well as Interactive messages are supported in this documentations. There is also webhooks settings to enable you receiving more messages and events from WhatsApp (messages and status receipt).

Please note that the recipient should opt-in to receive WhatsApp message in order to avoid block for your number.

Use case for this API :

OTP verification during login/signup to your app
Tracking order in your app
Event notifications or Alerting for any event in your system to the customer.

Before You Start

To begin to use the Qiscus WhatsApp Business API you need to have a Qiscus Omnichannel Chat account. You can easily get a Qiscus Omnichannel Chat account by register to this page.

Important Notes

Setting the webhook correctly in order to get any information from WhatsApp. For example there's a case the messages aren't delivered to customer this can be because of 24 hour and others factor might happens.
Make sure that you still have enough credit or free sessions to sends the template message. If your credit has run out then you cannot proceed a conversation. You can use our new feature Self Top Up or contact us to top up your credit.
Need WABA (WhatsApp Business Account) ID to create template

Get Started

A simple step for send message via WhatsApp Business API that you can follow i.e login, set up webhooks, post a text message, and get webhooks.

Authentication

First, you need to know App ID and Qiscus Secret Key to do authentication in Qiscus Omnichannel Chat. Please follow this page to get your App ID and Qiscus Secret Key.

Settings the Webhooks

When a customer sends you a message, the WhatsApp Business API client will send an HTTP POST request notification to your webhook URL. You need to setup the webhook URL in order to get webhooks from WhatsApp Business API. This webhooks will give you events:

New messages from WhatsApp users
Information whether your message is failed or success when you send a message
Any errors from WhatsApp
Message status (sent, delivered, read)

See Errors and Status Messages for more information on any errors you receive.

Your Server is a system server that you will be integrated with WhatsApp Business API.

URL:

HTTP
    
 
[POST] https://omnichannel.qiscus.com/whatsapp/{{APP-ID}}/{{channel-id}}/settings
Copy

Please follow this page to get your App ID, Qiscus Secret Key and channel-id.

Header:

HTTP
    
 
Qiscus-App-Id : {{APP-ID}}Qiscus-Secret-Key : {{Secret Key}}content-type : application/json
Copy

Body:

HTTP
    
 
{    "webhooks": {        "url": "YOUR_DOMAIN_URL.com/receive_webhooks"    }}
Copy

Fill the url field with your webhook URL

Example:

CURL
    
 
curl -X POST \  https://omnichannel.qiscus.com/whatsapp/***/***/settings \  -H 'Qiscus-App-Id: ***' \  -H 'Qiscus-Secret-Key: ***' \  -H 'Content-Type: application/json' \  -d '{    "webhooks": {        "url": "YOUR_DOMAIN_URL.com/receive_webhooks"    }}'
Copy

Example Response:

On Cloud
On Premise
    
 
{    "business_id": "***",    "status": 200,    "webhooks": {        "url": "YOUR_DOMAIN_URL.com/receive_webhooks"    }}
Copy

You can see the webhook payload from WhatsApp by following the docs:

Webhook inbound message: https://developers.facebook.com/docs/whatsapp/api/webhooks/inbound#fields
Webhook notification: https://developers.facebook.com/docs/whatsapp/api/webhooks/inbound#receiving
Webhook media message: https://developers.facebook.com/docs/whatsapp/api/webhooks/inbound#mediawebhook
Webhook replies to sent message: https://developers.facebook.com/docs/whatsapp/api/webhooks/inbound#context

Type Of Message

There are several types of post messages:

Session Message

You can start to chat with your own number as a customer.

Please refer to this documentations as well to understand the possibility of the payload :

When your customers sends a message, WhatsApp API will hook a message to Qiscus Omnichannel Chat Server.
Qiscus Omnichannel Chat Server forwards message to your webhook.
If you want to reply to that message, please follow the next process. If not, stop right there.
WhatsApp has to validate your reply. If your last customer message is more than 24 hours, your reply can not be sent. You must use an approved template if you want to send a message after 24 hours of the last customer's message.
If your last customer message is less than 24 hours, your customer gets the reply.
We notify you a response of the reply to your webhook.

URL:

HTTP
    
 
[POST] https://omnichannel.qiscus.com/whatsapp/v1/{{APP-ID}/{{channel-id}}/messages
Copy

Please follow this page to get your App ID, Qiscus Secret Key and channel-id.

Header:

HTTP
    
 
Qiscus-App-Id : {{APP-ID}}Qiscus-Secret-Key : {{Secret Key}}content-type : application/json
Copy

Body:

HTTP
    
 
{    "recipient_type": "individual",    "to": "62***", // YOUR CUSTOMER NUMBER HERE    "type": "text",    "text": {      "body": "your-message-content"    }}
Copy

Example:

HTTP
    
 
curl -X POST \  https://omnichannel.qiscus.com/whatsapp/v1/***/***/messages \  -H 'Qiscus-App-Id: ***' \  -H 'Qiscus-Secret-Key: ***' \  -H 'Content-Type: application/json' \  -d '{    "recipient_type": "individual",    "to": "62***",    "type": "text",    "text": {      "body": "your-message-content"    }}'
Copy

Example Response:

On Cloud
On Premise
    
 
{    "contacts": [        {            "input": "62***",            "wa_id": "62***"        }    ],    "messages": [        {            "id": "wamid.***"        }    ],    "messaging_product": "whatsapp"}
Copy

This response comes from Qiscus WhatsApp Message API, which means we will process your message to WhatsApp API to send your reply to your customer. Parameter messages.id is a reference to id that you can match in the response that you get in your webhook.

Example Content Webhook:

HTTP
    
 
{  "app_code": "***", // your app-id  "channel_id": ***, // your channel-id  "contacts": [    {      "profile": {        "name": "Risna" // your customer's name      },      "wa_id": "62***" // your customer's number    }  ],  "messages": [    {      "from": "62***",       "id": "***", // the id from response before      "text": {        "body": "hello" // your customer's body message       },      "timestamp": "1623136983",      "type": "text"    }  ]}
Copy

Template Messages

You need to setup template first, you can find how to submit the template in this docs, if you already have then you can continue to use this API. The template should be approved.

Please refer this documentations as well to understand the possibility of the payload:

On Premise

On Cloud

https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-message-templates

Please follow this page to get your namespace, template__name and language__code.

URL:

HTTP
    
 
[POST] https://omnichannel.qiscus.com/whatsapp/v1/{{APP-ID}}/{{channel-id}}/messages
Copy

Please follow this page to get your App ID, Qiscus Secret Key and channel-id.

Header:

HTTP
    
 
Qiscus-App-Id : {{APP-ID}}Qiscus-Secret-Key : {{Secret Key}}content-type : application/json
Copy

Body:

HTTP
    
 
{    "to": "62***", // YOUR CUSTOMER NUMBER HERE    "type": "template",    "template": {        "namespace": "***",        "name": "ticket_resolved_122",        "language": {            "policy": "deterministic",            "code": "en"        },        "components": [            {                "type" : "header",                "parameters": [                    {                        "type": "text",                        "text": "John"                    }                ]            },            {                "type" : "body",                "parameters": [                    {                        "type": "text",                        "text": "Ticket 001"                    }                ]            }        ]    }}
Copy

Example:

HTTP
    
 
curl -X POST \  https://omnichannel.qiscus.com/whatsapp/v1/***/***/messages \  -H 'Qiscus-App-Id: ***' \  -H 'Qiscus-Secret-Key: xxxxxxxxxx' \  -H 'Content-Type: application/json' \  -d '{    "to": "62***",    "type": "template",    "template": {        "namespace": "***",        "name": "ticket_resolved_122",        "language": {            "policy": "deterministic",            "code": "en"        },        "components": [            {                "type" : "header",                "parameters": [                    {                        "type": "text",                        "text": "John"                    }                ]            },            {                "type" : "body",                "parameters": [                    {                        "type": "text",                        "text": "Ticket 001"                    }                ]            }        ]    }}'
Copy

Example Response:

On Cloud
On Premise
    
 
{    "contacts": [        {            "input": "62***",            "wa_id": "62***"        }    ],    "messages": [        {            "id": "wamid.***"        }    ],    "messaging_product": "whatsapp"}
Copy

Example Content Webhook:

HTTP
    
 
{  "app_code": "***", // your app-id  "channel_id": ***, // your channel-id  "statuses": [    {      "id": "***", // your messages.id from response api      "recipient_id": "62***", // your customer number      "status": "read", // your status messages      "timestamp": "1623138607"    }  ]}
Copy

Interactive Messages Template

Quick Reply

Please refer this documentation as well to understand the possibility of the payload: https://developers.facebook.com/docs/whatsapp/api/messages/message-templates/interactive-message-templates.

URL:

HTTP
    
 
[POST] https://omnichannel.qiscus.com/whatsapp/v1/{{APP-ID}}/{{channel-id}}/messages
Copy

Please follow this page to get your App ID, Qiscus Secret Key and channel-id.

Header:

HTTP
    
 
Qiscus-App-Id : {{APP-ID}}Qiscus-Secret-Key : {{Secret Key}}content-type : application/json
Copy

Body

HTTP
    
 
{    "to": "62***", // YOUR CUSTOMER NUMBER HERE    "type": "template",    "template": {        "namespace": "6616bb93_d895_41e7_8bbe_2c528219e56e",        "name": "ticket_resolved_123",        "language": {            "policy": "deterministic",            "code": "en"        },        "components": [            {                "type" : "header",                "parameters": [                    {                        "type": "text",                        "text": "John"                    }                ]            },            {                "type" : "body",                "parameters": [                    {                        "type": "text",                        "text": "Credit Card"                    }                ]            },            {                "type": "button",                "sub_type" : "quick_reply",                "index": "0",                 "parameters": [                    {                        "type": "payload",                        "payload":"aGlzIHRoaXMga"                    }                ]            },            {                "type": "button",                "sub_type" : "quick_reply",                "index": "1",                 "parameters": [                    {                        "type": "payload",                        "payload":"SUQgV1FEV0RT"                    }                ]            }        ]    }}
Copy

Example:

HTTP
    
 
curl -X POST \  https://omnichannel.qiscus.com/whatsapp/v1/***/***/messages \  -H 'Qiscus-App-Id: ***' \  -H 'Qiscus-Secret-Key: ***' \  -H 'Content-Type: application/json' \  -d '{    "to": "62***",    "type": "template",    "template": {        "namespace": "6616bb93_d895_41e7_8bbe_2c528219e56e",        "name": "ticket_resolved_123",        "language": {            "policy": "deterministic",            "code": "en"        },        "components": [            {                "type" : "header",                "parameters": [                    {                        "type": "text",                        "text": "John"                    }                ]            },            {                "type" : "body",                "parameters": [                    {                        "type": "text",                        "text": "Credit Card"                    }                ]            },            {                "type": "button",                "sub_type" : "quick_reply",                "index": "0",                 "parameters": [                    {                        "type": "payload",                        "payload":"aGlzIHRoaXMga"                    }                ]            },            {                "type": "button",                "sub_type" : "quick_reply",                "index": "1",                 "parameters": [                    {                        "type": "payload",                        "payload":"EZISUQgV1FEV0RT"                    }                ]            }        ]    }}'
Copy

###

Call To Actions

Please refer this documentation as well to understand the possibility of the payload: https://developers.facebook.com/docs/whatsapp/api/messages/message-templates/interactive-message-templates.

URL:

HTTP
    
 
[POST] https://omnichannel.qiscus.com/whatsapp/v1/{{APP-ID}}/{{channel-id}}/messages
Copy

Please follow this page to get your App ID, Qiscus Secret Key and channel-id.

Header:

HTTP
    
 
Qiscus-App-Id : {{APP-ID}}Qiscus-Secret-Key : {{Secret Key}}content-type : application/json
Copy

Body:

HTTP
    
 
{    "to": "62***", // YOUR CUSTOMER NUMBER HERE    "type": "template",    "template": {        "namespace": "6616bb93_d895_41e7_8bbe_2c528219e56e",        "name": "ticket_resolved_124",        "language": {            "policy": "deterministic",            "code": "en"        },        "components": [            {                "type" : "header",                "parameters": [                    {                        "type": "text",                        "text": "John"                    }                ]            },            {                "type" : "body",                "parameters": [                    {                        "type": "text",                        "text": "credit card"                    }                ]            },            {                "type": "button",                "sub_type" : "url",                "index": "1",                "parameters": [                    {                        "type": "text",                        "text": "abc"                    }                ]            }        ]    }}
Copy

Example:

HTTP
    
 
curl -X POST \  https://omnichannel.qiscus.com/whatsapp/v1/***/***/messages \  -H 'Qiscus-App-Id: ***' \  -H 'Qiscus-Secret-Key: ***' \  -H 'Content-Type: application/json' \  -d '{    "to": "62***",    "type": "template",    "template": {        "namespace": "6616bb93_d895_41e7_8bbe_2c528219e56e",        "name": "ticket_resolved_124",        "language": {            "policy": "deterministic",            "code": "en"        },        "components": [            {                "type" : "header",                "parameters": [                    {                        "type": "text",                        "text": "John"                    }                ]            },            {                "type" : "body",                "parameters": [                    {                        "type": "text",                        "text": "credit card"                    }                ]            },            {                "type": "button",                "sub_type" : "url",                "index": "1",                "parameters": [                    {                        "type": "text",                        "text": "abc"                    }                ]            }        ]    }}'
Copy

List Messages & Reply Buttons

Please refer this documentation as well to understand the possibility of the payload:

Interactive messages can be combined together in the same flow.
Users cannot select more than one option at the same time from a list or button message, but they can go back and re-open a previous message.
List or reply button messages cannot be used as notifications. Currently, they can only be sent within 24 hours of the last message sent by the user. If you try to send a message outside the 24-hour window, you get an error message.
Supported platforms: iOS, Android, and web.
This message doesn't eat up your quota outbound message
When a user replies the interactive message it will deliver webhooks notifications through 2 streams
- first stream through WhatsApp Business API Webhook
- second stream through Bot-Human Collaboration Webhook

URL:

HTTP
    
 
[POST] https://omnichannel.qiscus.com/whatsapp/v1/{{APP-ID}}/{{channel-id}}/messages
Copy

Please follow this page to get your App ID, Qiscus Secret Key and channel-id.

Header:

HTTP
    
 
Qiscus-App-Id : {{APP-ID}}Qiscus-Secret-Key : {{Secret Key}}content-type : application/json
Copy

Body:

HTTP
    
 
{  "recipient_type": "individual",    "to": "62***",    "type": "interactive",    "interactive":{      "type": "list",      "header": {        "type": "text",        "text": "your-header-content"      },      "body": {        "text": "your-text-message-content"      },      "footer": {        "text": "your-footer-content"      },      "action": {        "button": "cta-button-content",        "sections":[          {            "title":"section-title1",            "rows": [              {                "id":"unique-row-identifier1",                "title": "row-title-content1",                "description": "row-description-content1"                       }            ]          },          {            "title":"section-title2",            "rows": [              {                "id":"unique-row-identifier2",                "title": "row-title-content2",                "description": "row-description-content2"                     }            ]          },          {            "title":"section-title3",            "rows": [              {                "id":"unique-row-identifier3",                "title": "row-title-content3",                "description": "row-description-content3"                     }            ]          },          {            "title":"section-title4",            "rows": [              {                "id":"unique-row-identifier4",                "title": "row-title-content4",                "description": "row-description-content4"                     }            ]          }        ]      }  }}
Copy

Example:

HTTP
    
 
curl -X POST \  https://omnichannel.qiscus.com/whatsapp/v1/***/***/messages \  -H 'Qiscus-App-Id: ***' \  -H 'Qiscus-Secret-Key: ***' \  -H 'content-type: application/json' \  -d '{  "recipient_type": "individual",    "to": "62***",    "type": "interactive",    "interactive":{      "type": "list",      "header": {        "type": "text",        "text": "your-header-content"      },      "body": {        "text": "your-text-message-content"      },      "footer": {        "text": "your-footer-content"      },      "action": {        "button": "cta-button-content",        "sections":[          {            "title":"section-title1",            "rows": [              {                "id":"unique-row-identifier1",                "title": "row-title-content1",                "description": "row-description-content1"                       }            ]          },          {            "title":"section-title2",            "rows": [              {                "id":"unique-row-identifier2",                "title": "row-title-content2",                "description": "row-description-content2"                     }            ]          },          {            "title":"section-title3",            "rows": [              {                "id":"unique-row-identifier3",                "title": "row-title-content3",                "description": "row-description-content3"                     }            ]          },          {            "title":"section-title4",            "rows": [              {                "id":"unique-row-identifier4",                "title": "row-title-content4",                "description": "row-description-content4"                     }            ]          }        ]      }  }}'
Copy

Other example for quick reply buttons:

HTTP
    
 
curl -X POST \  https://omnichannel.qiscus.com/whatsapp/v1/***/***/messages \  -H 'Qiscus-App-Id: ***' \  -H 'Qiscus-Secret-Key: ***' \  -H 'content-type: application/json' \  -d '{  "recipient_type": "individual",    "to": "6281212962113",    "type": "interactive",    "interactive": {    "type": "button",    "header": {      "type": "text",      "text": "your text"    },    "body": {      "text": "your-text-body-content"    },    "footer": {      "text": "your-text-footer-content"    },    "action": {      "buttons": [        {          "type": "reply",          "reply": {            "id": "unique-postback-id-1",            "title": "First Title"           }        },        {          "type": "reply",          "reply": {            "id": "unique-postback-id-2",            "title": "Second Title"           }        }      ]     }     }}'
Copy

Catalog Product

You can easily showcase and share your products and services with customers by sending a catalog to your customer via WhatsApp Business API. Refer to this documentation for more information about Catalog Product.

Please Contact Us, if you want to connect your catalog product to Qiscus Omnichannel Chat dashboard.

URL:

HTTP
    
 
[POST] https://omnichannel.qiscus.com/whatsapp/v1/{{APP-ID}}/{{channel-id}}/messages
Copy

Please follow this page to get your App ID, Qiscus Secret Key and channel-id.

Header:

HTTP
    
 
Qiscus-App-Id : {{APP-ID}}Qiscus-Secret-Key : {{Secret Key}}content-type : application/json
Copy

Body:

HTTP
    
 
{    "recipient_type": "individual",    "to": "62***",    "type": "interactive",    "interactive": {        "type": "product",        "body": {            "text": "Check out this book !!"        },        "footer": {            "text": ""        },        "action": {            "catalog_id": "51291235XXXXXXXX",            "product_retailer_id": "5XX8"        }    }}
Copy

Example:

HTTP
    
 
curl --location --request POST 'https://omnichannel.qiscus.com/whatsapp/v1/***/***/messages' \--header 'Qiscus-App-Id: abc' \--header 'Qiscus-Secret-Key: ***' \--header 'content-type: application/json' \--data-raw '{    "recipient_type": "individual",    "to": "62***",    "type": "interactive",    "interactive": {        "type": "product",        "body": {            "text": "Check out this book !!"        },        "footer": {            "text": ""        },        "action": {            "catalog_id": "***",            "product_retailer_id": "***"        }    }}'
Copy

Other Example for Multiple Product:

HTTP
    
 
curl --location --request POST 'https://omnichannel.qiscus.com/whatsapp/v1/***/***/messages' \--header 'Qiscus-App-Id: ***' \--header 'Qiscus-Secret-Key: ***' \--header 'content-type: application/json' \--data-raw '{ "recipient_type": "individual",    "interactive": {        "type": "product_list",        "header": {            "type": "text",            "text": "Hey"        },        "body": {            "text": "Check out this book!"        },        "action": {            "catalog_id": "***",            "sections": [                {                    "title": "Harry Potter",                    "product_items": [                        {                            "product_retailer_id": "***"                        },                        {                            "product_retailer_id": "***"                        }                    ]                },                {                    "title": "How to Worry",                    "product_items": [                        {                            "product_retailer_id": "***"                        }                    ]                }            ]        }    },  "to": "62***",  "type": "interactive"}'
Copy

If you face difficulties during sending the Interactive API because of any error or issue on the WhatsApp Server version, please submit ticket, our engineering team will help you.

When user replies the WhatsApp interactive message you will get data from webhook

###

Sending Carousel Templates

Please refer to this documentation to understand the detailed payload.

Please contact support@qiscus.com to request the creation of a carousel template, we will assist you with it.

URL:

HTTP
    
 
[POST] https://omnichannel.qiscus.com/whatsapp/v1/{{APP-ID}}/{{channel-id}}/messages
Copy

Please follow this page to get your App ID, Qiscus Secret Key and channel-id.

Header:

HTTP
    
 
Qiscus-App-Id : {{APP-ID}}Qiscus-Secret-Key : {{Secret Key}}content-type : application/json
Copy

Body:

HTTP
    
 
curl --location 'https://omnichannel.qiscus.com/whatsapp/v1/***/***/messages' \--header 'Qiscus-App-Id: ***' \--header 'Qiscus-Secret-Key: ***' \--header 'Content-Type: application/json' \--data '{    "messaging_product": "whatsapp",    "recipient_type": "individual",    "to": "62***",    "type": "template",    "template": {        "name": "summer_carousel_2024",        "language": {            "code": "en_US"        },        "components": [            {                "type": "BODY",                "parameters": [                    {                        "type": "TEXT",                        "text": "Andi"                    },                    {                        "type": "TEXT",                        "text": "Hello"                    }                ]            },            {                "type": "CAROUSEL",                "cards": [                    {                        "card_index": 0,                        "components": [                            {                                "type": "HEADER",                                "parameters": [                                    {                                        "type": "IMAGE",                                        "image": {                                            "id": "***"                                        }                                    }                                ]                            },                            {                                "type": "BODY",                                "parameters": [                                    {                                        "type": "text",                                        "text": "30OFFEXOTIC "                                    },                                    {                                        "type": "text",                                        "text": "10% "                                    }                                ]                            },                            {                                "type": "BUTTON",                                "sub_type": "QUICK_REPLY",                                "index": 0,                                "parameters": [                                    {                                        "type": "PAYLOAD",                                        "payload": "***"                                    }                                ]                            },                            {                                "type": "BUTTON",                                "sub_type": "URL",                                "index": 1,                                "parameters": [                                    {                                        "type": "PAYLOAD",                                        "payload": "***"                                    }                                ]                            }                        ]                    },                    {                        "card_index": 1,                        "components": [                            {                                "type": "HEADER",                                "parameters": [                                    {                                        "type": "IMAGE",                                        "image": {                                            "id": "***"                                        }                                    }                                ]                            },                            {                                "type": "BODY",                                "parameters": [                                    {                                        "type": "text",                                        "text": "20OFFEXOTIC "                                    },                                    {                                        "type": "text",                                        "text": "20% "                                    }                                ]                            },                            {                                "type": "BUTTON",                                "sub_type": "QUICK_REPLY",                                "index": 0,                                "parameters": [                                    {                                        "type": "PAYLOAD",                                        "payload": "xxx12344"                                    }                                ]                            },                            {                                "type": "BUTTON",                                "sub_type": "URL",                                "index": 1,                                "parameters": [                                    {                                        "type": "PAYLOAD",                                        "payload": "1235fssss"                                    }                                ]                            }                        ]                    }                ]            }        ]    }}'
Copy

To use media on this API, you need to contact us for uploading purposes, as WhatsApp does not allow the use of plain URLs

Sending Templates with Flow

Message templates with Flow allows businesses to create message template flows within WhatsApp. It helps guide users through a series of steps or options to complete a task or get information. Please refer to this documentation for more details.

Ensure that your template passes all required reviews so that status is APPROVED instead of PENDING.

URL:

HTTP
    
 
[POST]https://omnichannel.qiscus.com/whatsapp/v1/{{AppId}}/{{ChannelId}}/messages
Copy

Header:

HTTP
    
 
Qiscus-App-Id : {{APP-ID}}Qiscus-Secret-Key : {{Secret Key}}content-type : application/json
Copy

Body:

HTTP
    
 
{  "recipient_type": "individual",  "to": "62***",  "type": "template",  "template": {    "name": "flow_sign_up",    "language": {      "code": "en"    },    "components": [      {        "type": "header",        "parameters": [          {            "type": "image",            "image": {              "link": "xxx.jpg"            }          }        ]      },      {        "type": "button",        "sub_type": "flow",        "index": "0"      }    ]  }}
Copy

Example:

HTTP
    
 
curl --location 'https://omnichannel.qiscus.com/whatsapp/v1/***/***/messages' \--header 'Qiscus-App-Id: ***' \--header 'Qiscus-Secret-Key: ***' \--header 'Content-Type: application/json' \--data '{  "recipient_type": "individual",  "to": "62***",  "type": "template",  "template": {    "name": "flow_sign_up",    "language": {      "code": "en"    },    "components": [      {        "type": "header",        "parameters": [          {            "type": "image",            "image": {              "link": "xxx.jpg"            }          }        ]      },      {        "type": "button",        "sub_type": "flow",        "index": "0"      }    ]  }}'
Copy

Sending Interactive Message Templates with Flow

WhatsApp Flow Interactive Message is a feature that allows businesses to create menu options within a conversation, WhatsApp Flow Interactive Message enabling customers to select choices and making interactions easier. Please refer to this documentation for more details.

URL:

HTTP
    
 
[POST]https://omnichannel.qiscus.com/whatsapp/v1/{{AppId}}/{{ChannelId}}/messages
Copy

Header:

HTTP
    
 
Qiscus-App-Id : {{APP-ID}}Qiscus-Secret-Key : {{Secret Key}}content-type : application/json
Copy

Body:

HTTP
    
 
{    "messaging_product": "whatsapp",    "to": "62***",    "recipient_type": "individual",    "type": "interactive",    "interactive": {        "type": "flow",        "header": {            "type": "text",            "text": "Header Example"        },        "body": {            "text": "Body Example"        },        "footer": {            "text": "Footer Example"        },        "action": {            "name": "flow",            "parameters": {                "flow_message_version": "3",                "flow_action": "navigate",                "flow_token": "***",                "flow_id": "***",                "flow_cta": "Open Flow!",                "flow_action_payload": {                    "screen": "RECOMMEND",                    "data": {                        "CUSTOM_KEY": "123xxx"                    }                }            }        }    }}
Copy

Example:

HTTP
    
 
curl --location --globoff 'https://omnichannel.qiscus.com/whatsapp/v1/***/***/messages' \--header 'Qiscus-App-Id: ***' \--header 'Qiscus-Secret-Key: ***' \--data '{    "messaging_product": "whatsapp",    "to": "62***",    "recipient_type": "individual",    "type": "interactive",    "interactive": {        "type": "flow",        "header": {            "type": "text",            "text": "Header Example"        },        "body": {            "text": "Body Example"        },        "footer": {            "text": "Footer Example"        },        "action": {            "name": "flow",            "parameters": {                "flow_message_version": "3",                "flow_action": "navigate",                "flow_token": "***",                "flow_id": "***",                "flow_cta": "Open Flow!",                "flow_action_payload": {                    "screen": "RECOMMEND",                    "data": {                        "CUSTOM_KEY": "123xxx"                    }                }            }        }    }}'
Copy

###

Previous WhatsApp Messages API

You can also still using these APIs, we will not deprecate these API yet until further notice.

Here is the API for sending text template: https://documenter.getpostman.com/view/8259884/SzKMzMYz#83863325-fa2d-499b-bfc1-83ff08935a29

Here is the API for sending text template with image/video/pdf header: https://documenter.getpostman.com/view/8259884/SzKMzMYz#e0a7e389-6195-4da9-a25d-b1ecd9eee4e9.

For any further question you can ask us via : https://support.qiscus.com/hc/en-us.

Upload Media API

Use this API to upload your media. The media is stored on the WhatsApp servers for 14 days. Please refer to this documentations.

URL :

HTTP
    
 
[POST] https://omnichannel.qiscus.com/whatsapp/v1/{{APP-ID}}/{{channel-id}}/media
Copy

Please follow this page to get your App ID, Qiscus Secret Key and channel-id.

Header :

HTTP
    
 
Qiscus-App-Id : {{APP-ID}}Qiscus-Secret-Key : {{Secret Key}}content-type : {{appropriate media type}}
Copy

supported of content-type

application/pdf, image/jpeg, image/jpg, image/png, and video/mp4

Body :

--data-binary
    
 
<your file contents>
Copy

Example :

CURL
    
 
curl -X POST \  https://omnichannel.qiscus.com/whatsapp/v1/***/***/media \  -H 'Qiscus-App-Id: ***' \  -H 'Qiscus-Secret-Key: ***' \  -H 'Content-Type: {{appropriate media type}}' \  --data-binary '@<<path-to-media>>'
Copy

Example Response :

On Cloud
On Premise
    
 
{    "media": [        {            "id": "***"        }    ]}
Copy

Retrieve Media API

Use this API to retrieve the media that you uploaded before. {{IdMedia}} refers to media.id from the response of Upload Media API. Please refer to this documentations.

URL :

HTTP
    
 
[GET] https://omnichannel.qiscus.com/whatsapp/v1/{{APP-ID}}/{{channel-id}}/media/{{IdMedia}}
Copy

Please follow this page to get your App ID, Qiscus Secret Key and channel-id.

Header :

HTTP
    
 
Qiscus-App-Id : {{APP-ID}}Qiscus-Secret-Key : {{Secret Key}}content-type : application/json
Copy

Example :

HTTP
    
 
curl -X GET \  https://omnichannel.qiscus.com/whatsapp/v1/***/***/media/6a6e7688-b8ea-432a-adb7-c43295d3d829 \  -H 'Qiscus-App-Id: ***' \  -H 'Qiscus-Secret-Key: ***' \  -H 'Content-Type: application/json' \
Copy

Location

Use this API for send location message type to your customer. Please refer to this documentation as well to understand the possibility of the payload.

URL :

HTTP
    
 
[POST] https://omnichannel.qiscus.com/whatsapp/v1/{{APP-ID}}/{{channel-id}}/messages
Copy

Please follow this page to get your App ID, Qiscus Secret Key and channel-id.

Header :

HTTP
    
 
Qiscus-App-Id : {{APP-ID}}Qiscus-Secret-Key : {{Secret Key}}content-type : application/json
Copy

Body :

HTTP
    
 
{    "recipient_type": "individual",    "to": "62***",    "type": "location",    "location": {        "longitude": -122.425332,        "latitude": 37.758056,        "name": "Facebook HQ",        "address": "1 Hacker Way, Menlo Park, CA 94025"}
Copy

Example :

HTTP
    
 
curl -X POST \  https://omnichannel.qiscus.com/whatsapp/v1/***/***/messages \  -H 'Qiscus-App-Id: ***' \  -H 'Qiscus-Secret-Key: ***' \  -H 'Content-Type: application/json' \  -d '{        "recipient_type": "individual",        "to": "62***",        "type": "location",        "location": {            "longitude": -122.425332,            "latitude": 37.758056,            "name": "Facebook HQ",            "address": "1 Hacker Way, Menlo Park, CA 94025"      }'
Copy

Example Response :

On Cloud
On Premise
    
 
{    "contacts": [        {            "input": "62***",            "wa_id": "62***"        }    ],    "messages": [        {            "id": "wamid.***"        }    ],    "messaging_product": "whatsapp"}
Copy

Typing Indicators

Typing Indicator serves as a visual cue to WhatsApp users, indicating that the business is currently preparing a response. This indicator can enhance the user experience by providing a sense of responsiveness and interactivity, especially when the business needs time to respond to the message.

When a message is received, the business can send a read receipt (to indicate the message has been read) and simultaneously show a typing indicator to signal that a reply is being prepared. These two features can be sent in a single API request.

The typing indicator will automatically disappear when:

The business sends a reply, or
After 25 seconds, if no message is sent.

To send a typing indicator along with a read receipt, you can use the following API request:

URL :

HTTP
    
 
https://omnichannel.qiscus.com/whatsapp/v1/{{APPID}}/{{channel-ID}}/messages
Copy

Header :

HTTP
    
 
Qiscus-App-Id : {{APP-ID}}Qiscus-Secret-Key : {{Secret Key}}content-type : application/json
Copy

Body :

You can obtain the message_id required for this request from the incoming message payload, which can be accessed through this documentation.

HTTP
    
 
{    "to": "62*****",    "type": "text",   "messaging_product": "whatsapp",    "status": "read",    "message_id": "wamid.*****",    "typing_indicator": {        "type": "text"    }}
Copy

Example Request:

HTTP
    
 
curl --location --request POST 'https://omnichannel.qiscus.com/whatsapp/v1/***/***/messages' \--header 'Qiscus-App-Id: ***' \--header 'Qiscus-Secret-Key: ***' \--header 'Content-Type: application/json' \--data '{    "to": "62***",    "type": "text",   "messaging_product": "whatsapp",    "status": "read",    "message_id": "wamid.***":,    "typing_indicator": {        "type": "text"    }}'
Copy

Example Response :

Javascript
    
 
{    "success": true}
Copy

Guides

We provide a guide to help you get the most out of the WhatsApp Business API

How to Use WABA Catalogue API

Before using WABA Catalogue API, please Contact Us to connect your catalog product to Qiscus Omnichannel Chat dashboard.

You can use WhatsApp Business API to share your products while chatting with their customers in the form of a catalog. There are two types of catalogs you can create, Multi-Product Messages and Single Product Messages. Multi-Product Messages allows you to send a catalog of up to 30 items. While Single Product Messages, the catalog will be a single product displayed with details.

This guide will show you how to use WhatsApp business API to send catalog with Single Product Messages.

The catalog will only be sent if the conversation is within the 24 hours open window

Create catalogue in Facebook Commerce Manager,
Give Qiscus access in Assign Partner under Commerce Manager catalog by accessing this page Facebook business Setting. After that, you can follow these step:

Click the Add button in the Partner to share assets with section and enter Qiscus Business ID. Please contact our team to get Qiscus Business ID.

Select Catalog in the pop up that appears and select the catalog you want to assign then click Save,

Qiscus has become your partner and the catalog you previously assigned will be visible in the Assigned Assets section,

You should also give Qiscus BSP Admin access to Commerce Manager to manage the catalog by add People to Facebook business Setting and follow these steps:

Please contact our team to get the Qiscus BSP Admin email address. Click Add button in the People section,

Fill in the email address that you have received. Make sure you activated toggle Admin access and then click Next,

Select Catalog in the pop-up that appears and selects the catalog you want to assign then click Invite. Don’t forget to give Qiscus BSP admin full control of the catalog,

Please confirm with our team after you add the email address. Once the invitation is accepted, You will see the list of connected people and the shared catalog.

Admin Qiscus will connect Catalog to the WABA Business Manager,

Before using the WABA Catalog API, please note the following:

To send a catalog, the 24-hour windows must be active.
You can view the documentation on parameters for interactive messaging API here.

You can start posting the API using this curl:

HTTP
    
 
curl -X POST \  https://omnichannel.qiscus.com/whatsapp/v1/{{your-app-id}}/{{your-channel-id}}/messages \  -H 'app_id: your-app-id' \  -H 'authorization: your-token' \  -H 'content-type: application/json' \  -d '{    "recipient_type": "individual",    "to": "your-target-number",    "type": "interactive",    "interactive": {    "type": "product",    "body": {      "text": "your-text-body-content"    },    "footer": {      "text": "your-text-footer-content"    },    "action": {      "catalog_id": "your-catalog-id",      "product_retailer_id": "your-content-id"    }  }}'
Copy

You can get catalog _id and product_retailer_id in the Facebook Commerce Manager.

catalog_id refers to the ID of the catalog you want to use. The red arrow in the following image shows where you can get the catalog_id.

While product_retailer_id refers to the Content ID of your items in the catalog you want to use. You can get product_retailer_id as shown in the image below.

The catalog will appear like these on the Customer's WhatsApp,

Client need to subscribe WhatsApp webhook to listen the response from client when interacting with the Catalog,
Client can then respond to the customer using WhatsApp API provided by Qiscus.

How to Enable Catalog on WhatsApp Business Profile

After you have successfully integrated your product catalog with your WhatsApp Business Account, the product catalog icon will not appear on your profile by default. Here is an example of a WhatsApp Business profile without the product catalog icon.

Please make sure the catalog you are going to use is connected to your WhatsApp Business Account.

However, you can enable the product catalog on a per-business phone number basis. Once it's enabled, the product catalog icon will appear in your conversations and on your WhatsApp business profile. To enable this setting, please contact us and submit a request.

Once our team enables the catalog for your WhatsApp Business, the product catalog icon will appear as shown below:

The product catalog icon in the conversation.

The product catalog icon on the WhatsApp business profile.

This will allow your customers to easily browse and purchase your products directly on WhatsApp.

If you have any questions or need assistance with setting up your product catalog, please don't hesitate to contact us.

How to Use WhatsApp for OTP Authentication

WhatsApp officially released the new pricing on June 1, 2023. Business-initiated conversations will be split into three new categories: utility, authentication, and marketing. Meanwhile, user-initiated conversations will be called service conversations.

Accordingly, WhatsApp is set to introduce a new feature called "Authentication templates with one-time password buttons". Please take note of the following important details regarding Authentication templates:

Sending a broadcast will fail if you attempt to use an old template with OTP/Authentication category that contains media, links, or emojis.
While it is still possible to create new templates with the authentication category through the Qiscus Omnichannel Chat dashboard, please be aware that these templates will be rejected due to a distinct message structure. To resolve this, you must edit the template via Facebook Business Manager.

Differences with the old OTP template

Previously, OTP templates had the flexibility to include multiple elements, such as images or several variables. However, Starting from May 29, 2023, any newly created authentication templates must adhere to the following guidelines:

Templates should not include links, media, or emojis.
Each parameter within the template should not exceed a maximum length of 15 characters.
The template should include Copy Code button.

A copy code button copies the one-time password or code to the user's clipboard. The user can then manually switch to your app and paste the password or code into your app's interface.

Example for authentication templates with one-time password button:

Before sending OTP via WhatsApp, first you need an Authentication Template. However, the API used to create the Authentication Template is slightly different due to the new guidelines from WhatsApp. To understand more about the differences, refer to this API documentation.

You can send OTP message with a copy code button via the API by using this cURL:

cURL Syntax:

HTTP
    
 
curl --location 'https://omnichannel.qiscus.com/whatsapp/v1/<your-AppID>/<WA-ChannelID>/messages' \--header 'Qiscus-App-Id: <your-AppID>' \--header 'Qiscus-Secret-Key: <your-Secret_Key>' \--header 'Content-Type: application/json' \--data '{    "to": "<target-number>",    "type": "template",    "template": {        "namespace": "<template-namespace>",        "name": "<template-name>",        "language": {            "policy": "deterministic",            "code": "<template-language-code>"        },        "components": [      {        "type": "body",        "parameters": [          {            "type": "text",            "text": "<your ONE-TIME PASSWORD>"          }        ]      },      {        "type": "button",        "sub_type": "url",        "index": "0",        "parameters": [          {            "type": "text",            "text": "<your ONE-TIME PASSWORD>"          }        ]      }    ]  }}'
Copy

Response:

HTTP
    
 
{    "contacts": [        {            "input": "<INPUT>",            "wa_id": "<WA-ID>"        }    ],    "messages": [        {            "id": "<ID>"        }    ],    "meta": {        "api_status": "stable",        "version": "2.45.1"    }}
Copy

Example Request:

HTTP
    
 
curl --location 'https://omnichannel.qiscus.com/whatsapp/v1/***/***/messages' \--header 'Qiscus-App-Id: ***' \--header 'Qiscus-Secret-Key: ***' \--header 'Content-Type: application/json' \--data '{    "to": "62***",    "type": "template",    "template": {        "namespace": "text",        "name": "newotp",        "language": {            "policy": "deterministic",            "code": "en"        },        "components": [      {        "type": "body",        "parameters": [          {            "type": "text",            "text": "J$Fpn123"          }        ]      },      {        "type": "button",        "sub_type": "url",        "index": "0",        "parameters": [          {            "type": "text",            "text": "J$Fpn123"          }        ]      }    ]  }}'
Copy

Example Response:

HTTP
    
 
{    "contacts": [        {            "input": "62***",            "wa_id": "62***"        }    ],    "messages": [        {            "id": "***"        }    ],    "meta": {        "api_status": "stable",        "version": "2.45.1"    }}
Copy

The OTP message will appear like these on the Customer's WhatsApp:

How to Create and Send a Template with up to 10 Buttons

Facebook Business Messenger offers a feature that allows you to create message templates with a combination of up to 10 buttons, including Call to Action (CTA) Buttons and Quick Reply Buttons. You can use up to 3 Call to Action buttons to direct customers to a website, initiate a phone call, or other specific actions, and up to 8 Quick Reply buttons that enable customers to respond quickly with a single click. This feature is designed to simplify interactions, enhance communication efficiency, and provide a more interactive user experience.

Facebook Business Messenger has specific guidelines and limitations for adding buttons to message templates, Button Types:

Call to Action Buttons: Allows your customer to call a phone number and visit a website.
1. Visit Website: 2 buttons maximum,
2. Call Phone Number: 1 button maximum,
3. Complete Flow: 1 button maximum,
4. Copy Offer Code: 1 button maximum.
Call to Action Buttons: Allows your customer to call a phone number and visit a website.
1. Marketing Opt-out,
2. Custom.

Here are the steps to create a message template with button combinations via Facebook Business Manager:

1. Create a New Template:

Click Create Message,

Setup your template, you can choose the category (Marketing, Utility or Authentication), then select Custom and click Next.

Enter Template name and language.

2. Add Message Content:

Fill out the header, body and footer section of your template and Enter the text or media you want to include in the message content.

3. Add Buttons and Submit Template

Create buttons that let customers respond to your message or take action. You can add up to 10 buttons. If you add more than 3 buttons, they will appear in a list.

Call to Action (CTA) Buttons:

Click Add Button,

Choose the CTA buttons type, such as Visit Website/ Call Now/ Copy offer code,
Enter the button text and fill in the required URL or phone number.

Quick Reply Buttons:

Click Quick Reply Buttons, select Marketing Opt-out or Custom,

Add the short response text you want to display on the button.

you can add a total combination of up to 3 buttons (CTA and/or Quick Reply).

Click Submit for Review, confirmation pop-up will appear and click Confirm.

Wait until the message template approve from Facebook.

If the message template is approve by Facebook, the status will be active, and you can use it.

Sent Message Template with Buttons Combination via the API by using this cURL:

cURL Syntax:

HTTP
    
 
curl --location 'https://multichannel.qiscus.com/whatsapp/v1/{{AppCode}}/{{WAChannelId}}/messages' \--header 'Qiscus-App-Id: {{AppCode}}' \--header 'Qiscus-Secret-Key: {{SecretKey}}' \--header 'Content-Type: application/json' \--data '{    "to": "<target-number>",    "type": "template",    "template": {        "name": "<template-name>",        "language": {            "code": "en"        },        "components": [            {                "type": "button",                "sub_type": "quick_reply",                "index": "3",                "parameters": [                    {                        "type": "text",                        "text": "<your-example-text>"                    }                ]            },            {                "type": "button",                "sub_type": "quick_reply",                "index": "4",                "parameters": [                    {                        "type": "text",                        "text": "<your-example-text>"                    }                ]            },            {                "type": "button",                "sub_type": "quick_reply",                "index": "5",                "parameters": [                    {                        "type": "text",                        "text": "<your-example-text>"                    }                ]            },            {                "type": "button",                "sub_type": "quick_reply",                "index": "6",                "parameters": [                    {                        "type": "text",                        "text": "<your-example-text>"                    }                ]            },            {                "type": "button",                "sub_type": "quick_reply",                "index": "7",                "parameters": [                    {                        "type": "text",                        "text": "<your-example-text>"                    }                ]            },            {                "type": "button",                "sub_type": "quick_reply",                "index": "8",                "parameters": [                    {                        "type": "text",                        "text": "<your-example-text>"                    }                ]            },            {                "type": "button",                "sub_type": "quick_reply",                "index": "9",                "parameters": [                    {                        "type": "text",                        "text": "<your-example-text>"                    }                ]            }        ]    }}'
Copy

Response:

HTTP
    
 
{    "contacts": [        {            "input": "<target-number>",            "wa_id": "<target-number>"        }    ],    "messages": [        {            "id": "wamid.***",            "message_status": "accepted"        }    ],    "messaging_product": "whatsapp"}
Copy

Example Request:

HTTP
    
 
curl --location 'https://multichannel.qiscus.com/whatsapp/v1/{{AppCode}}/{{WAChannelId}}/messages' \--header 'Qiscus-App-Id: {{AppCode}}' \--header 'Qiscus-Secret-Key: {{SecretKey}}' \--header 'Content-Type: application/json' \--data '{    "to": "+62***",    "type": "template",    "template": {        "name": "exclusive_deals",        "language": {            "code": "en"        },        "components": [            {                "type": "button",                "sub_type": "quick_reply",                "index": "3",                "parameters": [                    {                        "type": "text",                        "text": "50% off product"                    }                ]            },            {                "type": "button",                "sub_type": "quick_reply",                "index": "4",                "parameters": [                    {                        "type": "text",                        "text": "Buy 1 Get 1 Free"                    }                ]            },            {                "type": "button",                "sub_type": "quick_reply",                "index": "5",                "parameters": [                    {                        "type": "text",                        "text": "New Arrivals"                    }                ]            },            {                "type": "button",                "sub_type": "quick_reply",                "index": "6",                "parameters": [                    {                        "type": "text",                        "text": "Limited Time Offers"                    }                ]            },            {                "type": "button",                "sub_type": "quick_reply",                "index": "7",                "parameters": [                    {                        "type": "text",                        "text": "Clearance Sale"                    }                ]            },            {                "type": "button",                "sub_type": "quick_reply",                "index": "8",                "parameters": [                    {                        "type": "text",                        "text": "Holiday Special"                    }                ]            },            {                "type": "button",                "sub_type": "quick_reply",                "index": "9",                "parameters": [                    {                        "type": "text",                        "text": "Top Seller"                    }                ]            }        ]    }}'
Copy

Example Response:

HTTP
    
 
{    "contacts": [        {            "input": "62***",            "wa_id": "62***"        }    ],    "messages": [        {            "id": "wamid.***",            "message_status": "accepted"        }    ],    "messaging_product": "whatsapp"}
Copy

and this is the result of sending message template with button combination via the API

Qiscus Omnichannel Chat Preview:

Customer Preview:

Glossary

APP-ID , Secret Key

Log in to Qiscus Omnichannel Chat account with your email and password.
Go to ‘Setting’ menu on the left bar.
Select ‘App Information’.

channel-id

Log in to Qiscus Omnichannel Chat account with your email and password.
Go to ‘Integrations’ menu on the left bar.
Select ‘WhatsApp Integration’.
Look for your WABA and select it.
Take a look at the part of the Webhook URL at the bottom of the page.
Get the last series of number.

Namespace , Template Name, Language

Log in to Qiscus Omnichannel Chat account with your email and password.
Go to ‘Outbound’ menu on the left bar.
Select ‘WhatsApp Broadcast Template’.
Look for your Approved Template and select it.
namespace for Namespace, template_name for Template Name, language_ code for Language. Please check this docs.

Last updated on Apr 30, 2025

Was this page helpful?