Enviar lista

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

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

import os, requests

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

package main

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

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

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

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

import os, requests

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

package main

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

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

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

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

import os, requests

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

package main

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

func main() {
    body := strings.NewReader(`{
        "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" }
                ]
            }
        ]
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/message/list/"+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 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

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

requerido

Cuerpo principal del mensaje (descripción). Aparece sobre el botón que abre la lista.

string

requerido

Texto del botón que abre la lista (p. ej., "See options", "Open menu"). Limitado por WhatsApp a unos pocos caracteres.

ListSection[]

requerido

Array de 1 a 10 secciones. El número total de filas entre todas las secciones no puede exceder 100.

Mostrar ListSection

string

requerido

Título de la sección (encabezado de grupo dentro del menú).

ListRow[]

requerido

Array de 1 a 10 filas por sección.

Mostrar ListRow

string

requerido

Identificador único de la fila. Es el valor que regresa como respuesta cuando el usuario selecciona esta opción.

string

requerido

Título mostrado para la opción.

string

Texto secundario en gris, debajo del título.

string

Título mostrado sobre contentText. Opcional.

string

Texto en gris claro debajo del botón. Opcional, ideal para disclaimers cortos.

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.

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, la respuesta 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 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

HTTP	Status interno	Mensaje
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`
400	`invalid_number`	`Invalid phone number format: <detail>`
404	,	`Instance not found`
500	`send_failed`	`Failed to send message: <reason>`
503	`disconnected`	`Instance is not connected to WhatsApp`

Envoltorio de error:

{
  "success": false,
  "error": { "message": "ContentText is required" }
}

Introducción

Instancia

Eventos

Mensajes

Llamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidad

Descripción

Ejemplos

Lista simple (1 sección)

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

Lista con encabezado y pie

Respuesta exitosa

Parámetros de ruta

Cabeceras

Cuerpo de la solicitud

Notas

Errores

​Descripción

​Ejemplos

​Lista simple (1 sección)

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

​Lista con encabezado y pie

​Respuesta exitosa

​Parámetros de ruta

​Cabeceras

​Cuerpo de la solicitud

​Notas

​Errores

Descripción

Ejemplos

Lista simple (1 sección)

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

Lista con encabezado y pie

Respuesta exitosa

Parámetros de ruta

Cabeceras

Cuerpo de la solicitud

Notas

Errores