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

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

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

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 como un mensaje de texto que contiene el id del botón clicado, captúralo vía webhook para encadenar el flujo.

Parámetros de ruta

instance

string

requerido

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

Cabeceras

token

string

requerido

TokenAccount o TokenInstance.

Content-Type

string

requerido

application/json

Cuerpo de la solicitud

number

string

requerido

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

message

string

Texto mostrado sobre el carrusel (opcional).

footer

string

Texto mostrado debajo del carrusel (opcional).

cards

CarouselCard[]

requerido

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

cards[].header

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.

cards[].body

object

requerido

Cuerpo de la tarjeta. Sub-campo:

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

cards[].footer

string

Texto opcional mostrado al pie de la tarjeta individual.

cards[].buttons

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.

delay

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.

replyTo

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.

replyPrivate

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

source

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

​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