Mensajes interactivos API WhatsApp: botones, listas y Flows

Actualizado el 29/10/2026

Los mensajes interactivos son envíos con type: "interactive" que le muestran al usuario botones de respuesta (hasta 3), una lista (hasta 10 opciones), un botón de enlace, una solicitud de ubicación, un carrusel o un WhatsApp Flow; cuando toca, el webhook devuelve el id que definiste. Son mensajes de servicio, por lo que solo se pueden enviar con la ventana de 24 horas abierta. Para iniciar una conversación con botones o Flow, usa una plantilla.

A continuación están los payloads de cada tipo, los límites de caracteres, el formato de la respuesta en el webhook y un enrutador en Node.js para manejarlo todo. Los ejemplos usan Vectalk (https://apis.vectalk.com.br/api/messages), que acepta el mismo cuerpo de la Cloud API de Meta.

Panorama de los tipos

Tipo	`interactive.type`	Límites principales	Qué vuelve en el webhook
Botones de respuesta	`button`	Hasta 3 botones; etiqueta de 20 caracteres; cuerpo de 1.024	`interactive.button_reply` con `id` y `title`
Lista	`list`	Hasta 10 secciones y 10 filas en total; botón de 20 caracteres	`interactive.list_reply` con `id`, `title` y `description`
Botón de enlace	`cta_url`	1 botón; etiqueta de 20 caracteres	Nada (abre el navegador)
Solicitud de ubicación	`location_request_message`	Cuerpo de 1.024 caracteres	Mensaje `type: "location"`
Carrusel multimedia	`carousel`	De 2 a 10 tarjetas con imagen o video	Depende del botón usado
Flow	`flow`	`flow_message_version` igual a `"3"`	`interactive.nfm_reply` con `response_json`
Producto y multiproducto	`product`, `product_list`	Ligados a un catálogo	Pedido (`type: "order"`)

La multimedia simple (imagen, video, documento, audio) y la ubicación fija no son interactivas, pero suelen aparecer en los mismos flujos y también están en esta guía.

Botones de respuesta

El formato más usado para confirmar, elegir entre pocas opciones o derivar a un agente.

curl -X POST https://apis.vectalk.com.br/api/messages \
  -H "Authorization: Bearer TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "5584999999999",
    "type": "interactive",
    "interactive": {
      "type": "button",
      "header": { "type": "text", "text": "Cita de mañana" },
      "body": { "text": "Hola, Marina. Tu cita está programada para el 21/10 a las 9 h. ¿La confirmas?" },
      "footer": { "text": "Clínica Ejemplo" },
      "action": {
        "buttons": [
          { "type": "reply", "reply": { "id": "confirmar_8812", "title": "Confirmar" } },
          { "type": "reply", "reply": { "id": "reprogramar_8812", "title": "Reprogramar" } },
          { "type": "reply", "reply": { "id": "agente", "title": "Hablar con alguien" } }
        ]
      }
    }
  }'

Reglas de Meta para este tipo:

hasta 3 botones, con etiquetas únicas de hasta 20 caracteres;
id de hasta 256 caracteres;
cuerpo de hasta 1.024 caracteres y pie de hasta 60;
encabezado opcional de texto, imagen, video o documento.

Usa el id para llevar contexto. En el ejemplo, confirmar_8812 ya indica la acción y la cita, y el webhook no depende del texto del botón. Cuando el usuario toca, llega:

"interactive": {
  "type": "button_reply",
  "button_reply": { "id": "confirmar_8812", "title": "Confirmar" }
}

¿Quieres probar mientras lees? Crea tu cuenta en Vectalk y envía el primer mensaje por la API oficial. Crear cuenta gratis →

Lista interactiva

Para más de tres opciones: menú, horarios, departamentos, planes. El usuario toca el botón y se abre un panel con las filas.

{
  "messaging_product": "whatsapp",
  "to": "5584999999999",
  "type": "interactive",
  "interactive": {
    "type": "list",
    "header": { "type": "text", "text": "Horarios disponibles" },
    "body": { "text": "Elige un horario para tu visita técnica." },
    "footer": { "text": "Hora de Brasilia" },
    "action": {
      "button": "Ver horarios",
      "sections": [
        {
          "title": "Miércoles, 22/10",
          "rows": [
            { "id": "slot_2210_09", "title": "09:00", "description": "Técnico disponible" },
            { "id": "slot_2210_14", "title": "14:00", "description": "Técnico disponible" }
          ]
        },
        {
          "title": "Jueves, 23/10",
          "rows": [
            { "id": "slot_2310_10", "title": "10:00" }
          ]
        }
      ]
    }
  }
}

