Guides

Interactive Message

Suggest Edits

Interactive messages include interactive elements like buttons or lists, designed to enhance engagement by making it easier for users to respond and take action. These messages are a powerful tool for businesses to create more user-friendly and dynamic interactions, such as allowing customers to select options from the message.

There are two types of interactive messages supported in WhatsApp:

  • Reply Buttons: These messages include up to three buttons that allow users to quickly reply to the message by selecting one of the predefined options.
  • Interactive List: These messages present a scrollable list of options (up to 10 items) that users can select from. This is particularly helpful when you need to offer multiple options in a structured manner.

Reply Buttons

Interactive reply button messages allow you to send up to three predefined replies for users to choose from.

HTTP Request: POST /v3/messages

The Reply Button Message example includes the following details about the button:

{
  "channel": "WHATSAPP",
  "request": {
    "message": "message text body of the registered template",
    "clientId": "clientId",
    "externalId": "123456789abcde",
    "to": "+1000000002",
    "from": "1000000001",
    "type": "interactive",
    "interactive": {
      "type": "button",
      "header": {
        "type": "image",
        "image": {
          "link": "https://example.com?media=image.png"
        }
      },
      "body": {
        "text": "Hi Alex! Your appointment with Dr. Smith is scheduled for 3:00 PM on Friday, September 15th. If you need to make changes, please use the buttons below."
      },
      "footer": {
        "text": "Looking forward to seeing you!"
      },
      "action": {
        "buttons": [
          {
            "type": "reply",
            "reply": {
              "id": "0",
              "title": "Change"
            }
          },
          {
            "type": "reply",
            "reply": {
              "id": "1",
              "title": "Cancel"
            }
          }
        ]
      }
    }
  }
}

The parameters presented in the request body example when creating the Reply Button Message are the following:

Parameter Required Description
channel Yes

Specifies the type of delivery channel which the notification message will be sent: "SMS", "EMAIL", "PUSH", "RCS", "WHATSAPP".

In this case, we enter the "WHATSAPP" value to send the WhatsApp message.
request Yes Message content.
request.message Yes

request.from Yes

Phone number of the sender.

Phone number provided during the WABA account setup will be used as the sender of the notification message.

Only accepts numeric characters. Do not include the "+" sign.
request.to Yes Determines the destination phone number for your session message. Numbers are specified in E.164 format → (‘+’ and a country code).
request.type Yes

Type of message you want to send.

Supported options:

  • "text": Sends a plain text message.

  • "image": Sends an image file (.jpeg, .png).

  • "audio": Sends an audio file (.acc, .mp3, .amr, .mpeg).

  • "video": Sends a video file (.mp4, .3gpp.)

  • "document": Sends a document file (.pdf).

  • "contacts": Sends contact information.

  • "location": Sends a location with latitude and longitude.

  • "interactive": Sends an interactive message with reply buttons or list .

In this example, we set the "interactive" parameter.
request.interactive Yes

Only applies to the "interactive" type.

This object contains the details of the interactive messsage,specifying the type of interaction (in this case, reply buttons) and the structure for buttons, headers, body text, and footer text.
request.interactive.
type		 Yes

Only applies to the "interactive" type.

Defines the type of interactive message.

  • "button": Set this parameter to include reply button(s).

  • "list": Set this parameter to include an interactive list.

In this example, we set the "button" parameter.
request.interactive.
header		 No

Only applies to the "interactive" type.

Object contains the details of the message’s header.

This is the content displayed at the top of the message. It can be used to provide context or a brief introduction to the interactive buttons.
request.interactive.
header.
type		 No

Only applies to the "interactive" type, and the "header" option.

Specifies the type of content in the header.

Supports the following types:

  • "text": For text-based headers.

  • "image": For image headers (.jpeg, .png).

  • "video": For video headers (.mp4, .3gpp.).

  • "document": For document headers (.pdf).
request.interactive.
header.
text		 No

Only applies to the "interactive" type, and the "header" option.

Enter the text message header to be sent. A text header has a limit of 60 characters including emojis.
request.interactive.
header.
image		 No

Only applies to the "interactive" type, the "header" option, and the media file type header.

Object that contains details about the media file to be displayed in the header of the message.

Specifies the type of header content: "image", "video", "document".

In this example, the object is "image".
request.interactive.
header.
image.
link		 No

Only applies to the "interactive" type, the "header" option, and the media file type header.

if you set the Video, Image or Document as Header type header, enter the URL of the chosen media.

The URL of the header (image, video and document) must be a valid URL that starts with "http://…" or "https://…" and provides a direct download. Redirects are not supported.

In this example, the file is an image.
request.interactive.
body		 Yes

Only applies to the "interactive" type.

The main text content of the message. This is where the core message is communicated, prompting the user to choose one of the available options.
request.interactive.
body.
text		 Yes

Only applies to the "interactive" type, and the "body" option.

Enter the text message body to be sent. Only contain text, markdown, and emojis. A text body has a limit of 1024 characters including emojis.
request.interactive.
footer		 No

Only applies to the "interactive" type.

