Saltar al contenido principal
POST
/
api
/
message
/
list
/
:instance
Enviar lista
curl --request POST \
  --url https://api.example.com/api/message/list/:instance \
  --header 'Content-Type: <content-type>' \
  --header 'token: <token>' \
  --data '
{
  "number": "<string>",
  "contentText": "<string>",
  "buttonText": "<string>",
  "sections": [
    {
      "title": "<string>",
      "rows": [
        {
          "id": "<string>",
          "title": "<string>",
          "description": "<string>"
        }
      ]
    }
  ],
  "headerText": "<string>",
  "footerText": "<string>",
  "delay": 123,
  "replyTo": "<string>",
  "replyPrivate": true,
  "source": "<string>"
}
'
Auth: TokenAccount o TokenInstance • Rate-limit: Global (100/min) • Idempotente: no

​
Descripción

Envía una lista interactiva con hasta 10 secciones y 10 filas por sección (límite global de 100 filas entre todas las secciones). El destinatario toca el botón (buttonText) para abrir el menú y elegir una de las opciones, y WhatsApp retorna el id de la fila seleccionada como un mensaje de respuesta. Ideal para menús, catálogos cortos, FAQs guiadas y soporte estructurado.

​
Ejemplos

​
Lista simple (1 sección)

Un menú lean con una única sección “Dishes” y dos filas. El destinatario toca “See options” para abrir el menú y seleccionar una de las opciones, que regresa como una respuesta cargando el id (p1 o p2). 
curl -X POST "https://ryzeapi.cloud/api/message/list/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":      "5511999999999",
    "contentText": "Pick an item from the menu:",
    "buttonText":  "See options",
    "sections": [
      {
        "title": "Dishes",
        "rows": [
          { "id": "p1", "title": "Lasagna", "description": "Bolognese, 4 slices" },
          { "id": "p2", "title": "Risotto", "description": "Mushroom" }
        ]
      }
    ]
  }'

​
Menú multi-sección (categorías)

Una lista con múltiples categorías agrupadas en secciones. Cada sección se renderiza con su propio encabezado dentro del menú, separando visualmente los grupos. 
curl -X POST "https://ryzeapi.cloud/api/message/list/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":      "5511999999999",
    "contentText": "Full menu. Choose an option:",
    "buttonText":  "Open menu",
    "sections": [
      {
        "title": "Main dishes",
        "rows": [
          { "id": "p1", "title": "Lasagna", "description": "Bolognese, 4 slices" },
          { "id": "p2", "title": "Risotto", "description": "Mushroom" },
          { "id": "p3", "title": "Salmon",  "description": "Grilled with vegetables" }
        ]
      },
      {
        "title": "Drinks",
        "rows": [
          { "id": "b1", "title": "Natural juice" },
          { "id": "b2", "title": "Soda" }
        ]
      },
      {
        "title": "Desserts",
        "rows": [
          { "id": "s1", "title": "Pudding" },
          { "id": "s2", "title": "Ice cream", "description": "3 flavors" }
        ]
      }
    ]
  }'

​
Lista con encabezado y pie

Agrega headerText (título sobre el cuerpo) y footerText (texto en gris debajo del botón), útil para branding y disclaimers cortos. 
curl -X POST "https://ryzeapi.cloud/api/message/list/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":      "5511999999999",
    "headerText":  "RyzeAPI Support",
    "contentText": "How can we help you today?",
    "footerText":  "24/7 support",
    "buttonText":  "See options",
    "sections": [
      {
        "title": "Support",
        "rows": [
          { "id": "sup_tec",  "title": "Technical support" },
          { "id": "sup_fin",  "title": "Billing" },
          { "id": "sup_com",  "title": "Sales",   "description": "Talk to sales" }
        ]
      }
    ]
  }'

​
Respuesta exitosa

El content retornado es el contentText que enviaste, y messageType es fijo en list. Guarda el messageId para correlacionar con los eventos de selección que llegan vía webhook.
200 OK
{
  "success": true,
  "message": "List message sent successfully",
  "status":  "sent",
  "data": {
    "messageId":   "3EB08FCF27E532F1B0F5",
    "direction":   "sent",
    "messageType": "list",
    "content":     "Pick an item from the menu:",
    "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 destinatario elige una opción, WhatsApp envía un mensaje de respuesta que contiene el id de la fila seleccionada, captura esa respuesta vía webhook/websocket de eventos para continuar 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).
​
contentText
string
requerido
Cuerpo principal del mensaje (descripción). Aparece sobre el botón que abre la lista.
​
buttonText
string
requerido
Texto del botón que abre la lista (p. ej., "See options", "Open menu"). Limitado por WhatsApp a unos pocos caracteres.
​
sections
ListSection[]
requerido
Array de 1 a 10 secciones. El número total de filas entre todas las secciones no puede exceder 100.
​
headerText
string
Título mostrado sobre contentText. Opcional.
​
footerText
string
Texto en gris claro debajo del botón. Opcional, ideal para disclaimers cortos.
​
delay
int
predeterminado:"0"
Tiempo en segundos a esperar antes de enviar. Durante el intervalo, el servidor envía el indicador “escribiendo…” al destinatario 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, la respuesta 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 en la base de datos y propagado a los webhooks.

​
Notas

  • Límites de WhatsApp: máximo de 10 secciones, 10 filas por sección y 100 filas en total. ¿Excediste? El servidor responde con 400 antes de intentar enviar.
  • La fila seleccionada por el usuario regresa a través del evento de mensaje como una respuesta cargando el id original, captura esto vía webhook para mapear la elección.
  • Las listas funcionan bien en DMs, grupos y canales, pero la UX puede variar entre WhatsApp Business y WhatsApp personal.
  • description es opcional por fila, pero mejora mucho la legibilidad cuando el título por sí solo es ambiguo.

​
Errores

HTTPStatus internoMensaje
400,Instance name is required
400,Invalid request body: <detail>
400,Number is required
400,ContentText is required
400,ButtonText is required
400,At least one section is required
400,Maximum of 10 sections allowed
400,Section N: Title is required
400,Section N: At least one row is required
400,Section N: Maximum of 10 rows allowed
400,Section N, Row M: ID is required
400,Section N, Row M: Title is required
400,Total number of rows across all sections cannot exceed 100
400invalid_numberInvalid phone number format: <detail>
404,Instance not found
500send_failedFailed to send message: <reason>
503disconnectedInstance is not connected to WhatsApp
Envoltorio de error: 
{
  "success": false,
  "error": { "message": "ContentText is required" }
}