Enviar carrusel

Auth: TokenAccount o TokenInstance • Rate-limit: Global (100/min) • Idempotente: no

Descripción

Envía un mensaje con un carrusel de tarjetas deslizables. Cada tarjeta tiene un header (título requerido, con media opcional vía imageUrl o videoUrl), body.text (requerido), un footer opcional y algunos botones interactivos. Los botones aceptan cuatro tipos: REPLY (default, retorna el ID al hacer clic), URL (abre un enlace), CALL (marca un número) y COPY (copia un código). Puedes agregar message (texto antes del carrusel) y footer (texto debajo). Soporta delay, replyTo y replyPrivate.

Ejemplos

Carrusel simple con botones REPLY

Dos tarjetas con texto y botones de respuesta rápida solamente.

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

Carrusel con encabezado de imagen y botones URL

imageUrl en el encabezado y botones de tipo URL (el id recibe la URL a abrir).

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

Carrusel con encabezado de video

videoUrl reemplaza a imageUrl en el encabezado. Usa uno de los dos, no ambos.

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

Respuesta exitosa

El messageType retornado es interactive (un carrusel es una variación del mensaje interactivo de WhatsApp), y content transporta una descripción agregada ("<message> - Carousel with N card(s)") usada por el historial. Las tarjetas individuales no regresan en la respuesta, guarda el messageId para correlacionar con los clics vía 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"
    }
  }
}

Cuando el usuario toca un botón REPLY, la respuesta llega al webhook con message.type igual a template_button_reply y el id del botón clicado en message.content (y también en message.interactive.selectedButtonId). Captúralo vía webhook para encadenar el flujo. En carruseles, message.interactive.selectedCarouselCardIndex indica qué card fue tocado.

Parámetros de ruta

string

requerido

Nombre de la instancia (p. ej., $Instance_Name).

Cabeceras

string

requerido

TokenAccount o TokenInstance.

string

requerido

application/json

Cuerpo de la solicitud

string

requerido

Destino: teléfono (5511999999999) o JID (@s.whatsapp.net, @lid, @g.us, @newsletter).

string

Texto mostrado sobre el carrusel (opcional).

string

Texto mostrado debajo del carrusel (opcional).

CarouselCard[]

requerido

Lista de tarjetas del carrusel. Mínimo 1. Cada tarjeta es un objeto con header, body, footer y buttons (descritos abajo).

object

requerido

Encabezado de la tarjeta. Sub-campos:

title (string, requerido), título de la tarjeta.
subtitle (string), subtítulo opcional.
imageUrl (string), URL de imagen para el encabezado.
videoUrl (string), URL de video para el encabezado. Usa una de las dos opciones de media por tarjeta.

object

requerido

Cuerpo de la tarjeta. Sub-campo:

text (string, requerido), contenido textual de la tarjeta.

string

Texto opcional mostrado al pie de la tarjeta individual.

CarouselButton[]

Lista de botones de la tarjeta. Cada botón tiene:

displayText (string, requerido), texto visible.
id (string, requerido), la semántica varía según type: para REPLY, es el ID retornado al hacer clic; para URL, la URL a abrir; para CALL, el número a marcar; para COPY, el código a copiar.
type (string), REPLY (default), URL, CALL o COPY. Otros valores retornan 400 Card N, Button M: Type must be one of: REPLY, URL, CALL, COPY.

int

predeterminado:"0"

Tiempo en segundos a esperar antes de enviar. Durante el intervalo, el servidor envía el indicador “escribiendo…” y dispara “pausado” antes del envío real.

string

ID del mensaje a citar (respuesta). El mensaje original debe pertenecer a la misma instancia y haber sido guardado en la base de datos.

boolean

predeterminado:"false"

Cuando es true y replyTo apunta a un mensaje originado en un grupo, el carrusel se redirige al chat privado del autor original (manteniendo la cita).

string

predeterminado:"api"

Identificador de origen para trazabilidad (p. ej., crm, bot-suporte, n8n). Guardado en el registro del mensaje y propagado a los webhooks.

Notas

delay es en segundos (no milisegundos).
En cada header, elige una sola media: ya sea imageUrl o videoUrl. Enviar ambas puede resultar en renderizado inconsistente en el cliente.
Validación del servidor: cada tarjeta necesita header.title y body.text no vacíos; cada botón necesita displayText e id no vacíos. Los errores se retornan con el índice (Card N, Button M: ...) para facilitar el debugging.
Los dispositivos antiguos de WhatsApp pueden caer a texto y mostrar el carrusel como un mensaje regular.
Para botones URL, asegúrate de que el enlace comience con https:// para evitar ser bloqueado por el cliente.

Errores

HTTP	Status interno	Mensaje
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`	(motivo del fallo de descarga de media del encabezado)
404	,	`Instance not found`
500	`media_upload_failed`	(motivo del fallo de upload de media del encabezado)
500	`send_failed`	`Failed to send carousel: <reason>`
503	`disconnected`	`Instance is not connected to WhatsApp`

Envoltorio de error:

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

Introducción

Instancia

Eventos

Mensajes

Llamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidad

Enviar carrusel

Descripción

Ejemplos

Carrusel simple con botones REPLY

Carrusel con encabezado de imagen y botones URL

Carrusel con encabezado de video

Respuesta exitosa

Parámetros de ruta

Cabeceras

Cuerpo de la solicitud

Notas

Errores

​Descripción

​Ejemplos

​Carrusel simple con botones REPLY

​Carrusel con encabezado de imagen y botones URL

​Carrusel con encabezado de video

​Respuesta exitosa

​Parámetros de ruta

​Cabeceras

​Cuerpo de la solicitud

​Notas

​Errores

Descripción

Ejemplos

Carrusel simple con botones REPLY

Carrusel con encabezado de imagen y botones URL

Carrusel con encabezado de video

Respuesta exitosa

Parámetros de ruta

Cabeceras

Cuerpo de la solicitud

Notas

Errores