Campo	Límite
`action.button`	20 caracteres, un botón
Secciones	Hasta 10, título de hasta 24 caracteres
Filas	Hasta 10 sumando todas las secciones
`rows[].title`	24 caracteres
`rows[].description`	72 caracteres, opcional
`rows[].id`	200 caracteres
Cuerpo	4.096 caracteres
Encabezado	Solo texto, 60 caracteres
Pie	60 caracteres, opcional

El límite de 10 filas es el total del mensaje, no por sección. Si tienes más opciones, divídelas en etapas (primero el día, después el horario). La elección vuelve como list_reply:

"interactive": {
  "type": "list_reply",
  "list_reply": { "id": "slot_2210_14", "title": "14:00", "description": "Técnico disponible" }
}

Botón de enlace (CTA URL)

Esconde una URL larga detrás de un botón. Útil para comprobantes de pago, seguimiento y portal del cliente. (En Brasil, un uso típico es el boleto, un comprobante bancario que se paga con código de barras.)

{
  "messaging_product": "whatsapp",
  "to": "5584999999999",
  "type": "interactive",
  "interactive": {
    "type": "cta_url",
    "body": { "text": "Tu duplicado de factura está listo." },
    "action": {
      "name": "cta_url",
      "parameters": {
        "display_text": "Abrir factura",
        "url": "https://cliente.ejemplo.com/facturas/7731?origen=whatsapp"
      }
    }
  }
}

La etiqueta admite hasta 20 caracteres y el cuerpo hasta 1.024. El toque abre el navegador y no genera un mensaje del usuario, así que no renueva la ventana de 24 horas. Para medir clics, usa parámetros en la propia URL.

Ubicación: enviar y pedir

Para enviar una dirección fija (tienda, punto de retiro), usa type: "location". Latitud y longitud son obligatorias; nombre y dirección son opcionales.

{
  "messaging_product": "whatsapp",
  "to": "5584999999999",
  "type": "location",
  "location": {
    "latitude": -5.7945,
    "longitude": -35.2110,
    "name": "Tienda Ejemplo Centro",
    "address": "Av. Exemplo, 100 - Natal, RN"
  }
}

Para pedir la ubicación del usuario (entrega, atención en terreno), usa el mensaje interactivo con el botón de enviar ubicación:

{
  "messaging_product": "whatsapp",
  "to": "5584999999999",
  "type": "interactive",
  "interactive": {
    "type": "location_request_message",
    "body": { "text": "Para calcular el envío, toca el botón y comparte tu ubicación." },
    "action": { "name": "send_location" }
  }
}

La respuesta llega como un mensaje común de ubicación, con latitude, longitude y, si el usuario quiere compartirlos, name y address. El campo context.id apunta al mensaje de solicitud, lo que ayuda a relacionar la respuesta con el pedido correcto.

Carrusel multimedia

El carrusel muestra de 2 a 10 tarjetas con desplazamiento horizontal. Cada tarjeta necesita un encabezado de imagen o video, puede tener un cuerpo de hasta 160 caracteres (con hasta 2 saltos de línea) y debe tener un botón de enlace o botones de respuesta rápida, con el mismo tipo y la misma cantidad en todas las tarjetas. Funciona bien para mostrar variantes de un producto. La estructura completa está en la página de carrusel de la documentación de Meta; para iniciar la conversación con tarjetas, consulta la plantilla carrusel de WhatsApp.

WhatsApp Flows

Los Flows son formularios de varias pantallas dentro de WhatsApp: registro, agendamiento, encuestas, simulación de crédito. El contenido de las pantallas se define en un archivo JSON (Flow JSON), y el resultado te vuelve por el webhook. Para una introducción más amplia, lee WhatsApp Flows.

Meta indica dos requisitos previos: tener la empresa verificada y mantener alta la calidad de los mensajes.

1. Crear, subir el JSON y publicar

En Vectalk, el ciclo se hace por API con un token de instancia:

# Crea el Flow como borrador
curl -X POST https://apis.vectalk.com.br/api/flows \
  -H "Authorization: Bearer TU_TOKEN_DE_INSTANCIA" \
  -H "Content-Type: application/json" \
  -d '{ "name": "agendamiento_visita", "categories": ["APPOINTMENT_BOOKING"] }'

# Sube el flow.json (multipart)
curl -X POST https://apis.vectalk.com.br/api/flows/FLOW_ID/assets \
  -H "Authorization: Bearer TU_TOKEN_DE_INSTANCIA" \
  -F "file=@flow.json" -F "name=flow.json" -F "asset_type=FLOW_JSON"

