# Enviar lista

> Envía una lista de opciones con secciones en WhatsApp con POST /v1/messages y recibe la elección del contacto.

`POST /v1/messages` con `type: "interactive"` e `interactive.type: "list"` muestra un botón que abre una lista de opciones. Solo existe en WhatsApp. Los campos comunes a todos los envíos están en [Campos comunes](/es/send/text/#campos-comunes).

## Antes de empezar

- Una clave de API con el permiso `send` (consulta [Autenticación](/es/api/authentication/)).
- Una conexión **Activa** de WhatsApp.
- Un mensaje interactivo es un mensaje libre: solo sale dentro de la ventana de 24 horas (consulta [Ventanas](/es/api/limits/#ventanas)). Fuera de ella, usa una plantilla.

## Enviar una lista

**cURL**

```bash
curl https://api.messajo.com/v1/messages \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
      "connection_id": "conn_...",
      "to": "5511999999999",
      "type": "interactive",
      "interactive": {
        "type": "list",
        "header": {
          "type": "text",
          "text": "Atención"
        },
        "body": {
          "text": "¿Sobre qué quieres hablar?"
        },
        "footer": {
          "text": "Elige una opción"
        },
        "action": {
          "button": "Ver opciones",
          "sections": [
            {
              "title": "Pedidos",
              "rows": [
                {
                  "id": "status",
                  "title": "Estado del pedido",
                  "description": "Dónde está mi entrega"
                },
                {
                  "id": "troca",
                  "title": "Cambio o devolución"
                }
              ]
            },
            {
              "title": "Cuenta",
              "rows": [
                {
                  "id": "fatura",
                  "title": "Copia de la factura"
                },
                {
                  "id": "humano",
                  "title": "Hablar con una persona",
                  "description": "Atención en horario comercial"
                }
              ]
            }
          ]
        }
      }
    }'
```

**TypeScript**

```ts
import { Messajo } from "@messajo/sdk";

const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! });

const sent = await messajo.messages.send({
  "connection_id": "conn_...",
  "to": "5511999999999",
  "type": "interactive",
  "interactive": {
    "type": "list",
    "header": {
      "type": "text",
      "text": "Atención"
    },
    "body": {
      "text": "¿Sobre qué quieres hablar?"
    },
    "footer": {
      "text": "Elige una opción"
    },
    "action": {
      "button": "Ver opciones",
      "sections": [
        {
          "title": "Pedidos",
          "rows": [
            {
              "id": "status",
              "title": "Estado del pedido",
              "description": "Dónde está mi entrega"
            },
            {
              "id": "troca",
              "title": "Cambio o devolución"
            }
          ]
        },
        {
          "title": "Cuenta",
          "rows": [
            {
              "id": "fatura",
              "title": "Copia de la factura"
            },
            {
              "id": "humano",
              "title": "Hablar con una persona",
              "description": "Atención en horario comercial"
            }
          ]
        }
      ]
    }
  }
});
```

**n8n**

n8n HTTP Request: POST https://api.messajo.com/v1/messages

```json
{
  "connection_id": "conn_...",
  "to": "5511999999999",
  "type": "interactive",
  "interactive": {
    "type": "list",
    "header": {
      "type": "text",
      "text": "Atención"
    },
    "body": {
      "text": "¿Sobre qué quieres hablar?"
    },
    "footer": {
      "text": "Elige una opción"
    },
    "action": {
      "button": "Ver opciones",
      "sections": [
        {
          "title": "Pedidos",
          "rows": [
            {
              "id": "status",
              "title": "Estado del pedido",
              "description": "Dónde está mi entrega"
            },
            {
              "id": "troca",
              "title": "Cambio o devolución"
            }
          ]
        },
        {
          "title": "Cuenta",
          "rows": [
            {
              "id": "fatura",
              "title": "Copia de la factura"
            },
            {
              "id": "humano",
              "title": "Hablar con una persona",
              "description": "Atención en horario comercial"
            }
          ]
        }
      ]
    }
  }
}
```

## Campos de la lista

| Campo | Regla |
|---|---|
| `interactive.body.text` | Obligatorio, de 1 a 1024 caracteres. |
| `interactive.header`, `interactive.footer` | Opcionales. Encabezado de texto y pie con hasta 60 caracteres. |
| `action.button` | De 1 a 20 caracteres. Es la etiqueta del botón que abre la lista. |
| `action.sections` | De 1 a 10 secciones. |
| `sections[].title` | Opcional, hasta 24 caracteres. |
| `sections[].rows` | Al menos 1 fila. |
| `rows[].id` | De 1 a 200 caracteres. Es lo que recibes de vuelta. |
| `rows[].title` | De 1 a 24 caracteres. |
| `rows[].description` | Opcional, hasta 72 caracteres. |

## Recibir la elección

La elección llega como un evento [`message.received`](/es/webhooks/events/), con `data.message.content` de tipo `reply` y `kind: "list"`:

```json
{
  "type": "message.received",
  "data": {
    "message": {
      "direction": "inbound",
      "content": {
        "type": "reply",
        "kind": "list",
        "id": "status",
        "title": "Estado del pedido",
        "description": "Dónde está mi entrega",
        "payload": null
      }
    }
  }
}
```

`id`, `title` y `description` son los de la fila elegida. Enlaza tu lógica al `id`.

## Otros tipos interactivos

- Botones de respuesta y de enlace: [Enviar botones](/es/send/buttons/).
- Flujos: [Flows](/es/guides/flows/).
- Catálogo y pedido con Pix: [Ventas en WhatsApp](/es/guides/commerce/).

## Errores comunes

- [`outside_service_window`](/es/errors#outside_service_window) (422): fuera de las 24 horas ([ventanas](/es/api/limits/#ventanas)). El fin de la ventana viene en `details[0].message`.
- [`type_not_supported_by_channel`](/es/errors#type_not_supported_by_channel) (422): el canal no acepta ese tipo. Por ejemplo, `interactive` en Instagram o Messenger, o `buttons` en WhatsApp.
- [`validation_failed`](/es/errors#validation_failed) (400): el cuerpo incumple las reglas, como más de 3 botones o un título por encima del límite.
