WhatsApp Business API para catálogo de productos — lista interactiva

Descripción del caso de uso

Este escenario envía una lista interactiva con sendList durante la ventana de sesión de 24 horas. Dos secciones agrupan filas de productos; el cliente abre el catálogo y selecciona un artículo.

Ejemplo de plantilla

Explora nuestro catálogo para {{1}}:

Los títulos de sección, ids de fila y la etiqueta del botón de catálogo se definen en el contrato de integración.

Variables y propósito

• {{1}} — contexto de campaña o producto mostrado en el texto del encabezado de la lista

Ejemplo completado

Explora nuestro catálogo para promoción de primavera:

Cuándo usarlo

• campañas de venta en whatsapp

Valor para el negocio

• Campaign trigger opens or continues the WhatsApp session window
• Interactive list message shows two sections with two products each
• Client taps View catalog and selects a product row
• Webhook delivers the product id to the sales or ecommerce backend
• CRM or OMS continues the purchase flow with the chosen SKU

Flujo de trabajo

1. Un evento de campaña o respuesta del cliente mantiene la sesión abierta.
2. Tu backend construye una lista interactiva de dos secciones con filas de productos.
3. El cliente toca Ver catálogo y selecciona un producto.
4. El webhook devuelve el id de fila para procesamiento de pedido o CRM.
5. El progreso de entrega se reporta de forma asíncrona — típicamente sent, luego delivered (o failed/undelivered).
6. Tu sistema recibe el estado vía webhook (hooks[]) o consulta el estado de entrega y maneja fallos si es necesario.

Implementación técnica

Requisitos previos

• Ventana de sesión de WhatsApp abierta y webhook inbound para respuestas de lista.
• Canal 1MSG con acceso a sendList e ids de producto mapeados en tu backend.

Ejemplos de código

#!/usr/bin/env node

// === Configuration (replace "___" placeholders) ===
const API_BASE_URL = "https://api.1msg.io"; // production 1MSG API base URL
const CHANNEL_ID = "___";                   // channel ID from 1MSG dashboard
const API_TOKEN = "___";                    // channel JWT token (Bearer)



// === Test data ===
const TEST_PHONE = "___";            // client phone in international format · requires open 24-hour session window
const TEST_PRODUCTCONTEXT = "___";    // {{1}} product context

function normalizePhone(phone) {
  return String(phone).replace(/\D/g, "");
}

async function sendInteractiveListMessage({ phone, productContext }) {
  const url = `${API_BASE_URL}/${CHANNEL_ID}/sendList`;
  const requestBody = {
    phone: normalizePhone(phone),
    body: `Browse our catalog for ${productContext}:`,
    buttonText: "View catalog",
    action: "catalog",
    sections: [
      {
        title: "Featured products",
        rows: [
          { id: "prod_alpha", title: "Alpha Widget", description: "Compact model" },
          { id: "prod_beta", title: "Beta Widget", description: "Standard model" }
        ],
      },
      {
        title: "Bundles",
        rows: [
          { id: "bundle_starter", title: "Starter pack", description: "Two items included" },
          { id: "bundle_pro", title: "Pro pack", description: "Four items included" }
        ],
      }
    ],
  };

  const res = await fetch(url, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${API_TOKEN}`,
    },
    body: JSON.stringify(requestBody),
  });

  const raw = await res.text();
  let data;
  try {
    data = JSON.parse(raw);
  } catch {
    data = null;
  }

  if (!res.ok || !data || data.sent !== true) {
    console.error("Send failed.");
    console.error(raw);
    process.exit(1);
  }

  console.log("Message sent to client.");
  return data;
}

if (require.main === module) {
  sendInteractiveListMessage({
    phone: TEST_PHONE,
    productContext: TEST_PRODUCTCONTEXT,
  }).catch((err) => {
    console.error("Execution failed:", err.message);
    process.exit(1);
  });
}

module.exports = { sendInteractiveListMessage };

Respuesta inmediata de la API (síncrona)

• HTTP 2xx y JSON "sent": true significan que 1MSG aceptó el mensaje para envío — no que ya llegó al teléfono del cliente.
• Guarda el campo `id` de la respuesta (valor tipo wamid.…). Úsalo para correlacionar callbacks de entrega o polling.
• La respuesta también puede incluir message y description — solo informativos.

Estado de entrega (asíncrono)

• Registra un webhook (POST …/webhook) para que 1MSG envíe actualizaciones de entrega a tu endpoint HTTPS en un payload `hooks[]` separado (sent, delivered, read, o failed/undelivered cuando aplique).
• Opcionalmente consulta: GET {base}/{channel}/hookInfo?messageId=<id de sendTemplate>.
• En la práctica, la entrega suele completarse en pocos segundos — pero eso no está garantizado por el contrato de la API.

Errores frecuentes

• Ventana de sesión cerrada (sin mensaje del cliente en 24 horas)
• Número de teléfono inválido o no normalizado
• Cuerpo del mensaje / URL de media ausente o inválida
• Fallo de entrega — revisa el webhook de estado y la política de reintentos

Preguntas frecuentes

• ¿Necesito una plantilla? No — este escenario usa un mensaje de sesión dentro de la ventana de atención de 24 horas.
• ¿Cuándo se cierra la ventana de sesión? Si el cliente no escribió ni respondió en 24 horas, sendMessage fallará hasta que una plantilla reabra el chat.
• ¿Cómo verifico la entrega? sent: true solo confirma aceptación. Rastrea la entrega vía webhook hooks[] o polling.
• ¿Qué pasa si no se entrega? Registra el hook failed/undelivered, verifica la ventana de sesión, luego reintenta o usa una plantilla.
• ¿Puedo conectarlo a mi CRM o backend? Sí — dispara la llamada a la API desde tu webhook entrante o motor de flujos.

Recursos relacionados

• Base de conocimiento
• Crear una plantilla
• Enviar una plantilla
• SDK