Send Carousel - RyzeAPI

Auth: TokenAccount or TokenInstance • Rate-limit: Global (100/min) • Idempotent: no

Description

Sends a message with a carousel of swipeable cards. Each card has a header (required title, with optional media via imageUrl or videoUrl), body.text (required), an optional footer and a few interactive buttons. Buttons accept four types: REPLY (default, returns the ID when clicked), URL (opens a link), CALL (dials a number) and COPY (copies a code). You can add message (text before the carousel) and footer (text below). Supports delay, replyTo and replyPrivate.

Examples

Simple carousel with REPLY buttons

Two cards with text and quick-reply buttons only.

curl -X POST "https://ryzeapi.cloud/api/message/carousel/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":  "5511999999999",
    "message": "Pick one of the plans below:",
    "footer":  "Promo valid until end of month.",
    "cards": [
      {
        "header": { "title": "Basic Plan" },
        "body":   { "text": "5 instances, email support." },
        "footer": "$49/month",
        "buttons": [
          { "displayText": "I want Basic", "id": "plan_basic", "type": "REPLY" }
        ]
      },
      {
        "header": { "title": "Pro Plan" },
        "body":   { "text": "20 instances, priority support, webhooks." },
        "footer": "$149/month",
        "buttons": [
          { "displayText": "I want Pro", "id": "plan_pro", "type": "REPLY" }
        ]
      }
    ]
  }'

Carousel with image header and URL buttons

imageUrl in the header and buttons of type URL (the id receives the URL to open).

curl -X POST "https://ryzeapi.cloud/api/message/carousel/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":  "5511999999999",
    "message": "Check out our products:",
    "cards": [
      {
        "header": {
          "title":    "Runner X Sneakers",
          "subtitle": "Limited edition",
          "imageUrl": "https://example.com/img/runner-x.jpg"
        },
        "body":   { "text": "High-performance cushioning, ideal for long runs." },
        "buttons": [
          { "displayText": "See details", "id": "https://store.example.com/runner-x", "type": "URL" },
          { "displayText": "Talk to seller", "id": "talk_seller_runner", "type": "REPLY" }
        ]
      }
    ]
  }'

Carousel with video header

videoUrl replaces imageUrl in the header. Use one of the two, not both.

curl -X POST "https://ryzeapi.cloud/api/message/carousel/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999999999",
    "cards": [
      {
        "header": {
          "title":    "Tutorial: how to activate",
          "videoUrl": "https://example.com/videos/onboarding.mp4"
        },
        "body":   { "text": "See in 30 seconds how to set up your first instance." },
        "buttons": [
          { "displayText": "Get started",     "id": "start_onboarding", "type": "REPLY" },
          { "displayText": "Call support",    "id": "+551130000000",    "type": "CALL" },
          { "displayText": "Copy coupon",     "id": "RYZE10",           "type": "COPY" }
        ]
      }
    ]
  }'

Success response

The returned messageType is interactive (a carousel is a variation of WhatsApp’s interactive message), and content carries an aggregated description ("<message> - Carousel with N card(s)") used by history. The individual cards do not come back in the response, store the messageId to correlate with clicks via webhook.

200 OK

{
  "success": true,
  "message": "Carousel sent successfully",
  "status":  "sent",
  "data": {
    "messageId":   "3EB08FCF27E532F1E4E4",
    "direction":   "sent",
    "messageType": "interactive",
    "content":     "Pick one of the plans below: - Carousel with 3 card(s)",
    "source":      "api",
    "timestamp":   "2026-04-30T14:30:00Z",
    "chat": {
      "jid":     "5511999999999@s.whatsapp.net",
      "isGroup": false
    },
    "sender": {
      "jid":      "5511777777777@s.whatsapp.net",
      "instance": "minha-instancia"
    }
  }
}

When the user taps a REPLY button, the response arrives as a text message containing the id of the clicked button, capture that via webhook to chain the flow.

Path parameters

instance

string

required

Instance name (e.g., $Instance_Name).

Headers

token

string

required

TokenAccount or TokenInstance.

Content-Type

string

required

application/json

Request body

number

string

required

Destination: phone (5511999999999) or JID (@s.whatsapp.net, @lid, @g.us, @newsletter).

message

string

Text displayed above the carousel (optional).

footer

string

Text displayed below the carousel (optional).

cards

CarouselCard[]

required

List of carousel cards. Minimum 1. Each card is an object with header, body, footer and buttons (described below).

cards[].header

object

required

Card header. Sub-fields:

title (string, required), card title.
subtitle (string), optional subtitle.
imageUrl (string), image URL for the header.
videoUrl (string), video URL for the header. Use one of the two media options per card.

cards[].body

object

required

Card body. Sub-field:

text (string, required), textual content of the card.

cards[].footer

string

Optional text displayed at the footer of the individual card.

cards[].buttons

CarouselButton[]

List of buttons for the card. Each button has:

displayText (string, required), visible text.
id (string, required), semantics vary by type: for REPLY, it is the ID returned when clicked; for URL, the URL to open; for CALL, the number to dial; for COPY, the code to copy.
type (string), REPLY (default), URL, CALL or COPY. Other values return 400 Card N, Button M: Type must be one of: REPLY, URL, CALL, COPY.

delay

int

default:"0"

Time in seconds to wait before sending. During the interval, the server sends the “typing…” indicator and fires “paused” before the actual send.

replyTo

string

ID of the message to be quoted (reply). The original message must belong to the same instance and have been saved in the database.

replyPrivate

boolean

default:"false"

When true and replyTo points to a message originating from a group, the carousel is redirected to the original author’s private chat (keeping the quote).

source

string

default:"api"

Origin identifier for traceability (e.g., crm, bot-suporte, n8n). Saved on the message record and propagated to webhooks.

Notes

delay is in seconds (not milliseconds).
In each header, choose a single media: either imageUrl or videoUrl. Sending both can result in inconsistent rendering on the client.
Server validation: each card needs non-empty header.title and body.text; each button needs non-empty displayText and id. Errors are returned with the index (Card N, Button M: ...) to make debugging easier.
Older WhatsApp devices may fall back to text and display the carousel as a regular message.
For URL buttons, make sure the link starts with https:// to avoid being blocked by the client.

Errors

HTTP	Internal status	Message
400	,	`Instance name is required`
400	,	`Invalid request body: <detail>`
400	,	`Number is required`
400	,	`At least one card is required`
400	,	`Card N: Header title is required`
400	,	`Card N: Body text is required`
400	,	`Card N, Button M: Display text is required`
400	,	`Card N, Button M: ID is required`
400	,	`Card N, Button M: Type must be one of: REPLY, URL, CALL, COPY`
400	`invalid_number`	`Invalid phone number format: <detail>`
400	`media_download_failed`	(reason for the header media download failure)
404	,	`Instance not found`
500	`media_upload_failed`	(reason for the header media upload failure)
500	`send_failed`	`Failed to send carousel: <reason>`
503	`disconnected`	`Instance is not connected to WhatsApp`

Error envelope:

{
  "success": false,
  "error": { "message": "Card 1: Header title is required" }
}

​Description

​Examples

​Simple carousel with REPLY buttons

​Carousel with image header and URL buttons

​Carousel with video header

​Success response

​Path parameters

​Headers

​Request body

​Notes

​Errors

Description

Examples

Simple carousel with REPLY buttons

Carousel with image header and URL buttons

Carousel with video header

Success response

Path parameters

Headers

Request body

Notes

Errors