Skip to main content

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​

ScopePurpose
messages:createSend interactive messages

WhatsApp Interactive Capabilities​

FeatureSupportedLimits
Button messagesYesMax 3 buttons
List messagesYesMax 10 rows per section
Request contact infoYesSingle fixed-label button, no custom buttons
CarouselYesTemplate-based, 2-10 cards
ReactionsYesAny emoji
Contact cardsYesFull vCard support
StickersYesWebP, 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 TypeDescription
textPlain text header
imageImage displayed above the message body
videoVideo displayed above the message body
documentDocument 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.

Request a Phone Number (request_contact_info)​

A single-button message asking the recipient to share their own WhatsApp phone number. Use it when a workflow genuinely needs a phone number -- SMS notifications, a voice callback, identity checks -- and the contact does not have one on file.

This is the normal case for contacts who adopted a WhatsApp username: WhatsApp withholds their phone number from every webhook, so until they share it they are reachable on WhatsApp only. See Migrating to BSUIDs.

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": "request_contact_info",
    "body": "To send you delivery updates by SMS, please share your phone number."
  }'
  • Only body is used. The button label is set and localized by WhatsApp into the recipient's app language, so buttons and sections are rejected.
  • The tap does not produce a button-reply webhook. The number arrives as a contact-card message and is linked onto the contact automatically -- and if it already belonged to a separate contact record, the two are merged. See Duplicates & Merging.
  • Only a number the sender shares about themselves is linked. A forwarded third-party contact card is never attached to the sender.
  • Like other interactive messages, this can only be sent inside the 24-hour messaging window.

Contact Cards​

Send one or more contact cards (vCard) with phone numbers, emails, and organization details. WhatsApp only. contacts is a list of cards; name.formatted_name is required on each.

curl -X POST "https://api.sendseven.com/api/v1/messages/send/contacts" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "channel_wa_001",
    "contact_id": "contact_xyz789",
    "contacts": [
      {
        "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.

FeatureWhatsAppMessengerInstagram
Buttons3 maxYesYes
ListsYesNoNo
CarouselTemplate-basedGeneric templateGeneric template
Contact cardsYesNoNo
StickersYesYesNo

Error Responses​

Most errors return detail as a message string. See Error Handling for the response shapes.

StatusdetailDescription
400"Interactive messages are only supported on WhatsApp. ..."The channel does not support interactive messages
400"Duplicate button id '...'. ..."Two reply buttons share the same id
400"Contact does not have a WhatsApp ID or phone number"The contact can't be reached on WhatsApp
400{"error": "WHATSAPP_WINDOW_EXPIRED", "message": ...}WhatsApp: the 24-hour customer service window has closed. Send a template
400{"error": "WHATSAPP_NO_CUSTOMER_MESSAGE", "message": ...}WhatsApp: the contact has never written to you. Send a template
401"Invalid or expired API token"Token is invalid or expired
403"Missing required permission(s): messages:create"Token lacks the scope
404"Channel not found", "Contact not found"Unknown ID, or it belongs to another workspace
409{"error": "CHANNEL_DISCONNECTED", ...}The channel is disconnected
409{"error": "CONTACT_BLOCKED", ...}The contact is blocked
422list of field errorsInvalid request body, for example more than 3 buttons

When the 24-hour window has closed, the request is refused with 400 WHATSAPP_WINDOW_EXPIRED before anything is sent (the same check as POST /messages). If WhatsApp rejects a message that was sent, the request still returns 201 with status: "failed", the reason in error and WhatsApp's numeric code in error_code (for example 131047), and the message.failed webhook fires once. Outside the window, send a template instead.

Next Steps​