Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.buildwithchirp.com/llms.txt

Use this file to discover all available pages before exploring further.

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.