Send Carousel

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

await fetch(`https://ryzeapi.cloud/api/message/carousel/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    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" }
        ]
      }
    ]
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/message/carousel/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "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"}
                ]
            }
        ]
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "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" }
                ]
            }
        ]
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/message/carousel/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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

await fetch(`https://ryzeapi.cloud/api/message/carousel/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    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" }
        ]
      }
    ]
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/message/carousel/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "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"}
                ]
            }
        ]
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "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" }
                ]
            }
        ]
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/message/carousel/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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

await fetch(`https://ryzeapi.cloud/api/message/carousel/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    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"  }
        ]
      }
    ]
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/message/carousel/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "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"}
                ]
            }
        ]
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "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"  }
                ]
            }
        ]
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/message/carousel/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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 at the webhook with message.type set to template_button_reply and the clicked button id in message.content (and also in message.interactive.selectedButtonId). Capture that via webhook to chain the flow. In carousels, message.interactive.selectedCarouselCardIndex tells which card was tapped.

Path parameters

string

required

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

Headers

string

required

TokenAccount or TokenInstance.

string

required

application/json

Request body

string

required

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

string

Text displayed above the carousel (optional).

string

Text displayed below the carousel (optional).

CarouselCard[]

required

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

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.

object

required

Card body. Sub-field:

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

string

Optional text displayed at the footer of the individual card.

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.

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.

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.

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).

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

Introduction

Instance

Events

Messages

Calls

Groups

Communities

Newsletter

Profile

Chat

Chatwoot

Typebot

Observability

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

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