WhatsApp Interactive Messages

WhatsApp supports a rich set of interactive message types that let customers tap buttons, browse lists, and take actions directly in the chat. This guide covers WhatsApp-specific details and capabilities.

Required Scopes

Scope	Purpose
messages:create	Send interactive messages

WhatsApp Interactive Capabilities

Feature	Supported	Limits
Button messages	Yes	Max 3 buttons
List messages	Yes	Max 10 rows per section
Carousel	Yes	Template-based, 2-10 cards
Reactions	Yes	Any emoji
Contact cards	Yes	Full vCard support
Stickers	Yes	WebP, 512x512px

info

Interactive messages (buttons and lists) can only be sent within the 24-hour messaging window. Outside the window, use template messages instead.

Button Messages on WhatsApp

WhatsApp button messages support up to 3 quick-reply buttons with optional headers and footers.

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"}
    ]
  }'

Header Options

WhatsApp supports four header types for interactive messages:

Header Type	Description
text	Plain text header
image	Image displayed above the message body
video	Video displayed above the message body
document	Document attachment in the header

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

List Messages on WhatsApp

WhatsApp is the primary platform for list messages. Lists display a button that opens a scrollable menu of categorized options.

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": "Select a product category:",
    "button_text": "View categories",
    "sections": [
      {
        "title": "Electronics",
        "rows": [
          {"id": "phones", "title": "Smartphones", "description": "Latest smartphones"},
          {"id": "laptops", "title": "Laptops", "description": "Work and gaming laptops"}
        ]
      },
      {
        "title": "Accessories",
        "rows": [
          {"id": "cases", "title": "Phone Cases"},
          {"id": "chargers", "title": "Chargers & Cables"}
        ]
      }
    ]
  }'

tip

List messages are excellent for customer self-service flows -- routing to departments, selecting products, or choosing appointment times.

Contact Cards

Send a contact card (vCard) with phone numbers, emails, and organization details. WhatsApp only.

curl -X POST "https://api.sendseven.com/api/v1/messages/send/contact-card" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "channel_wa_001",
    "contact_id": "contact_xyz789",
    "card": {
      "name": {
        "first_name": "Alice",
        "last_name": "Johnson",
        "formatted_name": "Alice Johnson"
      },
      "phones": [
        {"phone": "+14155551234", "type": "WORK"}
      ],
      "emails": [
        {"email": "[email protected]", "type": "WORK"}
      ],
      "org": {
        "company": "Example Corp",
        "department": "Sales",
        "title": "Account Manager"
      }
    }
  }'

Stickers

Send sticker messages on WhatsApp. Stickers must be in WebP format.

curl -X POST "https://api.sendseven.com/api/v1/messages/send/sticker" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "channel_wa_001",
    "contact_id": "contact_xyz789",
    "sticker_url": "https://example.com/stickers/thumbs-up.webp"
  }'

Sticker requirements:

• Format: WebP
• Dimensions: 512x512 pixels
• Max file size: 100 KB (static) or 500 KB (animated)

WhatsApp vs. Other Channels

For the full cross-channel comparison of interactive features, see the Interactive Messages guide.

Feature	WhatsApp	Messenger	Instagram
Buttons	3 max	Yes	Yes
Lists	Yes	No	No
Carousel	Template-based	Generic template	Generic template
Contact cards	Yes	No	No
Stickers	Yes	Yes	No

Error Responses

Status	Error Code	Description
400	VALIDATION_ERROR	Invalid message format
401	INVALID_TOKEN	Missing or invalid authentication token
403	INSUFFICIENT_SCOPE	Token lacks required scope
404	RESOURCE_NOT_FOUND	Channel or contact not found
422	VALIDATION_ERROR	24-hour window expired; use a template instead

Next Steps

• Send a Template Message -- for messaging outside the 24h window
• Interactive Messages -- cross-channel interactive messaging
• Carousel Messages -- multi-card carousels