WhatsApp Interactive Messages

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.

Endpoint

Headers

Name
contentType
Type
string
Description
This should be set to application/json.
Name
apikey
Type
string
Description
Find your API key under your login account.

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:

Required attributes

Name
body
Type
object
Description
Your message’s body. Maximum of 1024 characters.
Name
action
Type
object
Description
You must add at least one button, and include type, title, and id for your buttons.
You cannot add more than 3 buttons. Maximun of 20 characters for title.
You cannot have leading or trailing spaces when setting the ID.
Inside action, you must nest:
- a button field with your button’s content, maximum of 20 characters.
- at least one section object (maximum of 10) with a maximum of 24 characters for the title for section.
- Inside section, you must add at least one rows object. Maximum of 24 characters for the title for a row and maximum of 72 characters for the description for a row.

Optional attributes

Name
header
Type
object
Description
If you decide to include it, you must set the header’s type to text and add a text field with the desired content. Maximum of 60 characters.
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.
Name
footer
Type
object
Description
Maximum of 60 characters.

Example

{
"recipient_type": "individual",
"to" : "whatsapp-id",
"type": "interactive" 
    "interactive":{
        "type": "list" | "button" | ...,
        "header": {},
        "body": {},
        "footer": {},
        "action": {}
    }
}

Action 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" 
      }
    }
  ] 
}

Header Example

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

POST

Reply Buttons (without header)

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

Required attributes

Name
body
Type
object
Description
Your message’s body. Maximum of 1024 characters.
Name
action
Type
object
Description
You must add at least one button, and include type, title, and id for your buttons.
You cannot add more than 3 buttons. Maximun of 20 characters for title.

Optional attributes

Name
footer
Type
object
Description
Maximum of 60 characters.

Request

POST

   curl -P - /v1/whatsapp\
  -H 'apikey':'string'
  -H "Content-Type: application/json" \
  -d '{
        "recipient_type": "individual",
        "from": "+91XXXXXXXXXX",
        "to": "+91XXXXXXXXXX",
        "type": "interactive",
        "interactive": {
          "type": "button",
          "body": {
            "text": "How would you rate your experience?"
          },
          "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"
                }
              }
            ]
          }
        }
    }'

POST

Reply Buttons (with text header)

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

Required attributes

Name
body
Type
object
Description
Your message’s body. Maximum of 1024 characters.
Name
action
Type
object
Description
You must add at least one button, and include type, title, and id for your buttons.
You cannot add more than 3 buttons. Maximun of 20 characters for title.

Optional attributes

Name
header
Type
object
Description
If you decide to include it, you must set the header’s type to text and add a text field with the desired content. Maximum of 60 characters.
For button interactive messages, you can use the following header types: text, video, image, or document.
Name
footer
Type
object
Description
Maximum of 60 characters.

Request

POST

   curl -P - /v1/whatsapp\
  -H 'apikey':'string'
  -H "Content-Type: application/json" \
  -d '{
        "recipient_type": "individual",
        "from": "+91XXXXXXXXXX",
        "to": "+91XXXXXXXXXX",
        "type": "interactive",
         "interactive": {
            "type": "button",
            "header": {
                "type": "text",
                "text": "your-header-content"
            },
            "body": {
                "text": "How would you rate your experience?"
            },
            "action": {
                "buttons": [
                    {
                        "type": "reply",
                        "reply": {
                            "id": "rate_good",
                            "title": "Good"
                        }
                    },
                    {
                        "type": "reply",
                        "reply": {
                            "id": "rate_avg",
                            "title": "Average"
                        }
                    },
                    {
                        "type": "reply",
                        "reply": {
                            "id": "rate_bad",
                            "title": "Bad"
                        }
                    }
                ]
           }
        }
    }'

POST

Reply Buttons (with media header)

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

Required attributes

Name
body
Type
object
Description
Your message’s body. Maximum of 1024 characters.
Name
action
Type
object
Description
You must add at least one button, and include type, title, and id for your buttons.
You cannot add more than 3 buttons. Maximun of 20 characters for title.

Optional attributes

Name
header
Type
object
Description
If you decide to include it, you must set the header’s type to text and add a text field with the desired content. Maximum of 60 characters.
For button interactive messages, you can use the following header types: text, video, image, or document.
Name
footer
Type
object
Description
Maximum of 60 characters.

Request

POST

   curl -P - /v1/whatsapp\
  -H 'apikey':'string'
  -H "Content-Type: application/json" \
  -d '{
        "recipient_type": "individual",
        "from": "+91XXXXXXXXXX",
        "to": "+91XXXXXXXXXX",
        "type": "interactive",
        "interactive": {
          "type": "button",
          "header": {
             "type": "image",
              "image": {
                 "link": "http(s)://the-url"
               }
           },
          "body": {
            "text": "How would you rate your experience?"
          },
          "footer": {
            "text": "Thanks for your feedback"
          },
          "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"
                }
              }
            ]
          }
        }
    }'

POST

List Messages

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

Required attributes

Name
body
Type
object
Description
Your message’s body. Maximum of 1024 characters.
Name
action
Type
object
Description
Inside action, you must nest:
- a button field with your button’s content, maximum of 20 characters.
- at least one section object (maximum of 10) with a maximum of 24 characters for the title for section.
Inside section, you must add at least one rows object. Maximum of 24 characters for the title for a row and maximum of 72 characters for the description for a row.

