Before we being with this guide, there are few things to understand:
What is an interactive message template?
Interactive message templates expand the content you can send recipients beyond the standard message template and media messages template types to include interactive buttons
There are two types of predefined buttons offered by WhatsApp:
- Call-to-Action— Allows your customer to call a phone number and visit a website
- Quick Reply— Allows your customer to return a simple text message
These buttons can be attached to text messages or media messages (currently, with media this is not supported our platform).
Submitting Interactive message template for WhatsApp approval:
You can submit your custom template on this Google form: https://forms.gle/gFWNCqmX4LJ6ajjn6. We will submit it to WhatsApp for review and once approved by WhatsApp you can utilize the same using the API given in the latter part of this document.
Please follow the below guidelines while submitting the interactive message template using the Google form:
1. For an Interactive message template: Call-to-Action button template, you are required to submit below details:
- Message template
- Call-to-Action button should have the following:
- Button Title
- Button Type:
- Call a phone number button - the value will be a phone number with country code
- URL button - the value will be a Web page/application URL.
For example, you will have to submit such a template as:
Your train ticket no. {{1}} from {{2}} to {{3}} is confirmed. You can visit our website can download your ticket. | [Contact us,+917834811114] | [Visit Website,http://www.gupshup.io/{{4}}]
Where:
The message template is: Your train ticket no. {{1}} from {{2}} to {{3}} is confirmed. You can visit our website can download your ticket.
Buttons are:
[Contact us,+917834811114]
[Visit Website,http://www.gupshup.io/{{4}}]
- Button title and button value (action) are separated by comma( , ) and group by opening and closing square bracket( [] )
- You can choose to have one type of button or both i.e. call a phone number and URL in a Call-to-Action message template. At present, there can’t be 2 buttons of the same type.
- In case you want to place a dynamic URL button - the URL prefix that is: domain (example: https://www.gupshup.io) should be fixed and the suffix i.e. the relative path can be a variable part that you can programmatically. For example a Dynamic URL button value will is http://www.gupshup.io/{{4}} where {{4}} is the variable.
Message template and Buttons are separated by pipe ( | ) sign
2. For an Interactive message template: Quick reply button template, you are required to submit below details:
- Message Template
- Button title
For example, you will have to submit such a template as:
You can now view your Account Balance or Mini statement for Account ending with {{1}} simply by selecting one of the options below. | [View Account Balance] | [View Mini Statement]
Where:
The message template is: You can now view your Account Balance or Mini statement for Account ending with {{1}} simply by selecting one of the options below.
Buttons are:
[View Account Balance]
[View Mini Statement]
- Each button is separated by pipe( | ) and denoted by opening and closing square bracket( [] )
Message template and Buttons are also separated by pipe ( | ) sign
Once your templates are submitted to WhatsApp for review, you can track the status of your templates from your Gupshup app's template list as shown in the screenshot below:
For any reason, if you don't see your template in the list after 1-2 days, please write to us at devsupport@gupshup.io with your Gupshup app name and the template you have sent.
API to send Interactive message template:
To send a template message to an end-user using our API, first one must make sure the toggle to send template message is set to enabled for your app. To enable the template message, goto settings section of your Access API and scroll down to section Manage your Template messaging settings (as shown in below image) to enable it.
API Spec:
API Endpoint:
https://api.gupshup.io/sm/api/v1/msg
Headers:
Content-type |
application/x-www-form-urlencoded |
apikey |
Your API key here |
Request Body:
Key |
Type |
Description |
Example |
Required |
channel |
string |
The channel on which this message must be sent. |
|
Y |
destination |
string |
The phone number of the recipient to whom message is being sent. |
918x98xx21x4 |
Y |
source |
string |
The WhatsApp Business phone number from whom message will be sent. This number must be the verified number linked to your Gupshup app. |
917834811114 This is our proxy number |
Y |
message |
string |
WhatsApp template message that you want to send to your customers |
You can now view your Account Balance or Mini statement for Account ending with {{1}} simply by selecting one of the options below. | [View Account Balance] | [View Mini Statement] |
Y |
src.name |
string |
Your WhatsApp app name |
DemoApp |
Y - for sandbox apps |
Sample Request:
curl --location --request POST 'https://api.gupshup.io/sm/api/v1/msg' \
--header 'Cache-Control: no-cache' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'apikey: 2xxc4x4xx2c94xxxc2f9xx9d43xxxx8a' \
--data-urlencode 'channel=whatsapp' \
--data-urlencode 'source=917834811114' \
--data-urlencode 'destination=918x98xx21x4' \
--data-urlencode 'message= You can now view your Account Balance or Mini statement for Account ending with {{1}} simply by selecting one of the options below. | [View Account Balance] | [View Mini Statement]' \
--data-urlencode 'src.name=DemoApp'
API Response
WhatsApp send message API responses are async so you will always get a success response which includes an object with a Gupshup message identifier and status as submitted and your callback URL will receive message-event which states that your submitted message to WhatsApp API client (which actually sends message to the customer) is enqueued or failed.
{"status":"submitted","messageId":"ee4a68a0-1203-4c85-8dc3-49d0b3226a35"}
The customer clicked on a Quick Reply Button
When your customer clicks on a quick reply button, a response is sent to your Webhook URL. Below is an example of the callback format.
For the business to understand the context of a message reply, we include the context object. This context object provides the Gupshup message id(property: gsId) of the message to which the customer replied and the WhatsApp message id(property: id) of the original message. In addition to this payload object provides the button text which the user clicked.
Headers |
Content type: application/json |
Inbound Body |
{ "app": "DemoApp", "timestamp": 1590854464792, "version": 2, "type": "message", "payload": { "id": "ABEGkYaYVSEEAgo-sMx1DoUoQJRW", "source": "918x98xx21x4", "type": "text", "payload": { "text": "View Account Balance", "type": "button" }, "sender": { "phone": "918x98xx21x4", "name": "Smit", "country_code": "91", "dial_code": "8x98xx21x4" }, "context": { "id": "gBEGkYaYVSEEAgnPFrOLcjkFjL8", "gsId": "ee4a68a0-1203-4c85-8dc3-49d0b3226a35" } } } |
Comments
0 comments
Please sign in to leave a comment.