What interactive messages are

WhatsApp supports a set of interactive message types that work inside the 24-hour messaging window:

Reply buttons (button) — up to three tappable buttons that send a pre-filled reply back to your business when tapped. Useful for “Yes/No”, quick menu choices, or confirmation prompts.
List messages (list) — a tappable menu that expands into selectable options grouped into sections. Useful for FAQ pickers, category menus, or scheduling slots.
Product (product) — a single product card from your WhatsApp catalog.
Product list (product_list) — a multi-product catalog message.
Flow (flow) — a Cloud-API-only multi-step interactive flow.
Catalog message (catalog_message) — a Cloud-API-only message that opens your full WhatsApp catalog.

Interactive messages do not require template approval. They’re freeform messages, so they can only be sent inside the 24-hour messaging window after the customer’s last inbound message. Outside that window, use an approved template.

Before you start

You need:

A WhatsApp channel in Active status.
An open conversation with the recipient, started by a customer within the last 24 hours.
The WhatsApp Business API key from the channel detail page.
The interactive API enabled on your account. If your account isn’t opted in, the endpoint returns HTTP 403. Contact Octopods support to enable it.

Endpoint

Send a POST request to:

POST https://api.octopods.io/api/v1/whatsapp/interactive

Authenticate with your WhatsApp Business API key in the X-Octopods-Auth header:

X-Octopods-Auth: <your-whatsapp-api-key>

Payload shape

The top-level body has two fields:

destination_phone — the recipient’s phone number in E.164 format.
waba_interactive_message — an object that contains the entire interactive payload (type, body, header, footer, and the type-specific action object).

Optional top-level fields:

open_intercom_conversation — true to automatically open a new Intercom conversation when the message is sent.
intercom_teammate_id — the ID of the Intercom user who should appear as the sender.

Reply buttons

Use type: "button" with up to three reply buttons. Each button sends a pre-filled response when the customer taps it.

{
  "destination_phone": "+15551234567",
  "waba_interactive_message": {
    "type": "button",
    "body": { "text": "Did your order arrive today?" },
    "action": {
      "buttons": [
        { "type": "reply", "reply": { "id": "yes_delivered", "title": "Yes, received" } },
        { "type": "reply", "reply": { "id": "no_missing", "title": "Not yet" } },
        { "type": "reply", "reply": { "id": "issue", "title": "There's a problem" } }
      ]
    }
  }
}

When the customer taps a button, WhatsApp sends an inbound message with the button’s id and title as the content. That message arrives in your Intercom or HubSpot inbox like any other inbound WhatsApp reply.

Limits: up to 3 buttons, each title up to 20 characters.

List messages

Use type: "list" to show a tappable menu. The customer sees a single button that, when tapped, opens a scrollable list of options.

{
  "destination_phone": "+15551234567",
  "waba_interactive_message": {
    "type": "list",
    "body": { "text": "Which topic would you like help with today?" },
    "action": {
      "button": "Pick a topic",
      "sections": [
        {
          "title": "Orders",
          "rows": [
            { "id": "track", "title": "Track my order" },
            { "id": "return", "title": "Return an item" }
          ]
        },
        {
          "title": "Account",
          "rows": [
            { "id": "password", "title": "Reset password" },
            { "id": "billing", "title": "Billing question" }
          ]
        }
      ]
    }
  }
}

Tapping a row sends an inbound message back with the selected row’s id and title.

Limits: up to 10 rows total, grouped into up to 10 sections. Each row’s title up to 24 characters; description up to 72 characters.

Product, product_list, flow, catalog_message

These types are also accepted under waba_interactive_message.type. Their payload shapes follow Meta’s published WhatsApp Cloud API documentation for each interactive type — pass the same body Meta expects under waba_interactive_message. flow and catalog_message are only available on Cloud API channels (not on Twilio WhatsApp).

Response

On success, Octopods returns details about the queued send:

{
  "request_id": "req_01HT5Q...",
  "message_id": "msg_01HT5Q...",
  "message_status_url": "https://api.octopods.io/api/v1/whatsapp/messages/msg_01HT5Q...",
  "phone_number": "+15551234567",
  "channel_message_id": "wamid.HBgLM..."
}

Handling the reply

When the customer taps a button or list option:

WhatsApp sends an inbound message with the selected option’s id and title.
The message appears as a new entry in the same conversation in your Intercom or HubSpot inbox.
If you’re reading replies programmatically (for example, through your customer platform’s webhooks), the interactive reply looks like a text message whose body is the option title.

Common errors

HTTP 403 — interactive messaging is an opt-in feature. Contact Octopods support to enable it on your account.
Outside messaging window — the last inbound message from the recipient was more than 24 hours ago. Send an approved template instead.
Validation errors — buttons, rows, or section counts exceed the limits above. The error response includes the specific validation failure.
Unauthorized — the X-Octopods-Auth header is missing, revoked, or from a different channel.

For the full numeric error-code table, see API Error Reference.

Sending WhatsApp Interactive Messages