An additional text section displayed at the bottom of the message.
request.interactive.
footer.
text		 No

Only applies to the "interactive" type, and the "footer" option.

Enter the text message footer to be sent. A text footer has a limit of 60 characters.
request.interactive.
action		 Yes

Only applies to the "interactive" type.

For Reply buttons, defines the interactive components of the message, specifically the buttons used for user interaction. This field contains an array of buttons that the user can tap to respond.
request.interactive.
action.
buttons		 Yes

Only applies to the "interactive" type.

Array of buttons that users can tap to respond to the message. Each button contains a type and reply object.

You can have up to 3 buttons.
request.interactive.
action.
buttons.
type		 Yes

Only applies to the "interactive" type, and the "buttons" option.

Specifies the type of button. For reply buttons, this is set to "reply".
request.interactive.
action.
buttons.
reply		 Yes

Only applies to the "interactive" type, and the "buttons" option.

This object defines the specific reply option that a user can select by tapping a button. Each reply button in the interactive message is associated with a unique “reply” object that contains an ID and a title.
request.interactive.
action.
buttons.
reply.id		 Yes

Only applies to the "interactive" type, and the "buttons" option.

A unique identifier for each button. Supports up to 3 buttons.
request.interactive.
action.
buttons.
reply.
title		 Yes

Only applies to the "interactive" type, and the "buttons" option.

Button label text.

Maximum 20 characters.
request.externalId No

Alphanumeric identifier used for reporting purposes.
request.clientId No Unique user identifier that can be used for reporting purposes. This is an identifier you can use to uniquely identify the destination address in your systems. This is similar to the externalId and will be sent back to you if you are requesting callbacks that contain status changes of the messages you send.
callbacks No

Indicate one or more (separated by comma) webhook URLs to notify about the status of the message delivery.That is, If you want to receive the status of the message you've sent to your subscribers, you need to specify your endpoint.

Your endpoint must have a HTTP POST access method and receive a JSON body.

The URL is the external callback where the events of the Email will be registered and published. Once an email is processed, its status will be posted to your callback URL.

To view the full list and meaning of each status, please refer to the WhatsApp Status section.

When you send a Reply Button Message, the response body contains the following data:

{
  "meta": {
    "timestamp": 1642531254980,
    "transactionId": "077da1d0-e089-487e-aed0-59534ba2d9f5",
    "explain": "Send Notification"
  }
}

Parameters presented in the response body example when sending the Session Reply Button Message are the following:

Parameter Description
meta "meta" segment is dedicated to metadata regarding the call itself.
meta.timestamp

Call’s time mark.

Sequence of characters identifying when the message has been sent.
meta.transactionId Call’s transaction ID, this will help our teams to locate issues faster if arose.
meta.explain Useful message regarding the operation or the call.

Interactive List

Interactive list messages allow you to present WhatsApp users with a list of options to choose from (options are defined as rows in the request payload):

When a user taps the button in the message, it displays a modal that lists the options available:

Users can then choose one option and their selection will be sent as a reply.

Interactive list messages support up to 10 sections, with up to 10 rows per section, and can include an optional header and footer.

HTTP Request: POST /v3/messages

The Interactive List example includes the following details about the list:

{
  "channel":"WHATSAPP",
  "request":{
    "from":"1000000001",
    "to":"+1000000002",
    "type":"interactive",
    "interactive":{
       "type":"list",
       "header":{
          "type":"text",
          "text":"Choose Your Meal Option"
       },
       "body":{
          "text":"What would you like for lunch today? Please select an option below."
       },
       "footer":{
          "text":"Foodie's Delight: Fresh meals, delivered fast."
       },
       "action":{
          "sections":[
             {
                "title":"I'm Hungry!",
                "rows":[
                   {
                      "id":"first-option",
                      "title":"Grilled Chicken Salad",
                      "description":"Fresh greens with a grilled chicken breast (300 kcal)"
                   },
                   {
                      "id":"second-option",
                      "title":"Veggie Wrap",
                      "description":"Tortilla stuffed with fresh veggies and hummus (250 kcal)"
                   }
                ]
             },
             {
                "title":"Light Bites",
                "rows":[
                   {
                      "id":"third-option",
                      "title":"Fruit Bowl",
                      "description":"A mix of seasonal fruits (150 kcal)"
                   },
                   {
                      "id":"fourth-option",
                      "title":"Greek Yogurt",
                      "description":"Creamy yogurt with honey and granola (200 kcal)"
                   }
                 ]
              }
           ],
           "button":"Select Meal"
         }
      }
   }
}

The parameters presented in the request body example when creating the Session Interactive List are the following:

Parameter Required Description
channel Yes

Specifies the type of delivery channel which the notification message will be sent: "SMS", "EMAIL", "PUSH", "RCS", "WHATSAPP".

In this case, we enter the "WHATSAPP" value to send the WhatsApp message.
request Yes Message content.
request.message Yes

request.from Yes

Phone number of the sender.

Phone number provided during the WABA account setup will be used as the sender of the notification message.

