Send interactive menu (buttons, carousel, list, or poll)

This endpoint offers a unified interface for sending four main types of interactive messages:

• Buttons: For quick and direct actions
• Button Carousel: For a horizontal list of buttons with images
• Lists: For menus organized into sections
• Polls: For collecting opinions and voting

Tracking fields support: This endpoint also supports track_source and track_id documented in the “Send Message” tag.

Base Payload Structure

All requests follow this base structure:

{
  "number": "5511999999999",
  "type": "button|list|poll|carousel",
  "text": "Main message text",
  "choices": ["options based on the chosen type"],
  "footerText": "Footer text (optional for buttons and lists)",
  "listButton": "Button text (for lists)",
  "selectableCount": "Number of selectable options (polls only)"
}

Interactive Message Types

1. Buttons (type: “button”)

Creates interactive buttons with different action functionalities.

Specific Fields

• footerText: Optional text displayed below the main message
• choices: Array of options that will be converted into buttons

Button Formats

Each button can be configured using | (pipe) or \n (newline) as separators:

• Reply Button:

  • "text|id" or
  • "text\nid" or
  • "text" (ID will be equal to the text)

• Copy Button:

  • "text|copy:code" or
  • "text\ncopy:code"

• Call Button:

  • "text|call:+5511999999999" or
  • "text\ncall:+5511999999999"

• URL Button:

  • "text|https://example.com" or
  • "text|url:https://example.com"

Buttons with Image

To add an image to the buttons, use the imageButton field in the payload:

Example with Image

{
  "number": "5511999999999",
  "type": "button",
  "text": "Choose a product:",
  "imageButton": "[https://example.com/product1.jpg](https://example.com/product1.jpg)",
  "choices": [
    "Product A|prod_a",
    "More Info|[https://example.com/product-a](https://example.com/product-a)",
    "Product B|prod_b",
    "Call|call:+5511999999999"
  ],
  "footerText": "Featured products"
}

Support: The imageButton field accepts URLs or base64 images.

Complete Example

{
  "number": "5511999999999",
  "type": "button",
  "text": "How can we help?",
  "choices": [
    "Tech Support|support",
    "Place Order|order",
    "Our Website|[https://example.com](https://example.com)",
    "Contact Us|call:+5511999999999"
  ],
  "footerText": "Choose one of the options below"
}

Limitations and Compatibility

Important: When combining reply buttons with other types (call, url, copy) in the same message, the warning: “This message cannot be displayed on WhatsApp Web. Open WhatsApp on your phone to view it.” will be displayed.

2. Lists (type: “list”)

Creates menus organized in sections with selectable items.

Specific Fields

• listButton: Text of the button that opens the list
• footerText: Optional footer text
• choices: Array with sections and list items

Choices Format

• "[Section Title]": Starts a new section
• "text|id|description": List item with:
  • text: Item label
  • id: Unique identifier, optional
  • description: Additional optional descriptive text

Complete Example

{
  "number": "5511999999999",
  "type": "list",
  "text": "Product Catalog",
  "choices": [
    "[Electronics]",
    "Smartphones|phones|Latest releases",
    "Notebooks|notes|2024 Models",
    "[Accessories]",
    "Headphones|phones|Bluetooth and wired",
    "Cases|cases|Protection for your device"
  ],
  "listButton": "View Catalog",
  "footerText": "Prices subject to change"
}

3. Polls (type: “poll”)

Creates interactive voting polls.

Specific Fields

• selectableCount: Number of options that can be selected (default: 1)
• choices: Simple array with voting options

Complete Example

{
  "number": "5511999999999",
  "type": "poll",
  "text": "What time do you prefer for the appointment?",
  "choices": [
    "Morning (8am-12pm)",
    "Afternoon (1pm-5pm)",
    "Evening (6pm-10pm)"
  ],
  "selectableCount": 1
}

4. Carousel (type: “carousel”)

Creates a carousel of cards with images and interactive buttons.

Specific Fields

• choices: Array with carousel elements in the following order:
  • [Card Text]: Card text inside brackets
  • {URL or base64 of image}: Image inside curly braces
  • Card buttons (one per line):
    • "text|copy:code" for copy button
    • "text|https://url" for link button
    • "text|call:+number" for call button

Complete Example

{
  "number": "5511999999999",
  "type": "carousel",
  "text": "Meet our products",
  "choices": [
    "[Smartphone XYZ\nThe most advanced smartphone in the line]",
    "{[https://example.com/product1.jpg](https://example.com/product1.jpg)}",
    "Copy Code|copy:PROD123",
    "View on Site|[https://example.com/xyz](https://example.com/xyz)",
    "Contact Us|call:+5511999999999",
    "[Notebook ABC\nThe ideal notebook for professionals]",
    "{[https://example.com/product2.jpg](https://example.com/product2.jpg)}",
    "Copy Code|copy:NOTE456",
    "Buy Online|[https://example.com/abc](https://example.com/abc)",
    "Support|call:+5511988888888"
  ]
}

Note: We created another endpoint for carousel: /send/carousel, it works the same way but with a different payload format. See which one is easier for you.

Terms of Use

Interactive button and list features may be discontinued at any time without prior notice. We are not responsible for any changes or unavailability of these features.

Alternatives and Compatibility

Considering the dynamic nature of these resources, our endpoint was designed to facilitate migration between different message types (buttons, lists, and polls).

We recommend creating your flows flexibly, prepared to switch between different types.

In case of feature discontinuation, you can easily migrate to another message type by simply changing the “type” field in the payload, maintaining the same choices structure.