Skip to main content
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

ParameterTypeRequiredDescription
flowIdstringYesWhatsApp Flow ID from your Meta account
flowTokenstringYesUnique token for session tracking
flowActionstringNo"navigate" (default) or "data_exchange"
flowActionPayloadobjectNoInitial 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:
TypeFieldsDescription
texttextPlain text header (60 chars max)
imagemediaIdImage from uploaded media
videomediaIdVideo from uploaded media
documentmediaId, filenameDocument 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

TypeBest For
ButtonsQuick decisions, ratings, confirmations (up to 3 options)
ListsMenus, categories, many options organized by group
CTA URLExternal links, tracking pages, payment portals
Location RequestStore finders, delivery, service areas
FlowsMulti-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.