Inicio / Tipos de mensaje / Botones / Listas

Mensajes interactivos

Botones de respuesta rápida y listas desplegables. Sirven para guiar al cliente en menús, flujos de soporte, encuestas, selección de productos, confirmaciones, etc. Mejoran muchísimo la tasa de respuesta versus pedirle al cliente que escriba algo.

POST https://api.wis.chat/v22.0/{tid}/messages

Botones de respuesta rápida (máx 3)

Hasta 3 botones que el cliente puede tocar para responder. Cada botón tiene un id que recibirás en el webhook cuando el cliente haga clic.

{
  "messaging_product": "whatsapp",
  "to": "593999999999",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "header": { "type": "text", "text": "Soporte NOUXSOFT" },
    "body":   { "text": "¿Cómo podemos ayudarte hoy?" },
    "footer": { "text": "Atención 24/7" },
    "action": {
      "buttons": [
        { "type": "reply", "reply": { "id": "btn_factura",  "title": "📄 Factura" } },
        { "type": "reply", "reply": { "id": "btn_soporte",  "title": "🛠 Soporte" } },
        { "type": "reply", "reply": { "id": "btn_ventas",   "title": "💼 Ventas" } }
      ]
    }
  }
}

Límites por botón: el id hasta 256 caracteres, el title hasta 20 caracteres. Total máximo: 3 botones.

Estructura

CampoTipoRequeridoDescripción
interactive.typestringrequeridoSiempre "button" en este caso.
headerobjectopcionalTexto, imagen, video o documento como encabezado.
body.textstringrequeridoTexto principal del mensaje. Máx 1024 caracteres.
footer.textstringopcionalPie de página. Máx 60 caracteres.
action.buttonsarrayrequerido1 a 3 botones de tipo reply.

Lista desplegable (máx 10 opciones)

Más útil cuando tienes muchas opciones. WhatsApp muestra un botón que abre un panel con la lista. Hasta 10 filas distribuidas en hasta 10 secciones.

{
  "messaging_product": "whatsapp",
  "to": "593999999999",
  "type": "interactive",
  "interactive": {
    "type": "list",
    "header": { "type": "text", "text": "Catálogo NOUXSOFT" },
    "body":   { "text": "Selecciona el producto que te interesa" },
    "footer": { "text": "Cotizamos en menos de 24h" },
    "action": {
      "button": "Ver opciones",
      "sections": [
        {
          "title": "Software",
          "rows": [
            { "id": "prod_neocrm",  "title": "NeoCRM 360",    "description": "CRM omnicanal" },
            { "id": "prod_wischat", "title": "Wis.Chat",       "description": "WhatsApp Business" },
            { "id": "prod_finance", "title": "FinancePro",    "description": "ERP financiero" }
          ]
        },
        {
          "title": "Servicios",
          "rows": [
            { "id": "srv_voip",    "title": "VoIP empresarial" },
            { "id": "srv_etl",     "title": "ETL / integración" }
          ]
        }
      ]
    }
  }
}

Estructura

CampoTipoRequeridoDescripción
interactive.typestringrequeridoSiempre "list".
action.buttonstringrequeridoTexto del botón que abre la lista. Máx 20 caracteres.
action.sectionsarrayrequerido1 a 10 secciones, cada una con un título y filas.
sections[].titlestringopcionalTítulo del grupo. Máx 24 caracteres.
sections[].rowsarrayrequeridoFilas seleccionables (total máx 10 entre todas las secciones).
rows[].idstringrequeridoID que recibirás en el webhook. Máx 200 caracteres.
rows[].titlestringrequeridoTexto principal de la fila. Máx 24 caracteres.
rows[].descriptionstringopcionalSubtítulo descriptivo. Máx 72 caracteres.

Cómo recibir la respuesta del cliente

Cuando el cliente toca un botón o selecciona una opción de la lista, te llega un mensaje en tu webhook configurado. El payload incluye el id que tú definiste: 

// Webhook entrante cuando el cliente toca un botón
{
  "messages": [{
    "from": "593911223344",
    "type": "interactive",
    "interactive": {
      "type": "button_reply",
      "button_reply": {
        "id": "btn_factura",        // el id que vos pusiste
        "title": "📄 Factura"
      }
    }
  }]
}

// Para listas, el tipo es "list_reply"
{
  "messages": [{
    "from": "593911223344",
    "type": "interactive",
    "interactive": {
      "type": "list_reply",
      "list_reply": {
        "id": "prod_neocrm",
        "title": "NeoCRM 360",
        "description": "CRM omnicanal"
      }
    }
  }]
}

Estrategia recomendada: usa id auto-descriptivos (btn_factura_pendiente) en vez de números (1, 2). Te facilita debuggear y permite cambiar el orden visual sin romper la lógica del backend.

Ejemplo PHP completo

function enviarBotonesWischat($tid, $token, $to, $bodyText, $botones) {
    // $botones = [['id' => 'btn1', 'title' => 'Sí'], ...]
    $btns = array_map(function($b) {
        return ['type' => 'reply', 'reply' => $b];
    }, $botones);

    $payload = [
        'messaging_product' => 'whatsapp',
        'to'                => $to,
        'type'              => 'interactive',
        'interactive'       => [
            'type'   => 'button',
            'body'   => ['text' => $bodyText],
            'action' => ['buttons' => $btns],
        ],
    ];

    $ch = curl_init("https://api.wis.chat/v22.0/{$tid}/messages");
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POSTFIELDS     => json_encode($payload),
        CURLOPT_HTTPHEADER     => [
            "Authorization: Bearer {$token}",
            'Content-Type: application/json',
        ],
    ]);
    $res = json_decode(curl_exec($ch), true);
    curl_close($ch);
    return $res;
}

enviarBotonesWischat(15, 'TOKEN', '593999999999',
    '¿Confirmás tu pedido #4521?',
    [
        ['id' => 'btn_si',    'title' => '✅ Sí'],
        ['id' => 'btn_no',    'title' => '❌ No'],
        ['id' => 'btn_ayuda', 'title' => '❓ Ayuda'],
    ]
);