Sending Interactive Messages

This guide teaches you how to send each interactive message option. Interactive messages give your users a simpler way to find and select what they want from your business on WhatsApp. During testing, chatbots using interactive messaging features achieved significantly higher response rates and conversions compared to those that are text-based.

The following messages are considered interactive:

  • List Messages: Messages including a menu of up to 10 options. This type of message offers a simpler and more consistent way for users to make a selection when interacting with a business.
  • Reply Buttons: Messages including up to 3 options —each option is a button. This type of message offers a quicker way for users to make a selection from a menu when interacting with a business. Reply buttons have the same user experience as interactive templates with buttons.
  • Single Product Message: Messages with a Single Product item from the business’ inventory. See Share Products With Customers for more information.
  • Multi-Product Message: Messages containing a selection of up to 30 items from a business’ inventory. See Share Products With Customers for more information.

With WhatsApp Business API v2.37, we have introduced two new types of interactive messages: Single Product Messages and Multi-Product Messages.

Interactive Message Specifications

  • 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.

See how text messages compare to interactive messages:


See an example of how List messages and Reply buttons can be combined in the same flow:

Something Went Wrong
We're having trouble playing this video.

Overview

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

Interactive 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

Reply Buttons are best for offering quick responses from a limited set of options, such as:

  • Airtime recharge
  • Changing personal details
  • Reordering a previous order
  • Requesting a return
  • Adding optional extras to a food order
  • Choosing a payment method

Reply buttons are particularly valuable for ‘personalized’ use cases where a generic response is not adequate.

How To Use It

At the API level, interactive messages are set by specifying a message’s type to interactive and adding the interactive object. Generally, these messages include 4 main parts: header, body, footer, and action:

{
  "recipient_type": "individual",
  "to" : "whatsapp-id",
  "type": "interactive" 
  "interactive":{
    "type": "list" | "button",
    "header": {},
    "body": {},
    "footer": {},
    "action": {}
  }
}
For List Messages, this is how the parts fit together:

For Reply Buttons Messages, this is how the parts fit together:

See more information below on how to send these messages.

Get Started

Before you can send each message, you need to get your receiver’s WhatsApp ID with a call to the /contacts node.

We recommend setting up your webhooks to receive message status and inbound message notifications. This way, you can track if your message was sent and the answers you get from the users. See Webhooks for more information.

Step 1: Assemble your interactive object

List Messages

To send a list message, you must assemble an interactive object of type list with the following components:

ObjectDescription

header

Optional.

If you decide to include it, you must set the header’s type to text and add a text field with the desired content.


See all available header fields.

body

Required.

Your message’s body.


See all available body fields.

footer

Optional.

Your message’s footer.


See all available footer fields.

action

Required.

Inside action, you must nest:

  • a button field with your button’s content, and
  • at least one section object (maximum of 10).

Inside section, you must add at least one rows object.


See all available action fields.

See all available section fields.

By the end, your interactive object should look something like this:

  "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":"your-section-title-content",
          "rows": [
            {
              "id":"unique-row-identifier",
              "title": "row-title-content",
              "description": "row-description-content",           
            }
          ]
        },
        {
          "title":"your-section-title-content",
          "rows": [
            {
              "id":"unique-row-identifier",
              "title": "row-title-content",
              "description": "row-description-content",           
            }
          ]
        },
        ...
      ]
    }
  }

Reply Buttons

To send a reply button message, you must assemble an interactive object of type button with the following components:

ObjectDescription

header

Optional.

For button interactive messages, you can use the following header types: text, video, image, or document.


Once you select your type, add the corresponding objects/fields with more information:

  • For video, image, and document types: Add a media object.
  • For text type: Add a text field with the desired content.

Example:

