Interactive Messages

Convers8 allows you to send interactive messages to your WhatsApp contacts, including list messages and reply buttons. This guide covers how to use the interactive messaging API.

Authentication

All API requests must include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Base URL

https://waba-v1.convers8.africa

Interactive Message Types

Convers8 supports the following interactive message types:

• List Messages: Messages with a list of selectable options
• Reply Buttons: Messages with up to 3 quick reply buttons

Sending List Messages

List messages allow you to present a menu of options to your customers.

Endpoint

POST /whatsapp/message/interactive-list

Request Body

Property	Type	Description
to	string	The recipient's phone number in international format
name	string	The recipient's name
content	object	An object containing the message content
content.header	string	(Optional) The header text
content.body	string	The main message text
content.footer	string	(Optional) The footer text
content.action	object	The action object containing the button and sections
content.action.button	string	The text for the main button
content.action.sections	array	An array of section objects

Each section object has the following properties:

Property	Type	Description
title	string	The title of the section
rows	array	An array of row objects

Each row object has the following properties:

Property	Type	Description
id	string	A unique identifier for the row
title	string	The title of the row
description	string	(Optional) A description for the row

Example Request

{
  "to": "+1234567890",
  "name": "Customer Name",
  "content": {
    "header": "Menu Options",
    "body": "Please select an option from the list below",
    "footer": "Powered by Convers8",
    "action": {
      "button": "View Options",
      "sections": [
        {
          "title": "Services",
          "rows": [
            {
              "id": "service_1",
              "title": "Customer Support",
              "description": "Get help from our team"
            },
            {
              "id": "service_2",
              "title": "Sales Inquiry",
              "description": "Talk to our sales team"
            }
          ]
        },
        {
          "title": "Products",
          "rows": [
            {
              "id": "product_1",
              "title": "Product Catalog",
              "description": "Browse our products"
            },
            {
              "id": "product_2",
              "title": "New Arrivals",
              "description": "See what's new"
            }
          ]
        }
      ]
    }
  }
}

cURL Example

curl --request POST \
     --url https://waba-v1.convers8.africa/whatsapp/message/interactive-list \
     --header 'Authorization: Bearer YOUR_API_KEY' \
     --header 'Content-Type: application/json' \
     --data '{
       "to": "+1234567890",
       "name": "Customer Name",
       "content": {
         "header": "Menu Options",
         "body": "Please select an option from the list below",
         "footer": "Powered by Convers8",
         "action": {
           "button": "View Options",
           "sections": [
             {
               "title": "Services",
               "rows": [
                 {
                   "id": "service_1",
                   "title": "Customer Support",
                   "description": "Get help from our team"
                 },
                 {
                   "id": "service_2",
                   "title": "Sales Inquiry",
                   "description": "Talk to our sales team"
                 }
               ]
             }
           ]
         }
       }
     }'

Sending Reply Button Messages

Reply button messages allow you to present up to 3 quick reply buttons to your customers.

Endpoint

POST /whatsapp/message/interactive-reply

Request Body

Property	Type	Description
to	string	The recipient's phone number in international format
name	string	The recipient's name
content	object	An object containing the message content
content.type	string	Must be "button"
content.header	object	(Optional) The header object
content.body	object	The body object
content.action	object	The action object containing the buttons

The header object has the following properties:

Property	Type	Description
type	string	The type of header (e.g., "text")
text	string	The header text

The body object has the following properties:

Property	Type	Description
text	string	The main message text

The action object has the following properties:

Property	Type	Description
buttons	array	An array of button objects (maximum 3)

Each button object has the following properties:

Property	Type	Description
type	string	Must be "reply"
reply	object	The reply object

The reply object has the following properties:

Property	Type	Description
id	string	A unique identifier for the button
title	string	The button text

Example Request

{
  "to": "+1234567890",
  "name": "Customer Name",
  "content": {
    "type": "button",
    "header": {
      "type": "text",
      "text": "Feedback Request"
    },
    "body": {
      "text": "How would you rate our service?"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "rating_good",
            "title": "Good"
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "rating_average",
            "title": "Average"
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "rating_poor",
            "title": "Poor"
          }
        }
      ]
    }
  }
}

cURL Example

curl --request POST \
     --url https://waba-v1.convers8.africa/whatsapp/message/interactive-reply \
     --header 'Authorization: Bearer YOUR_API_KEY' \
     --header 'Content-Type: application/json' \
     --data '{
       "to": "+1234567890",
       "name": "Customer Name",
       "content": {
         "type": "button",
         "header": {
           "type": "text",
           "text": "Feedback Request"
         },
         "body": {
           "text": "How would you rate our service?"
         },
         "action": {
           "buttons": [
             {
               "type": "reply",
               "reply": {
                 "id": "rating_good",
                 "title": "Good"
               }
             },
             {
               "type": "reply",
               "reply": {
                 "id": "rating_average",
                 "title": "Average"
               }
             },
             {
               "type": "reply",
               "reply": {
                 "id": "rating_poor",
                 "title": "Poor"
               }
             }
           ]
         }
       }
     }'

Response Format

All API endpoints return a JSON response with the following structure:

{
  "success": true,
  "message": "Message sent successfully",
  "data": {
    "messageId": "wamid.abcdefghijklmnopqrstuvwxyz"
  }
}

Error Handling

In case of an error, the response will look like:

{
  "success": false,
  "message": "Error message",
  "error": {
    "code": "error_code",
    "details": "Error details"
  }
}

Common error codes include:

• invalid_parameter: One or more parameters in the request are invalid
• unauthorized: Invalid or missing API key
• rate_limit_exceeded: Too many requests in a short period
• interactive_message_invalid: The interactive message structure is invalid

Limitations

• List messages can have a maximum of 10 sections
• Each section can have a maximum of 10 rows
• Reply button messages can have a maximum of 3 buttons
• Button titles are limited to 20 characters
• The body text is limited to 1024 characters

Best Practices

1. Keep it Simple: Use clear, concise options that are easy to understand.
2. Button Text: Keep button text short and descriptive.
3. User Experience: Design interactive messages with the user experience in mind.
4. Error Handling: Implement proper error handling to manage API errors gracefully.
5. Testing: Test your interactive messages on different devices to ensure they display correctly.