Only accepts numeric characters. Do not include the "+" sign.
request.to Yes Determines the destination phone number for your session message. Numbers are specified in E.164 format → (‘+’ and a country code).
request.type Yes

Type of message you want to send.

Supported options:

  • "text": Sends a plain text message.

  • "image": Sends an image file (.jpeg, .png).

  • "audio": Sends an audio file (.acc, .mp3, .amr, .mpeg).

  • "video": Sends a video file (.mp4, .3gpp.)

  • "document": Sends a document file (.pdf).

  • "contacts": Sends contact information.

  • "location": Sends a location with latitude and longitude.

  • "interactive": Sends an interactive message with reply buttons or list .

In this example, we set the "interactive" parameter.
request.interactive Yes

Only applies to the "interactive" type.

This object contains the details of the interactive message, specifying the type of interaction (in this case, a list), and the structure of the list (sections, rows, buttons).
request.interactive.
type		 Yes

Only applies to the "interactive" type.

Defines the type of interactive message.

  • "button": Set this parameter to include reply button(s).

  • "list": Set this parameter to include an interactive list.

In this example, we set the "list" parameter.
request.interactive.
header		 No

Only applies to the "interactive" type.

Object contains the details of the message’s header.

This is the content displayed at the top of the message. It can be used to provide context or a brief introduction to the interactive buttons.
request.interactive.
header.
type		 No

Only applies to the "interactive" type, and the "header" option.

Specifies the type of content in the header.

Supports the following types:

  • "text": For text-based headers.
request.interactive.
header.
text		 No

Only applies to the "interactive" type, and the "header" option.

Enter the text message header to be sent. A text header has a limit of 60 characters including emojis.
request.interactive.
body		 Yes

Only applies to the "interactive" type.

The main text content of the message. This is where the core message is communicated, prompting the user to choose one of the available options.
request.interactive.
body.
text		 Yes

Only applies to the "interactive" type, and the "body" option.

Enter the text message body to be sent. Only contain text, markdown, and emojis. A text body has a limit of 1024 characters including emojis.
request.interactive.
footer		 No

Only applies to the "interactive" type.

An additional text section displayed at the bottom of the message.
request.interactive.
footer.
text		 No

Only applies to the "interactive" type, and the "footer" option.

Enter the text message footer to be sent. A text footer has a limit of 60 characters.
request.interactive.
action		 Yes

Only applies to the "interactive" type.

For Interactive List, defines the interactive components of the message, specifically the list of options (organized into sections) and the button that the user presses to interact with the list.
request.interactive.
action.
sections		 Yes

Only applies to the "interactive" type.

Array of sections. Each section can contain multiple rows (list items). A section helps organize the options in the list into categories or groups.

Interactive list messages support up to 10 sections, with up to 10 rows per section.
request.interactive.
action.
sections.
title		 Yes

Only applies to the "interactive" type, and the "sections" option.

Section title text. At least 1 section is required. Supports up to 10 sections. Maximum 24 characters.
request.interactive.
action.
sections.
rows		 Yes

Only applies to the "interactive" type, and the "sections" option.

Array of individual rows (list options) that belong to this section.

Rows represent the individual list items (or options) that the user can select. Each row contains an id and a title.
request.interactive.
action.
sections.
rows.
id		 Yes

Only applies to the "interactive" type, and the "sections" option.

A unique identifier for the row, which will be sent back to the server when the user selects this option.

At least one row is required. Supports up to 10 rows.

Maximum 200 characters.
request.interactive.
action.
sections.
rows.
title		 Yes

Only applies to the "interactive" type, and the "sections" option.

Row title. At least 1 row is required.

Supports up to 10 rows.

Maximum 24 characters.
request.interactive.
action.
sections.
rows.
description		 No

Only applies to the "interactive" type, and the "sections" option.

Row description.

Maximum 72 characters.
request.interactive.
action.
button		 Yes

Only applies to the "interactive" type.

Button label text. When tapped, reveals rows (options the WhatsApp user can tap). Supports a single button.

Maximum 20 characters.
request.externalId No

Alphanumeric identifier used for reporting purposes.
request.clientId No Unique user identifier that can be used for reporting purposes. This is an identifier you can use to uniquely identify the destination address in your systems. This is similar to the externalId and will be sent back to you if you are requesting callbacks that contain status changes of the messages you send.
callbacks No

Indicate one or more (separated by comma) webhook URLs to notify about the status of the message delivery.That is, If you want to receive the status of the message you've sent to your subscribers, you need to specify your endpoint.

Your endpoint must have a HTTP POST access method and receive a JSON body.

The URL is the external callback where the events of the Email will be registered and published. Once an email is processed, its status will be posted to your callback URL.

To view the full list and meaning of each status, please refer to the WhatsApp Status section.

Parameters presented in the response body example when sending the Session Interactive List are the following:

Parameter Description
meta "meta" segment is dedicated to metadata regarding the call itself.
meta.timestamp

Call’s time mark.

Sequence of characters identifying when the message has been sent.
meta.transactionId Call’s transaction ID, this will help our teams to locate issues faster if arose.
meta.explain Useful message regarding the operation or the call.

Updated 5 days ago