# Publica
curl -X POST https://apis.vectalk.com.br/api/flows/FLOW_ID/publish \
  -H "Authorization: Bearer TU_TOKEN_DE_INSTANCIA"

La respuesta de la subida trae validation_errors. Corrige todo antes de publicar: un Flow publicado no se puede eliminar, solo dejar obsoleto.

2. Enviar el Flow dentro de la ventana

{
  "messaging_product": "whatsapp",
  "to": "5584999999999",
  "type": "interactive",
  "interactive": {
    "type": "flow",
    "header": { "type": "text", "text": "Agendar visita" },
    "body": { "text": "Elige fecha, horario y dirección en pocos pasos." },
    "footer": { "text": "Toma cerca de 1 minuto" },
    "action": {
      "name": "flow",
      "parameters": {
        "flow_message_version": "3",
        "flow_id": "FLOW_ID",
        "flow_token": "ag_5584999999999_20261020",
        "flow_cta": "Agendar",
        "flow_action": "navigate",
        "flow_action_payload": { "screen": "INICIO", "data": { "nombre": "Marina" } }
      }
    }
  }
}

El flow_token es tuyo: úsalo para identificar la sesión cuando vuelva la respuesta. Meta recomienda un CTA de hasta 30 caracteres, sin emojis. Para iniciar el contacto con un Flow fuera de la ventana, crea una plantilla con un botón de tipo FLOW, como explica la guía de plantillas de la API de WhatsApp.

3. Recibir la respuesta

Cuando el usuario termina, llega un mensaje interactivo de tipo nfm_reply. El response_json es una cadena con los datos definidos en la acción de cierre del Flow:

"interactive": {
  "type": "nfm_reply",
  "nfm_reply": {
    "name": "flow",
    "body": "Sent",
    "response_json": "{\"flow_token\":\"ag_5584999999999_20261020\",\"fecha\":\"2026-10-22\",\"horario\":\"14:00\"}"
  }
}

Vigila la salud del Flow. Si el endpoint del Flow se vuelve inestable, Meta cambia el estado a THROTTLED (envío limitado a 10 mensajes por hora) y, si empeora, a BLOCKED, cuando no se puede enviar ni abrir. Los cambios llegan por el webhook flows.

Multimedia: imagen, video, documento y audio

La multimedia va por link (URL pública) o por id (obtenido en la subida). En Vectalk, la subida se hace en /api/media y devuelve el media_id. Hay más ejemplos en cómo enviar multimedia por la API de WhatsApp.

{
  "messaging_product": "whatsapp",
  "to": "5584999999999",
  "type": "document",
  "document": {
    "link": "https://archivos.ejemplo.com/contratos/7731.pdf",
    "filename": "contrato-7731.pdf",
    "caption": "Te enviamos el contrato para firmar."
  }
}

Los IDs de multimedia que devuelve la subida valen por 30 días, así que puedes reutilizar el mismo id en varios envíos en lugar de volver a subir el archivo. En encabezados de botones, Meta recomienda usar el id de la multimedia subida en lugar del link. Para manejar los archivos que te envían los clientes, consulta cómo descargar la multimedia del webhook de WhatsApp.

Cómo enrutar las respuestas en el webhook

Un enrutador simple para los tipos anteriores, aprovechando que Vectalk entrega el payload de Meta sin cambios:

function enrutar(msg) {
  if (msg.type === "location") {
    return calcularEnvio(msg.from, msg.location.latitude, msg.location.longitude, msg.context?.id);
  }
  if (msg.type !== "interactive") return manejarTextoLibre(msg);

  const i = msg.interactive;
  switch (i.type) {
    case "button_reply":
      if (i.button_reply.id === "agente") return transferirAHumano(msg.from);
      return ejecutarAccion(msg.from, i.button_reply.id);
    case "list_reply":
      return reservarHorario(msg.from, i.list_reply.id);
    case "nfm_reply": {
      const datos = JSON.parse(i.nfm_reply.response_json);
      return guardarAgendamiento(datos.flow_token, datos);
    }
    default:
      return registrarNoManejado(msg);
  }
}

Las respuestas a botones de plantilla (respuesta rápida) llegan con type: "button", un formato distinto de button_reply; maneja los dos. La guía de webhooks de la API de WhatsApp muestra el servidor completo con cola y deduplicación, el tutorial de bot de WhatsApp con Node.js arma uno desde cero, y el artículo sobre chatbot con IA en WhatsApp muestra cómo combinar botones y respuestas generadas por IA.

