Sending Interactive Messages

Interactive messages allow users to respond with button clicks, list selections, or other actions, making conversations more engaging and efficient.

Button Messages

Send a message with up to 3 quick reply buttons:

Send Button Message

curl -X POST https://api.buildwithchirp.com/v1/whatsapp/messages \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543",
    "type": "interactive",
    "interactive": {
      "type": "buttons",
      "body": "How would you rate your experience?",
      "buttons": [
        { "id": "rating_great", "title": "Great!" },
        { "id": "rating_ok", "title": "It was OK" },
        { "id": "rating_bad", "title": "Not good" }
      ]
    }
  }'

Button Constraints

Maximum 3 buttons per message
Button titles: 20 characters max
Button IDs: 256 characters max

List Messages

Send a message with a list of options organized into sections:

Send List Message

curl -X POST https://api.buildwithchirp.com/v1/whatsapp/messages \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543",
    "type": "interactive",
    "interactive": {
      "type": "list",
      "body": "Please select a department:",
      "buttonText": "View Options",
      "sections": [
        {
          "title": "Sales",
          "rows": [
            { "id": "sales_new", "title": "New Inquiry", "description": "Start a new sales conversation" },
            { "id": "sales_existing", "title": "Existing Order", "description": "Questions about your order" }
          ]
        },
        {
          "title": "Support",
          "rows": [
            { "id": "support_tech", "title": "Technical Help", "description": "Get help with technical issues" },
            { "id": "support_billing", "title": "Billing", "description": "Payment and invoice questions" }
          ]
        }
      ]
    }
  }'

List Constraints

Maximum 10 sections
Maximum 10 rows per section
Section titles: 24 characters max
Row titles: 24 characters max
Row descriptions: 72 characters max

CTA URL Button

Send a message with a call-to-action URL button that opens a link when tapped:

Send CTA URL Message

curl -X POST https://api.buildwithchirp.com/v1/whatsapp/messages \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543",
    "type": "interactive",
    "interactive": {
      "type": "cta_url",
      "body": "Your order is ready! Track your shipment:",
      "url": "https://example.com/track/12345",
      "footer": "Delivery expected within 3-5 business days"
    }
  }'

The CTA URL button is ideal for:

Order tracking links
Payment pages
Support portals
Product pages

Location Request

Request the user’s current location:

Send Location Request

curl -X POST https://api.buildwithchirp.com/v1/whatsapp/messages \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543",
    "type": "interactive",
    "interactive": {
      "type": "location_request",
      "body": "Please share your location so we can find stores near you."
    }
  }'

When the user taps the button, WhatsApp prompts them to share their location. You’ll receive the coordinates in a webhook.

WhatsApp Flows

Trigger a WhatsApp Flow for complex multi-step interactions:

Send Flow Message

curl -X POST https://api.buildwithchirp.com/v1/whatsapp/messages \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543",
    "type": "interactive",
    "interactive": {
      "type": "flow",
      "body": "Complete your booking in just a few steps.",
      "flowId": "1234567890",
      "flowToken": "unique_session_token",
      "flowAction": "navigate",
      "flowActionPayload": {
        "screen": "BOOKING_START",
        "data": { "service_type": "consultation" }
      },
      "header": {
        "type": "text",
        "text": "Book an Appointment"
      },
      "footer": "Powered by Chirp"
    }
  }'

Flow Parameters

Parameter	Type	Required	Description
`flowId`	string	Yes	WhatsApp Flow ID from your Meta account
`flowToken`	string	Yes	Unique token for session tracking
`flowAction`	string	No	`"navigate"` (default) or `"data_exchange"`
`flowActionPayload`	object	No	Initial data to pass to the flow

WhatsApp Flows must be created and published in your Meta Business account before you can trigger them via the API.

Optional Headers and Footers

Most interactive messages support optional headers and footers:

Interactive with Header and Footer

curl -X POST https://api.buildwithchirp.com/v1/whatsapp/messages \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": "+15559876543",
    "type": "interactive",
    "interactive": {
      "type": "buttons",
      "header": {
        "type": "text",
        "text": "Order Confirmation"
      },
      "body": "Your order #12345 is confirmed. What would you like to do?",
      "footer": "Reply within 24 hours",
      "buttons": [
        { "id": "track", "title": "Track Order" },
        { "id": "modify", "title": "Modify Order" },
        { "id": "cancel", "title": "Cancel" }
      ]
    }
  }'

Header Types

Headers can contain text or media:

Type	Fields	Description
`text`	`text`	Plain text header (60 chars max)
`image`	`mediaId`	Image from uploaded media
`video`	`mediaId`	Video from uploaded media
`document`	`mediaId`, `filename`	Document from uploaded media

Response

All interactive messages return the same response format:

Response

{
  "id": "msg_wa_2DbBs7GWhGvVNJGrDXr5RG0mBWI",
  "from": "+15551234567",
  "to": "+15559876543",
  "type": "interactive",
  "status": "queued",
  "timestamp": "2024-01-15T12:00:00.000Z"
}

Handling User Responses

When a user interacts with buttons or lists, you receive a webhook with the selection:

Button Reply Webhook

{
  "event": "messages.whatsapp.received",
  "timestamp": "2024-01-15T12:05:00.000Z",
  "data": {
    "message": {
      "id": "msg_wa_2DbBs7GWhGvVNJGrDXr5RG0mBWI",
      "from": "+15559876543",
      "to": "+15551234567",
      "type": "interactive",
      "direction": "inbound",
      "interactive": {
        "type": "button_reply",
        "buttonReply": {
          "id": "rating_great",
          "title": "Great!"
        }
      }
    }
  }
}

List Reply Webhook

{
  "event": "messages.whatsapp.received",
  "timestamp": "2024-01-15T12:05:00.000Z",
  "data": {
    "message": {
      "id": "msg_wa_2DbBs7GWhGvVNJGrDXr5RG0mBWI",
      "from": "+15559876543",
      "to": "+15551234567",
      "type": "interactive",
      "direction": "inbound",
      "interactive": {
        "type": "list_reply",
        "listReply": {
          "id": "sales_new",
          "title": "New Inquiry",
          "description": "Start a new sales conversation"
        }
      }
    }
  }
}

Use the id field to determine which option the user selected and respond accordingly.

Use Cases

Type	Best For
Buttons	Quick decisions, ratings, confirmations (up to 3 options)
Lists	Menus, categories, many options organized by group
CTA URL	External links, tracking pages, payment portals
Location Request	Store finders, delivery, service areas
Flows	Multi-step forms, bookings, complex workflows

Keep button text short and action-oriented. Use lists when you have more than 3 options or need to organize choices into categories.

Getting Started

Concepts

Webhooks

SMS

WhatsApp

Calling

Resources

Sending Interactive Messages

Button Messages

Button Constraints

List Messages

List Constraints

CTA URL Button

Location Request

WhatsApp Flows

Flow Parameters

Optional Headers and Footers

Header Types

Response

Handling User Responses

Use Cases

​Button Messages

​Button Constraints

​List Messages

​List Constraints

​CTA URL Button

​Location Request

​WhatsApp Flows

​Flow Parameters

​Optional Headers and Footers

​Header Types

​Response

​Handling User Responses

​Use Cases

Button Messages

Button Constraints

List Messages

List Constraints

CTA URL Button

Location Request

WhatsApp Flows

Flow Parameters

Optional Headers and Footers

Header Types

Response

Handling User Responses

Use Cases