> ## 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.
# Sending Interactive Messages
> Send WhatsApp messages with buttons, lists, CTA URLs, location requests, and flows
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:
```bash icon="terminal" title="Send Button Message" theme={null}
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:
```bash icon="terminal" title="Send List Message" theme={null}
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:
```bash icon="terminal" title="Send CTA URL Message" theme={null}
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:
```bash icon="terminal" title="Send Location Request" theme={null}
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:
```bash icon="terminal" title="Send Flow Message" theme={null}
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:
```bash icon="terminal" title="Interactive with Header and Footer" theme={null}
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:
```json icon="code" title="Response" theme={null}
{
"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:
```json icon="json" title="Button Reply Webhook" theme={null}
{
"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!"
}
}
}
}
}
```
```json icon="json" title="List Reply Webhook" theme={null}
{
"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.