Interactive Messages

Interactive messages let you present customers with structured choices -- buttons for quick replies or lists for browsable menus. These are supported across multiple channels through a single unified API.

Required Scopes

Scope	Purpose
messages:create	Send interactive messages

Channel Capabilities

Not all channels support all interactive features. Check before sending:

Feature	WhatsApp	Messenger	Instagram	Telegram	SMS	Email	Live Chat
Buttons	Yes (3 max)	Yes	Yes	Yes	No	No	Yes
List	Yes	No	No	No	No	No	Yes

tip

Use the Channel Capabilities endpoint (GET /api/v1/channels/{channel_id}/capabilities) to programmatically check what a specific channel supports before sending.

Button Messages

Button messages present up to 3 quick-reply options that customers can tap.

POST /api/v1/messages/send/interactive

Request Body

Field	Type	Required	Description
channel_id	string	Yes	The channel to send through
contact_id	string	Yes	The recipient contact
type	string	Yes	Must be buttons
header	object	No	Optional header (text, image, video, or document)
body	string	Yes	Main message text
footer	string	No	Footer text (smaller, muted)
buttons	array	Yes	Array of button objects (max 3)

Each button object:

Field	Type	Required	Description
id	string	Yes	Unique button identifier (returned when customer taps)
title	string	Yes	Button label (max 20 characters)

curl

curl -X POST "https://api.sendseven.com/api/v1/messages/send/interactive" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "channel_wa_001",
    "contact_id": "contact_xyz789",
    "type": "buttons",
    "header": {
      "type": "text",
      "text": "Order Support"
    },
    "body": "How can we help you with your order?",
    "footer": "Reply within 24 hours",
    "buttons": [
      {"id": "track_order", "title": "Track My Order"},
      {"id": "return_item", "title": "Return an Item"},
      {"id": "speak_agent", "title": "Speak to Agent"}
    ]
  }'

Python

import requests

BASE_URL = "https://api.sendseven.com/api/v1"
HEADERS = {
    "Authorization": "Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00",
    "Content-Type": "application/json",
}

response = requests.post(
    f"{BASE_URL}/messages/send/interactive",
    headers=HEADERS,
    json={
        "channel_id": "channel_wa_001",
        "contact_id": "contact_xyz789",
        "type": "buttons",
        "body": "Was your issue resolved?",
        "buttons": [
            {"id": "yes", "title": "Yes, thank you!"},
            {"id": "no", "title": "No, I need more help"},
        ],
    },
)
print(response.json())

Response

{
  "id": "msg_int_001",
  "conversation_id": "conv_abc123",
  "contact_id": "contact_xyz789",
  "channel_id": "channel_wa_001",
  "type": "interactive",
  "interactive_type": "buttons",
  "status": "sent",
  "created_at": "2026-02-10T17:00:00Z"
}

List Messages

List messages display a menu with categorized options that customers can browse and select from. These are ideal for presenting multiple choices organized by category.

info

List messages are currently supported on WhatsApp and Live Chat only.

Request Body

Field	Type	Required	Description
channel_id	string	Yes	The channel to send through
contact_id	string	Yes	The recipient contact
type	string	Yes	Must be list
body	string	Yes	Main message text
button_text	string	Yes	Text on the button that opens the list
sections	array	Yes	Array of section objects

Each section object:

Field	Type	Required	Description
title	string	Yes	Section heading
rows	array	Yes	Array of row items

Each row object:

Field	Type	Required	Description
id	string	Yes	Unique row identifier
title	string	Yes	Row title (max 24 characters)
description	string	No	Row description (max 72 characters)

curl

curl -X POST "https://api.sendseven.com/api/v1/messages/send/interactive" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "channel_wa_001",
    "contact_id": "contact_xyz789",
    "type": "list",
    "body": "Choose a department to connect with:",
    "button_text": "View Departments",
    "sections": [
      {
        "title": "Sales",
        "rows": [
          {"id": "new_quote", "title": "Get a Quote", "description": "Request pricing for our products"},
          {"id": "enterprise", "title": "Enterprise Sales", "description": "For orders over 1000 units"}
        ]
      },
      {
        "title": "Support",
        "rows": [
          {"id": "technical", "title": "Technical Support", "description": "Help with product issues"},
          {"id": "billing", "title": "Billing Support", "description": "Invoice and payment questions"}
        ]
      }
    ]
  }'

Response

{
  "id": "msg_int_002",
  "conversation_id": "conv_abc123",
  "contact_id": "contact_xyz789",
  "channel_id": "channel_wa_001",
  "type": "interactive",
  "interactive_type": "list",
  "status": "sent",
  "created_at": "2026-02-10T17:05:00Z"
}

Header Types

The optional header object supports multiple formats:

Text header:

{"type": "text", "text": "Welcome"}

Image header:

{"type": "image", "url": "https://example.com/banner.jpg"}

Video header:

{"type": "video", "url": "https://example.com/demo.mp4"}

Document header:

{"type": "document", "url": "https://example.com/catalog.pdf", "filename": "catalog.pdf"}

Error Responses

Status	Error Code	Description
400	VALIDATION_ERROR	Invalid message format or unsupported feature for channel
401	INVALID_TOKEN	Missing or invalid authentication token
403	INSUFFICIENT_SCOPE	Token lacks required scope
404	RESOURCE_NOT_FOUND	Channel, contact, or message not found
422	VALIDATION_ERROR	Feature not supported by this channel type

Example error:

{
  "detail": "List messages are not supported on Messenger channels",
  "error_code": "VALIDATION_ERROR"
}

Next Steps

• Carousel Messages -- multi-card scrollable carousels
• Reactions -- add emoji reactions to messages
• WhatsApp Interactive Messages -- WhatsApp-specific details