"header": {
      "type": "text" | "image" | "video" | "document",
      "text": "your text"
      # OR
      "document": {
        "id": "your-media-id",
        "filename": "some-file-name"
      }
      # OR
      "document": {
        "link": "the-provider-name/protocol://the-url",
        "provider": {
          "name": "provider-name",
        },
        "filename": "some-file-name"
      },
      # OR
      "video": {
        "id": "your-media-id"
      }
      # OR
      "video": {
        "link": "the-provider-name/protocol://the-url",
        "provider": {
          "name": "provider-name"
        }
      }
      # OR
      "image": {
        "id": "your-media-id"
      }
      # OR
      "image": {
        "link": "http(s)://the-url",
        "provider": {
          "name": "provider-name"
        }
      }
    }

See all available header fields.

body

Required.

See all available body fields.

footer

Optional.

See all available footer fields.

action

Required.

You must add at least one button, and include type, title, and id for your buttons. You cannot add more than 3 buttons.


Example:

"action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "unique-postback-id",
            "title": "First Button’s Title" 
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "unique-postback-id",
            "title": "Second Button’s Title" 
          }
        }
      ] 
    }

See all available action fields.

By the end, your interactive object should look something like this:

"interactive": {
    "type": "button",
    "header": { # optional
      "type": "text" | "image" | "video" | "document",
      "text": "your text"
      # OR
      "document": {
        "id": "your-media-id",
        "filename": "some-file-name"
      }
      # OR
      "document": {
        "link": "the-provider-name/protocol://the-url",
        "provider": {
          "name": "provider-name",
        },
        "filename": "some-file-name"
      },
      # OR
      "video": {
        "id": "your-media-id"
      }
      # OR
      "video": {
        "link": "the-provider-name/protocol://the-url",
        "provider": {
          "name": "provider-name"
        }
      }
      # OR
      "image": {
        "id": "your-media-id"
      }
      # OR
      "image": {
        "link": "http(s)://the-url",
        "provider": {
          "name": "provider-name"
        }
      }
    }, # end header
    "body": {
      "text": "your-text-body-content"
    },
    "footer": { # optional
      "text": "your-text-footer-content"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "unique-postback-id",
            "title": "First Button’s Title" 
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "unique-postback-id",
            "title": "Second Button’s Title" 
          }
        }
      ] 
    } # end action   
  } # end interactive

Step 2: Add common message parameters

Now that you have your interactive object, append the other parameters that make a message: recipient_type, to, and type. Remember to set the type to interactive.

{
  "recipient_type": "individual",
  "to" : "whatsapp-id", // WhatsApp ID of your recipient
  "type": "interactive",
  "interactive":{
    // Your interactive object  
   }
  }

See parameters common to all message types here.

Step 3: Make a POST call to /messages

Make a POST call to the /messages endpoint with the JSON object you have assembled in steps 1 and 2. If your message is sent successfully, you get the following response:

{
  "messages": [{
    "id": "{message-id}"
  }]
}

Optional Step 4: Check Webhooks

If you set up your webhooks, check for changes in your message status as well as any responses coming from users.

Webhooks of users responding to interactive messages include a new component called interactive, which contains information about the user’s choice. See Webhooks, Components for more information.

Troubleshooting

See Errors and Status Messages for more information about error codes.

FAQs

There may be a very small number of users for whom their app version does not support this feature, the business will receive a webhook notification throwing an error that describes why the message was unable to be received. It is up to the business to determine how to handle this error elegantly. Best practice would convert the interactive message to a text-based list to allow the user to complete the workflow.

Through user testing we’ve identified 3 as the optimal number of buttons to provide a good user experience. If you have a list of more than 3 options, and cannot condense it into one button message, we recommend using list messages. During testing, businesses had higher response rates and conversions with list messages than using text-based lists.

Through user testing we’ve identified 10 as the optimal number of rows to provide a good user experience. If you have a list of more than 10 options, and cannot condense into one list message, we recommend creating an additional step in the flow and using two list messages. During testing businesses had higher response rates and conversions with this approach than using text-based lists.

Interactive messages can be reopened by the user in order to resend an option. This is in case of mistyping the desired option or wanting to choose a new option.