Sending Interactive List & Buttons
Supports only through WhatsApp Official Channel

Currently in Beta

Introduction

WhatsApp keep adding more messages formats to their messaging app to make the communication more seamless and frictionless, July 2021 WhatsApp Introduced a new message type "List Messages" and buttons now made available through Session messages as earlier, button's was earlier available only through Template Messages
From July 2021 onwards it's possible to send messages with optional header, footer in session messages as well, when passing the head and footer the body character will limit to 1024 when compared to the 4000 characters for text only message type.

List Messages

Using list message business can send a menu as message with upto 10 lists or choices separated by optional section and header, a great feature to showcase product category, recent orders, saved card details,faq etc
This type of message offers a simpler and more consistent way for users to make a selection when interacting with a business

List Message Specifications

    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.
    It's possible to use header and footer
    List 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.
    No Template Approval Needed
    List can be dynamically generate based on the conversation context
    Able to pass your own reference value against each choice so that developers will get the value when a user make a choice.
    It's possible to pass upto 10 choices in list and segregate the choice with Sections (Optional)
    Can't use Media files with a list messages

Why You Should Use It

User Comprehension
When compared to text-based lists, interactive messages provide a simpler and more consistent format for people to find and select what they want from a business. During testing, people had higher comprehension levels interacting with these features.
Business Outcomes
During testing, chatbots using interactive messaging features achieved significantly higher response rates and conversions compared to those that are text-based.
Personalised
Populated dynamically in real-time and so can be personalised to the customer or situation. For example, you can show a List message of available time slots for appointment booking, or use Reply buttons to show previous delivery addresses.
No Templates
List Messages do not require templates or pre-approvals.

When You Should Use It

List Messages are best for presenting several options, such as:
    A customer care or FAQ menu
    A take-out menu
    Selection of nearby stores or locations
    Available reservation times
    Choosing a recent order to repeat
    Displaying last 10 order details
    Showing last few transactions
    Displaying Saved Card details
    Show delivery address to choose

Understanding List Message Components

Interactive Quick Reply Buttons

WhatsApp first experimented the Quick Reply buttons with WhatsApp Template messages now from July 2021 onwards it's extended to Session messages as well, now business will able to send a message with upto 3 quick reply buttons and button text can now generated dynamically.

Quick Reply Button Specifications

    Ability to use with Image/Video/Document/GIF media files
    Supports Header & Footer optional
    Upto 3 text buttons can be placed in a message
    Buttons will automatically disable once a user is selected i.e user able to select only one button at a time
    Button supports only Text (no emoji) upto 20 characters
    No approval needed so button can be dynamically generated as per the context of the conversation
    Able to pass your own reference value against each button so that developers can track which button got clicked by the user

When You Should Use this?

    When customer want to make a selection like Confirm an Appointment
    Submit feedback about an order
    Combine with List to use for an enhanced user experience
    Airtime recharge
    Changing personal details
    Reordering a previous order
    Requesting a return
    Adding optional extras to a food order
    Choosing a payment method

Understand Quick Reply Button Components

Watch Video How List Message & Quick Reply Button combined to build a better conversational experience

Text Vs List Messages & Quick Reply Buttons

Request URL

Method : POST
1
https://pickyassist.com/beta/api/v2/push
Copied!

API Variables

See the API variables used to construct the WhatsApp List Messages & Buttons
Variable
Data Type
Description
Required
token
string
Your API Token
Mandatory
application
numeric
8=WhatsApp Official
919737001155 = Shared Number India
Mandatory
globalmessage
string
Ability to send static message to a group of numbers
Optional, Mandatory if not passed message in data array
global_headermessage
string
Global header, maximum 20 characters
Optional
global_footermessage
string
Global footer, maximum 60 characters
Optional
data
array
Array to pass dynamic messages
​
number
numeric
Mobile Number with Country Code
Mandatory
message
string
Message Content
Mandatory, if globalmessage is blank
header_message
string
20 Characters Maximum
Optional
footer_message
string
60 Characters Maximum
Optional
interactive
array
​
​
interactive_type
numeric
1= List
2 = Quick Reply Button
Mandatory for Interactive messages
list_title
string
Title of the List maximum 20 Characters
Mandatory for List Messages
sections
array
Maximum 10 sections can be created
​
title
string
Title of the sections, choice can be grouped as Sections
Optional, but mandatory if you have more than one Sections
choices
array
Need to pass the choice details in this array
​
Maximum 10 choices can be passed
​
title
string
Title of the Choice
​
Maximum 20 Characters
Mandatory
description
string
Description of the Choice
​
Maximum 72 Characters
Optional
choice_id
string
Your value to track the user selection, you will get this value in the message eventhook variable named "id"
​
Maximum 256 Characters
Mandatory
buttons
array
Maximum 3 Quick Reply Buttons
​
title
string
Button Name, maximum 20 characters
Mandatory
button_id
string
Your value to track the user selection, you will get this value in the message eventhook variable named "id"
​
Maximum 256 Characters
Mandatory

