Interactive Messages

Interactive messages allow the user to respond by clicking on buttons or selecting items from a list, instead of typing. They are supported on WhatsApp, Instagram, Messenger, and Telegram (with variations).

Availability by type and channel

Interactive type	WhatsApp	Instagram	Messenger	Telegram
Quick Reply (buttons)	✅	✅	✅	❌
Option list	✅	✅	✅	✅ (poll)
CTA URL (button with link)	✅	✅	✅	❌
Request location	✅	❌	❌	❌

Channel-specific fields

header and footer are only supported on WhatsApp. On Instagram, Messenger, and Telegram, only the body field is required.

---

Quick Reply (Response buttons)

Displays up to 3 quick reply buttons. When the user clicks, the button ID is sent back via webhook.

{
  "from": "channel-uuid",
  "to": "5511993986082",
  "content": {
    "interactive": {
      "type": "button",
      "header": {
        "type": "text",
        "text": "Customer support"
      },
      "body": {
        "text": "How can I help you?"
      },
      "footer": {
        "text": "Reply with an option"
      },
      "action": {
        "buttons": [
          { "type": "reply", "reply": { "id": "SUPPORT", "title": "Support" } },
          { "type": "reply", "reply": { "id": "SALES", "title": "Sales" } },
          { "type": "reply", "reply": { "id": "OTHER", "title": "Other" } }
        ]
      }
    }
  }
}

Header with image

The header can also be an image (WhatsApp):

"header": {
  "type": "image",
  "image": {
    "link": "https://example.com/banner.jpg"
  }
}

Or video:

"header": {
  "type": "video",
  "video": {
    "link": "https://example.com/presentation.mp4"
  }
}

Button fields

Field	Required	Description
type	✅	Always "reply"
reply.id	✅	Internal identifier (returned in the webhook)
reply.title	✅	Text displayed on the button (max 20 characters)

---

Option list

Displays a menu with sections and items. Ideal for service menus, FAQs, catalogs.

{
  "content": {
    "interactive": {
      "type": "list",
      "header": {
        "type": "text",
        "text": "Our Menu"
      },
      "body": {
        "text": "Choose a category"
      },
      "footer": {
        "text": "Available until 10 PM"
      },
      "action": {
        "button": "View options",
        "sections": [
          {
            "title": "Main courses",
            "rows": [
              { "id": "dish_1", "title": "Grilled steak", "description": "With fries and salad" },
              { "id": "dish_2", "title": "Shrimp risotto", "description": "Serving for 2 people" }
            ]
          },
          {
            "title": "Desserts",
            "rows": [
              { "id": "dessert_1", "title": "Chocolate lava cake", "description": "With vanilla ice cream" }
            ]
          }
        ]
      }
    }
  }
}

List fields

Field	Required	Description
action.button	✅	Text of the button that opens the list
sections	✅	Array of sections (minimum 1)
sections[].title	❌	Section title
rows[].id	✅	Identifier returned in the webhook
rows[].title	✅	Item text (max 24 characters)
rows[].description	❌	Item description (max 72 characters)

---

CTA URL (Button with external link)

Displays a button that opens a URL in the browser.

{
  "content": {
    "interactive": {
      "type": "cta_url",
      "header": {
        "type": "text",
        "text": "Visit our website"
      },
      "body": {
        "text": "Click the button below to access:"
      },
      "footer": {
        "text": "Available 24/7"
      },
      "action": {
        "button": "Access",
        "parameters": {
          "display_text": "Visit Site",
          "url": "https://example.com"
        }
      }
    }
  }
}

---

Request user location (WhatsApp)

Asks the user to share their current location.

{
  "content": {
    "interactive": {
      "type": "location_request_message",
      "body": {
        "text": "To calculate shipping, please share your location."
      },
      "action": {
        "name": "send_location"
      }
    }
  }
}

The location shared by the user will arrive via webhook in the received message payload.

---

Common optional fields

Field	Description	Supported channels
header	Message header (text, image, etc.)	WhatsApp
footer	Plain text footer	WhatsApp
body	Message body (required)	All

---

User response via webhook

When the user interacts with a button or list, you receive via webhook a payload with the selected id:

{
  "type": "interactive",
  "interactive": {
    "type": "button_reply",
    "button_reply": {
      "id": "SUPPORT",
      "title": "Support"
    }
  }
}

Use the id to implement the logic of your service flow.