Saltar al contenido principal
POST
/
api
/
message
/
carousel
/
:instance
Enviar carrusel
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 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

HTTPStatus internoMensaje
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(motivo del fallo de descarga de media del encabezado)
404—Instance not found
500media_upload_failed(motivo del fallo de upload de media del encabezado)
500send_failedFailed to send carousel: <reason>
503disconnectedInstance is not connected to WhatsApp
Envoltorio de error: 
{
  "success": false,
  "error": { "message": "Card 1: Header title is required" }
}