Sample Request - Sending List Messages (Single Contact)

This is a sample request for sending a list menu to a contact
1
{
2
"token":"37c42c3a5305fde8568d870c520",
3
"priority ":"0",
4
"application":"8",
5
"interactive_type":1,
6
"data":[
7
{
8
"number":"19834434690",
9
"message":"test message body",
10
"header_message":"test header",
11
"footer_message":"test footer",
12
"interactive":{
13
"list_title":"Test Button",
14
"sections":[
15
{
16
"title":"Section1",
17
"choices":[
18
{
19
"title":"choice1",
20
"choice_id":"ref1",
21
"description":"choice description1"
22
},
23
{
24
"title":"choice2",
25
"choice_id":"ref2",
26
"description":"choice description2"
27
}
28
]
29
},
30
{
31
"title":"Section2",
32
"choices":[
33
{
34
"title":"choice21",
35
"choice_id":"ref21",
36
"description":"choice description21"
37
},
38
{
39
"title":"choice22",
40
"choice_id":"ref22",
41
"description":"choice description22"
42
}
43
]
44
}
45
]
46
}
47
}
48
]
49
}
Copied!
​

Sample Request - Sending List Messages (Dynamic Messages - Multiple Contacts)

This is a sample request for sending a list menu to multiple contacts and each contact will receive different list menu and message content
1
{
2
"token":"37c42c3a5fde8568d870c520",
3
"priority ":"0",
4
"application":"8",
5
"interactive_type":1,
6
"data":[
7
{
8
"number":"19834434690",
9
"message":"test message body",
10
"header_message":"test header",
11
"footer_message":"test footer",
12
"interactive":{
13
"list_title":"Test Button",
14
"sections":[
15
{
16
"title":"Section1",
17
"choices":[
18
{
19
"title":"choice1",
20
"choice_id":"ref1",
21
"description":"choice description1"
22
},
23
{
24
"title":"choice2",
25
"choice_id":"ref2",
26
"description":"choice description2"
27
}
28
]
29
},
30
{
31
"title":"Section2",
32
"choices":[
33
{
34
"title":"choice21",
35
"choice_id":"ref21",
36
"description":"choice description21"
37
},
38
{
39
"title":"choice22",
40
"choice_id":"ref22",
41
"description":"choice description22"
42
}
43
]
44
}
45
]
46
}
47
},
48
{
49
"number":"19834434690",
50
"message":"test message body2",
51
"header_message":"test header2",
52
"footer_message":"test footer2",
53
"interactive":{
54
"list_title":"Test Button2",
55
"sections":[
56
{
57
"title":"Section122",
58
"choices":[
59
{
60
"title":"choice1",
61
"choice_id":"ref1",
62
"description":"choice description1"
63
},
64
{
65
"title":"choice2",
66
"choice_id":"ref2",
67
"description":"choice description2"
68
}
69
]
70
},
71
{
72
"title":"Section2",
73
"choices":[
74
{
75
"title":"choice21",
76
"choice_id":"ref21",
77
"description":"choice description21"
78
},
79
{
80
"title":"choice22",
81
"choice_id":"ref22",
82
"description":"choice description22"
83
}
84
]
85
}
86
]
87
}
88
}
89
]
90
}
91
​
Copied!

Sample Request - Sending List Messages (Multiple Contact - Static)

