Skip to main content
POST
/
api
/
message
/
carousel
/
:instance
Send Carousel
curl --request POST \
  --url https://api.example.com/api/message/carousel/:instance \
  --header 'Content-Type: <content-type>' \
  --header 'token: <token>' \
  --data '
{
  "number": "<string>",
  "message": "<string>",
  "footer": "<string>",
  "cards": [
    {}
  ],
  "cards[].header": {},
  "cards[].body": {},
  "cards[].footer": "<string>",
  "cards[].buttons": [
    {}
  ],
  "delay": 123,
  "replyTo": "<string>",
  "replyPrivate": true,
  "source": "<string>"
}
'

Documentation Index

Fetch the complete documentation index at: https://docs.ryzeapi.cloud/llms.txt

Use this file to discover all available pages before exploring further.

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

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

HTTPInternal statusMessage
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
400invalid_numberInvalid phone number format: <detail>
400media_download_failed(reason for the header media download failure)
404—Instance not found
500media_upload_failed(reason for the header media upload failure)
500send_failedFailed to send carousel: <reason>
503disconnectedInstance is not connected to WhatsApp
Error envelope: 
{
  "success": false,
  "error": { "message": "Card 1: Header title is required" }
}