Carousel Messages

Carousel messages display multiple cards that recipients can scroll through horizontally. Each card can include a title, subtitle, image, and action buttons. They are ideal for showcasing products, plans, or options.

Required Scopes

Scope	Purpose
messages:create	Send carousel messages

Channel Support

Channel	Support	Implementation
WhatsApp	Yes	Template-based carousels
Messenger	Yes	Generic template carousels
Instagram	Yes	Generic template carousels
Telegram	No	Not supported
SMS	No	Not supported
Email	No	Not supported

Send a Carousel

POST /api/v1/messages/send/carousel

Request Body

Field	Type	Required	Description
channel_id	string	Yes	The channel to send through
contact_id	string	Yes	The recipient contact
cards	array	Yes	Array of carousel cards (2-10 cards)

Card object:

Field	Type	Required	Description
title	string	Yes	Card title
subtitle	string	No	Card description
image_url	string	No	Card image URL
buttons	array	No	Card action buttons (max 3 per card)

Button object:

Field	Type	Required	Description
type	string	Yes	url (opens a link) or postback (sends data back)
title	string	Yes	Button label
url	string	Conditional	Required when type is url
payload	string	Conditional	Required when type is postback

curl

curl -X POST "https://api.sendseven.com/api/v1/messages/send/carousel" \
  -H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "channel_msngr_001",
    "contact_id": "contact_xyz789",
    "cards": [
      {
        "title": "Wireless Headphones",
        "subtitle": "Premium noise-cancelling - EUR 149",
        "image_url": "https://shop.example.com/images/headphones.jpg",
        "buttons": [
          {"type": "url", "title": "View Product", "url": "https://shop.example.com/headphones"},
          {"type": "postback", "title": "Add to Cart", "payload": "add_headphones"}
        ]
      },
      {
        "title": "Bluetooth Speaker",
        "subtitle": "Portable and waterproof - EUR 79",
        "image_url": "https://shop.example.com/images/speaker.jpg",
        "buttons": [
          {"type": "url", "title": "View Product", "url": "https://shop.example.com/speaker"},
          {"type": "postback", "title": "Add to Cart", "payload": "add_speaker"}
        ]
      },
      {
        "title": "Smart Watch",
        "subtitle": "Fitness tracking and notifications - EUR 249",
        "image_url": "https://shop.example.com/images/watch.jpg",
        "buttons": [
          {"type": "url", "title": "View Product", "url": "https://shop.example.com/watch"},
          {"type": "postback", "title": "Add to Cart", "payload": "add_watch"}
        ]
      }
    ]
  }'

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/carousel",
    headers=HEADERS,
    json={
        "channel_id": "channel_msngr_001",
        "contact_id": "contact_xyz789",
        "cards": [
            {
                "title": "Basic Plan",
                "subtitle": "Perfect for small teams. Starting at EUR 0/month.",
                "image_url": "https://example.com/images/basic.jpg",
                "buttons": [
                    {"type": "url", "title": "Learn More", "url": "https://example.com/basic"},
                    {"type": "postback", "title": "Choose Basic", "payload": "SELECT_BASIC"},
                ],
            },
            {
                "title": "Scale Plan",
                "subtitle": "For growing businesses. EUR 199/month minimum.",
                "image_url": "https://example.com/images/scale.jpg",
                "buttons": [
                    {"type": "url", "title": "Learn More", "url": "https://example.com/scale"},
                    {"type": "postback", "title": "Choose Scale", "payload": "SELECT_SCALE"},
                ],
            },
        ],
    },
)
print(response.json())

Response

{
  "id": "msg_car_001",
  "conversation_id": "conv_def456",
  "contact_id": "contact_xyz789",
  "channel_id": "channel_msngr_001",
  "type": "carousel",
  "card_count": 3,
  "status": "sent",
  "created_at": "2026-02-10T17:10:00Z"
}

warning

WhatsApp carousels use template-based carousels, which require an approved template. Messenger and Instagram use generic templates that can be sent freely within an active conversation.

Error Responses

Status	Error Code	Description
400	VALIDATION_ERROR	Invalid card data or unsupported on this channel
401	INVALID_TOKEN	Missing or invalid authentication token
403	INSUFFICIENT_SCOPE	Token lacks required scope
404	RESOURCE_NOT_FOUND	Channel or contact not found

Next Steps

• Interactive Messages -- button and list messages
• Reactions -- emoji reactions
• Send Text Messages -- plain text messaging