This is a sample request for sending a list menu to multiple contacts but the message content and list menu is static for all contacts
Supports Only Video/Image/GIF/Document as media files when using with Quick Reply Buttons and maximum 1024 characters allowed in the body contents, Optional Header upto 20 characters, optional Footer upto 60 Characters
1
{
2
"token":"37c42c305fde8568d870c520",
3
"priority ":"0",
4
"application":"8",
5
"interactive_type":1,
6
"globalmessage":"test message body",
7
"global_headermessage":"test header",
8
"global_footermessage":"test footer",
9
"interactive":{
10
"list_title":"Test Button",
11
"sections":[
12
{
13
"title":"Section1",
14
"choices":[
15
{
16
"title":"choice1",
17
"choice_id":"ref1",
18
"description":"choice description1"
19
},
20
{
21
"title":"choice2",
22
"choice_id":"ref2",
23
"description":"choice description2"
24
},
25
{
26
"title":"choice3",
27
"choice_id":"ref3",
28
"description":"choice description3"
29
}
30
]
31
},
32
{
33
"title":"Section2",
34
"choices":[
35
{
36
"title":"choice21",
37
"choice_id":"ref21",
38
"description":"choice description21"
39
},
40
{
41
"title":"choice22",
42
"choice_id":"ref22",
43
"description":"choice description22"
44
}
45
]
46
}
47
]
48
},
49
"data":[
50
{
51
"number":"19834434690"
52
},
53
{
54
"number":"19834434690"
55
},
56
{
57
"number":"19834434690"
58
}
59
]
60
}
Copied!

Sample Request - Sending Quick Reply Buttons Messages (Single Contact - Static)

This is a sample request for sending Quick Reply button messages to a single contact with static message content
1
{
2
"token":"37c42c3a543ed8d208568d870c520",
3
"priority ":"0",
4
"application":"8",
5
"interactive_type":2,
6
"data":[
7
{
8
"number":"19846290",
9
"message":"test message body",
10
"media":"https://pickyassist.com/img/logo.png",
11
"header_message":"test header",
12
"footer_message":"test footer",
13
"interactive": {
14
"buttons": [
15
{
16
"title": "yes",
17
"button_id": "btn1"
18
},
19
{
20
"title": "no",
21
"button_id": "btn2"
22
},
23
{
24
"title": "cancel",
25
"button_id": "btn3"
26
}
27
]
28
}
29
​
30
}
31
]
32
}
Copied!
​

Sample Request - Sending Quick Reply Buttons Messages (Multiple Contact - Dynamic)

This is a sample request for sending Quick Reply button messages to multiple contacts with dynamic message content to each contact.
1
{
2
"token":"37c42c3a54bc305fde8568d870c520",
3
"priority ":"0",
4
"application":"8",
5
"interactive_type":2,
6
"data":[
7
{
8
"number":"19846290",
9
"message":"test message body",
10
"media":"https://pickyassist.com/img/logo.png",
11
"header_message":"test header",
12
"footer_message":"test footer",
13
"interactive": {
14
"buttons": [
15
{
16
"title": "yes",
17
"button_id": "btn1"
18
},
19
{
20
"title": "no",
21
"button_id": "btn2"
22
},
23
{
24
"title": "cancel",
25
"button_id": "btn3"
26
}
27
]
28
}
29
​
30
},
31
{
32
"number":"19846290",
33
"message":"test message body",
34
"media":"https://pickyassist.com/blog/wp-content/uploads/2021/05/drafting.png",
35
"header_message":"test header2",
36
"footer_message":"test footer3",
37
"interactive": {
38
"buttons": [
39
{
40
"title": "yes1",
41
"button_id": "btn1"
42
},
43
{
44
"title": "no1",
45
"button_id": "btn2"
46
}
47
]
48
}
49
​
50
}
51
]
52
}
Copied!

Getting List Message Selection & Button Click Events

To know the selection made by user in a list message or which button the user is clicked you need to listen to the Global Webhook Event.
You will get the Webhook Event as below, extract the value from the "Interactive" array
type=1 = List Message | type=2=Quick Reply Button
id= the value you passed in each Choice List (choice_id) or Button (button_id)
description=description of the choice, only applicable for list messages
If you need the button or choice title then extract it from "message_in_raw" variable
Use the "context-msg-id" to know which message user responded
1
{
2
"number":"93436707768",
3
"message-in":"choice1",
4
"message_in_raw":"choice1",
5
"type":1,
6
"application":8,
7
"unique-id":"70946012",
8
"project-id":"14192",
9
"direction":0,
10
"context-msg-id":"41668446",
11
"interactive":{
12
"type":1,
13
"id":"ref1",
14
"description":"choice description1"
15
}
16
}
Copied!
​
Last modified 4mo ago