Cómo elegir el tipo correcto

La elección depende de lo que necesitas recibir de vuelta:

Necesidad	Tipo indicado	Motivo
Sí o no, confirmar o reprogramar	Botones de respuesta	Un toque, respuesta estructurada y renovación de la ventana
Elegir entre 4 y 10 opciones	Lista	Cabe en un solo mensaje, con descripción por fila
Llevar a pago, seguimiento o portal	Botón de enlace	Esconde la URL y deja el texto limpio
Dirección de entrega o visita	Solicitud de ubicación	Coordenadas exactas, sin escribir
Recoger varios campos (nombre, fecha, dirección, preferencias)	Flow	Pantallas con validación, sin idas y vueltas en el chat
Mostrar variantes de producto	Carrusel o mensajes de catálogo	Comparación visual lado a lado

Si la conversación necesita más de dos preguntas seguidas, un Flow suele ser más corto para el usuario que varios botones en secuencia.

Buenas prácticas

Etiquetas cortas y con verbo. «Confirmar» y «Reprogramar» funcionan mejor que frases. El límite de 20 caracteres corta el resto.
Siempre una salida hacia una persona. La Política de Mensajería de WhatsApp Business exige vías de escalamiento rápidas, claras y directas en las experiencias automatizadas, como la transferencia a un agente humano. Un botón «Hablar con alguien» lo resuelve.
IDs estables. Trata el id como un contrato con tu backend. Cambiar el texto del botón no debería romper el enrutamiento.
Acepta texto libre. El usuario puede ignorar los botones y escribir. El enrutador tiene que entender «sí», «puede ser a las 14 h» o un audio.
No cuentes con el orden de entrega. Meta advierte que el orden de entrega de una secuencia de mensajes no está garantizado. Si el orden importa, espera el estado delivered del anterior antes de enviar el siguiente.
Una pregunta por mensaje. Tres mensajes interactivos seguidos confunden y generan respuestas al mensaje equivocado. El context.id del webhook muestra a qué mensaje respondió el usuario.

Preguntas frecuentes

¿Puedo enviar botones a un cliente que no habló conmigo hoy?

No como mensaje interactivo. Fuera de la ventana de 24 horas, usa una plantilla con botones de respuesta rápida, de enlace o de Flow.

¿Se pueden poner más de 3 botones de respuesta?

En el mensaje interactivo, no. Usa una lista (hasta 10 opciones). En plantillas, el límite es de hasta 10 botones, con reglas por tipo.

¿Se cobran los mensajes interactivos?

Son mensajes de servicio. Desde el 1/10/2026, Meta da 1.000 mensajes de servicio entregados gratis por número al mes y cobra a partir de ahí, salvo dentro de la ventana de punto de entrada gratuito abierta por un anuncio. Las tarifas varían según el país del destinatario; consulta precio de la API de WhatsApp por país.

¿Necesito un endpoint propio para usar Flows?

No para Flows simples, en los que los datos están en el propio Flow JSON y vuelven en el nfm_reply. Los Flows que buscan datos en tiempo real (horarios disponibles, precios) usan la acción data_exchange y exigen un endpoint propio.

Crea conversaciones interactivas con Vectalk

En Vectalk, botones, listas, ubicación, multimedia y Flows usan el mismo payload de la Cloud API, y las respuestas llegan al webhook en el formato de la documentación de Meta. Un token sirve para todas tus cuentas, la coexistencia con la app WhatsApp Business está disponible y el cobro funciona con una mensualidad más saldo prepago: Vectalk coloca su propia línea de crédito en tu número y cada mensaje entregado se descuenta del saldo, sin tarjeta registrada en Meta. Crea tu cuenta en apps.vectalk.com.br/register, consulta los ejemplos en docs.vectalk.com.br o habla con el equipo en el Centro de Ayuda.

Fuentes oficiales consultadas el 29/10/2026: Mensajes con botones de respuesta, Mensajes de lista, Mensajes CTA URL, Mensajes de solicitud de ubicación, Mensajes de carrusel multimedia, Envío de Flows, Salud y monitoreo de Flows, Multimedia.

Prueba hoy la API oficial de WhatsApp

Crea tu cuenta, genera el token y envía el primer mensaje con la guía de la documentación. Los mismos payloads y webhooks de la Cloud API de Meta.

Crear cuenta gratis

Leer la documentación

Mensajes interactivos en la API de WhatsApp: botones, listas, multimedia, ubicación y Flows