Optional attributes

Name
header
Type
object
Description
If you decide to include it, you must set the header’s type to text and add a text field with the desired content. Maximum of 60 characters.
Name
footer
Type
object
Description
Maximum of 60 characters.

Request

POST

   curl -P - /v1/whatsapp\
  -H 'apikey':'string'
  -H "Content-Type: application/json" \
  -d '{
      "recipient_type": "individual",
      "from": "+91XXXXXXXXXX",
      "to": "+91XXXXXXXXXX",
      "type": "interactive",
      "interactive": {
        "type": "list",
        "header": {
          "type": "text",
          "text": "Book a Service"
        },
        "body": {
          "text": "Choose a service or support option:"
        },
        "footer": {
          "text": "Your Service Center"
        },
        "action": {
          "button": "See Options",
          "sections": [
            {
              "title": "Services",
              "rows": [
                {
                  "id": "serv_1",
                  "title": "Cleaning",
                  "description": "Full home cleaning"
                },
                {
                  "id": "serv_2",
                  "title": "Plumbing",
                  "description": "Fix water leakage"
                }
              ]
            },
            {
              "title": "Support",
              "rows": [
                {
                  "id": "sup_1",
                  "title": "Technical Support",
                  "description": "For devices"
                },
                {
                  "id": "sup_2",
                  "title": "Account Support",
                  "description": "For account issues"
                }
              ]
            }
          ]
        }
      }
    }'

POST

Location Request Messages

Location request messages contain body text and a Send location button that users can tap. Tapping the button displays a location sharing screen which the user can then use to share their location.

To send a location request message, first assemble an interactive object with text you wish to display in the message:

Required attributes

Name
body
Type
object
Description
Your message’s body. Maximum of 1024 characters.
Name
action
Type
object
Description
Inside action, you must nest:
- a name field with button name like (send_location).

Optional attributes

Name
footer
Type
object
Description
Maximum of 60 characters.

Request

POST

  curl -P - /v1/whatsapp\
  -H 'apikey':'string'
  -H "Content-Type: application/json" \
  -d '{
      "recipient_type": "individual",
      "from": "+91XXXXXXXXXX",
      "to": "+91XXXXXXXXXX",
      "type": "interactive",
      "interactive": {
        "type": "location_request_message",
        "body": {
          "text": "Can you please send your location"
        },
        "footer": {
          "text": " Tapping the button you can share your location."
        },
        "action": {
          "name": "send_location"               
        }
      }
    }'

POST

Text Messages

To send a simple text message, first assemble an object with type text ..

Required attributes

Name
body
Type
object
Description
Your message’s body. Maximum of 1024 characters.

Request

POST

  curl -P - /v1/whatsapp\
  -H 'apikey':'string'
  -H "Content-Type: application/json" \
  -d '{
      "recipient_type": "individual",
      "from": "+91XXXXXXXXXX",
      "to": "+91XXXXXXXXXX",
      "type": "text",
      "text": {
          "body": "Not Working"
             },
    }'

POST

Image Messages

To send a simple image message, first assemble an object with type image ..

Required attributes

Name
link
Type
string
Description
The protocol and URL of the media to be sent. Use only with HTTP/HTTPS URLs.
Do not use this field when message type is set to text.

Optional attributes

Name
caption
Type
string
Description
this field is is limited to 1024 characters. Captions are currently not supported for document media.

Request

POST

  curl -P - /v1/whatsapp\
  -H 'apikey':'string'
  -H "Content-Type: application/json" \
  -d '{
      "recipient_type": "individual",
      "from": "+91XXXXXXXXXX",
      "to": "+91XXXXXXXXXX",
      "type": "image",
      "image": {
         "link": "http(s)://the-url",
         "caption": "Testing"
       }
    }'

POST

Video Messages

To send a simple video message, first assemble an object with type video ..

Required attributes

Name
link
Type
string
Description
The protocol and URL of the media to be sent. Use only with HTTP/HTTPS URLs.
Do not use this field when message type is set to text.

Optional attributes

Name
caption
Type
string
Description
this field is is limited to 1024 characters. Captions are currently not supported for document media.

Request

POST

  curl -P - /v1/whatsapp\
  -H 'apikey':'string'
  -H "Content-Type: application/json" \
  -d '{
      "recipient_type": "individual",
      "from": "+91XXXXXXXXXX",
      "to": "+91XXXXXXXXXX",
      "type": "video",
      "video": {
         "link": "http(s)://the-url",
         "caption": " Testing"
       }
    }'

POST

Document Messages

To send a simple document message, first assemble an object with type document ..

Required attributes

Name
link
Type
string
Description
The protocol and URL of the media to be sent. Use only with HTTP/HTTPS URLs.
Do not use this field when message type is set to text.

Optional attributes

Name
caption
Type
string
Description
this field is is limited to 1024 characters. Captions are currently not supported for document media.

Request

POST

  curl -P - /v1/whatsapp\
  -H 'apikey':'string'
  -H "Content-Type: application/json" \
  -d '{
      "recipient_type": "individual",
      "from": "+91XXXXXXXXXX",
      "to": "+91XXXXXXXXXX",
      "type": "document",
      "document": {
         "link": "http(s)://the-url",
         "caption": " Testing"
       }
    }'