Interactive messages
Interactive messages is a WhatsApp feature that offers enhanced functionality for messages. The available options include:
- List Messages: Facilitate user choices by sending list pickers that present a menu of up to 10 options.
- Reply Buttons: Streamline conversation flow by incorporating reply buttons in your messages. Note that a maximum of three reply buttons can be included in a single message.
- Call-to-action URL Button: Customers may be hesitant to tap raw URLs containing lengthy or obscure strings in text messages. In these situations, sending an interactive message with body text and a call-to-action (CTA) URL button might be an option.
- Location Request messages: Location request messages allows you to send messages with text along with a 'Send Location' button. Upon tapping the button, a location sharing screen will appear, enabling users to easily share their location.
- Interactive Flows messages:
- Call Permission Request messages: Call permission request allows you to place a call to your WhatsApp customers but you must obtain their explicit permission first throught this interactive message request. These permissions can be temporary or permanent.
Please note the following guidelines for the header object
- It is possible to add images, videos or documents to the header of a interactive message, but only when using the interactive reply buttons message. To do so add an media object in the Interactive Header. Audio is not supported.
- You also need to update the header type to the type of media you are sending. The options are image, video or document.
Interactive list message
Interactive list message
Please note the following guidelines
- The title of your section contains an maximum length: 24 characters.
- Each row must have a title (Maximum length: 24 characters) and an ID (Maximum length: 200 characters).
- You can add a description (Maximum length: 72 characters), but it is optional.
- Header is optional but only supports text with a maximum lenght: 60 characters.
In the example below, we send a interactive list message that contains list two items.
{
"messages": {
"msg": [
{
"body": {
"type": "auto",
"content": "Fallback Text"
},
"to": [
{
"number": "00316012345678"
}
],
"from": "00316098765432",
"allowedChannels": ["WhatsApp"],
"richContent": {
"conversation": [
{
"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-title1",
"rows": [
{
"id": "unique-row-identifier1",
"title": "row-title-content",
"description": "row-description-content"
}
]
},
{
"title": "your-section-title2",
"rows": [
{
"id": "unique-row-identifier2",
"title": "row-title-content",
"description": "row-description-content"
}
]
}
]
}
}
}
]
}
}
]
}
}
Interactive reply button message
Interactive reply button message
Please note the following guidelines
- title: Button title. It cannot be an empty string and must be unique within the message. Does not allow emojis or markdown. Maximum length: 20 characters.
- id: Unique identifier for your button. This ID is returned in the webhook when the button is clicked by the user. Maximum length: 256 characters.
In the example below, we send a interactive reply button message that contains two reply buttons.
{
"messages": {
"msg": [
{
"body": {
"type": "auto",
"content": "Fallback Text"
},
"to": [
{
"number": "00316012345678"
}
],
"from": "00316098765432",
"allowedChannels": ["WhatsApp"],
"richContent": {
"conversation": [
{
"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-id1",
"title": "First Button"
}
},
{
"type": "reply",
"reply": {
"id": "unique-postback-id2",
"title": "Second Button"
}
}
]
}
}
}
]
}
}
]
}
}
Interactive reply button message with image (media)
Interactive reply button message with image
In the example below, we send a interactive reply button message with an image header and that contains two reply buttons. (Other supported media types for the header are: video and document)
{
"messages": {
"msg": [
{
"body": {
"type": "auto",
"content": "Fallback Text"
},
"to": [
{
"number": "00316012345678"
}
],
"from": "00316098765432",
"allowedChannels": ["WhatsApp"],
"richContent": {
"conversation": [
{
"interactive": {
"type": "button",
"header": {
"type": "image",
"media": {
"mediaName": "CM.com - Be part of it.",
"mediaUri": "https://www.cm.com/cdn/web/blog/content/logo-cmcom.png",
"mimeType": "image/jpeg"
}
},
"body": {
"text": "your-text-body-content"
},
"footer": {
"text": "your-text-footer-content"
},
"action": {
"buttons": [
{
"type": "reply",
"reply": {
"id": "unique-postback-id1",
"title": "First Button"
}
},
{
"type": "reply",
"reply": {
"id": "unique-postback-id2",
"title": "Second Button"
}
}
]
}
}
}
]
}
}
]
}
}
Interactive CTA button message
Interactive CTA button message
Interactive CTA button with image header
Please note the following guidelines
- Only a single URL button is supported by WhatsApp in a call-to-action URL button message. If multiple CTA buttons are supplied, only the first one will be sent with the call-to-action URL button message.
- Header can contains a document, image, video or text.
In the example below, we send a call-to-action URL button message.
{
"messages": {
"msg": [
{
"body": {
"type": "auto",
"content": "Fallback Text"
},
"to": [
{
"number": "00316012345678"
}
],
"from": "00316098765432",
"allowedChannels": ["WhatsApp"],
"richContent": {
"conversation": [
{
"interactive": {
"type": "button",
"header": {
"type": "text",
"text": "your text"
},
"body": {
"text": "your-text-body-content"
},
"footer": {
"text": "your-text-footer-content"
},
"action": {
"buttons": [
{
"type": "openurl",
"id": "unique-postback-id",
"title": "Button",
"url": "your url"
}
]
}
}
}
]
}
}
]
}
}
{
"messages": {
"msg": [
{
"body": {
"type": "auto",
"content": "Fallback Text"
},
"to": [
{
"number": "00316012345678"
}
],
"from": "00316098765432",
"allowedChannels": ["WhatsApp"],
"richContent": {
"conversation": [
{
"interactive": {
"type": "button",
"header": {
"type": "image",
"media": {
"mediaName": "your-image-name",
"mediaUri": "your-image-url",
"mimeType": "media-type"
}
},
"body": {
"text": "your-text-body-content"
},
"footer": {
"text": "your-text-footer-content"
},
"action": {
"buttons": [
{
"type": "openurl",
"id": "unique-postback-id",
"title": "Button",
"url": "your url"
}
]
}
}
}
]
}
}
]
}
}
Location Request messages
Location request messages allows you to send messages with text along with a 'Send Location' button. Upon tapping the button, a location sharing screen will appear, enabling users to easily share their location.
Location Request message
In the example below, we send a Location Request message.
{
"messages": {
"msg": [
{
"body": {
"type": "auto",
"content": "Fallback Text"
},
"to": [
{
"number": "00316012345678"
}
],
"from": "00316098765432",
"allowedChannels": [
"WhatsApp"
],
"richContent": {
"conversation": [
{
"interactive": {
"type": "location_request_message",
"body": {
"text": "Hello! Please share your pickup location so we can send you a cab."
},
"action": {
"name": "send_location"
}
}
}
]
}
}
]
}
}
Interactive message Flows
In the example below, we send a WhatsApp Flows button message.
{
"messages": {
"msg": [
{
"body": {
"type": "auto",
"content": "Fallback Text"
},
"to": [
{
"number": "00316012345678"
}
],
"from": "00316098765432",
"allowedChannels": [
"WhatsApp"
],
"richContent": {
"conversation": [
{
"interactive": {
"type": "flow",
"header": {
"type": "text",
"text": "Flow message header"
},
"body": {
"text": "Flow message body"
},
"footer": {
"text": "Flow message footer"
},
"action": {
"name": "flow",
"parameters": {
"flow_message_version": "3",
"flow_token": "your-flow-token",
"flow_id": "your-flow-id",
"flow_cta": "Button title!",
"flow_action": "navigate",
"flow_action_payload": {
"screen": "your-flow-id",
"data": {
"options-field": "optional-value"
}
}
}
}
}
}
]
}
}
]
}
}
Interactive Call Permission Request message
To place a call to your WhatsApp customers, you must obtain their explicit permission, which can be temporary or permanent. Only your customer can grant or revoke this permission, and permanent permissions will be stored until revoked.
Limitations per business phone number
- Temporary permissions last 7 days (168 hours).
- Permanent permissions do not expire but can be revoked by the user.
- Maximum of 100 connected calls per business phone number every 24 hours.
To ensure an optimal user experience, specific limits are enforced for permission requests and call handling. You are allowed to send a maximum of one permission request within a 24-hour period and up to two requests within seven days. These limits reset after any connected call, whether initiated by you or your customer.
For unanswered or rejected calls, two consecutive unanswered calls will trigger a system message advising your customer to reconsider the approved permission. If four consecutive calls go unanswered, the approved permission will be automatically revoked. Your customers retain the ability to update their permissions again if they choose to do so.
Example of interactive call permission request
In the example below, we send a call permission request message. The message may include a header, footer, and body, all of which are optional. While the body is optional, it is strongly recommended to include it to provide context for your customers.
{
"messages": {
"msg": [
{
"from": "00316098765432",
"to": [
{
"number": "00316012345678"
}
],
"body": {
"type": "auto",
"content": "This is a WhatsApp message"
},
"allowedChannels": [
"WhatsApp"
],
"richContent": {
"conversation": [
{
"interactive": {
"type": "call_permission_request",
"action": {
"name": "call_permission_request"
},
"body": {
"text": "your-body-text"
}
}
}
]
}
}
]
}
}
Updated 5 days ago