WhatsApp Business API para calificación de lead con preguntas clave

Descripción del caso de uso

Este caso de uso envía a un lead nuevo una plantilla de WhatsApp aprobada con saludo personalizado: el mensaje sustituye el nombre del lead y el contexto de producto o fuente, y el botón quick-reply «Iniciar» abre un flujo corto de calificación. Después de tocar el botón, dentro de la ventana de sesión de 24 horas el sistema hace preguntas de seguimiento una a la vez y registra cada respuesta vía webhook.

Ejemplo de plantilla

Hola, {{1}}! Para encontrar la solución adecuada para {{2}} más rápido, responde unas preguntas breves. Toca «Iniciar» — toma un par de minutos.

[Iniciar]

Variables y propósito

• {{1}} — nombre del lead o destinatario
• {{2}} — interés en producto o contexto de fuente del lead (de dónde vino la solicitud, qué área interesa)

Ejemplo completado

Hola, Alejandro! Para encontrar la solución adecuada para Mensajería WhatsApp más rápido, responde unas preguntas breves. Toca «Iniciar» — toma un par de minutos.

[Iniciar]

Cuándo usarlo

• ventas y generación de leads: primer contacto con un lead nuevo desde formulario, anuncio o crm cuando necesitas recopilar un perfil estructurado (presupuesto, plazo, tamaño de empresa, caso de uso) antes de traspasar a ventas. adecuado para equipos de desarrollo, grupos de producto pequeños y agencias que integran whatsapp en el embudo de calificación.

Valor para el negocio

• capture a new lead event with name and optional product or source context
• send a cold-start template that opens the chat and offers a Start action
• receive the Start tap via webhook and send the first qualifying question
• capture each subsequent answer via webhook and advance to the next question
• persist the completed qualification profile and hand off to sales or CRM

Flujo de trabajo

1. Cuando aparece un lead nuevo, el sistema envía una plantilla personalizada de saludo e invitación a iniciar un flujo corto de calificación.
2. El lead toca «Iniciar» — el evento llega vía webhook y se abre una sesión en la ventana de WhatsApp de 24 horas.
3. Dentro de la sesión el integrador envía preguntas de seguimiento una a la vez (presupuesto, plazo, tamaño de empresa, caso de uso).
4. Cada respuesta se captura vía webhook y se almacena en el perfil de calificación.
5. Tras recopilar todos los campos clave el perfil se pasa al CRM o ventas para seguimiento.
6. El progreso de entrega se reporta de forma asíncrona — típicamente sent, luego delivered (o failed/undelivered).
7. Tu sistema recibe el estado vía webhook (hooks[]) o consulta GET …/hookInfo?messageId=<id> y maneja fallos si es necesario.

Implementación técnica

Requisitos previos

• Plantilla de WhatsApp aprobada con dos variables en el cuerpo y un botón quick-reply «Iniciar»
• Cuenta 1MSG con acceso a la API de envío de plantillas y webhook configurado para mensajes entrantes
• Integración con CRM o sistema interno para registrar respuestas y pasar el perfil a ventas
• El handleIncomingMessage generado compara el texto entrante con las etiquetas de botones de la plantilla — un punto de partida; reemplázalo con tu router de producción.

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)

const TEMPLATE_NAME = "___";                // approved template name
const TEMPLATE_NAMESPACE = "___";           // template namespace (422 without it)
const TEMPLATE_LANGUAGE = "___";            // template language code, e.g. "en"



// === Test data ===
const TEST_PHONE = "___";            // client phone in international format
const TEST_LEADNAME = "___";    // {{1}} lead name
const TEST_PRODUCTCONTEXT = "___";    // {{2}} product context

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

function assertConfigured(values) {
  for (const [key, value] of Object.entries(values)) {
    if (value === "___" || value === "" || value === undefined || value === null) {
      throw new Error(`Missing configuration value: ${key}`);
    }
  }
}

async function sendTemplateMessage({ phone, leadName, productContext }) {
  assertConfigured({
    CHANNEL_ID,
    API_TOKEN,
    TEMPLATE_NAME,
    TEMPLATE_NAMESPACE,
    TEMPLATE_LANGUAGE,
    phone,
    leadName,
    productContext,
  });

  const url = `${API_BASE_URL}/${CHANNEL_ID}/sendTemplate`;

  // params carries body and button blocks (dynamic buttons).
  const requestBody = {
    phone: normalizePhone(phone),
    template: TEMPLATE_NAME,
    namespace: TEMPLATE_NAMESPACE,
    language: {
      policy: "deterministic",
      code: TEMPLATE_LANGUAGE,
    },
    params: [
      {
        type: "body",
        parameters: [
          { type: "text", text: String(leadName) }, // {{1}} lead name
          { type: "text", text: String(productContext) }, // {{2}} product context
        ],
      },
    ],
  };

  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. API response:");
    console.error(raw);
    process.exit(1);
  }

  console.log("Message sent to client.");
  console.log("API response:", raw);
  return data;
}

function handleIncomingMessage(message) {
  const text = (message && (message.text || message.body || "")).trim();
  // Meta quick_reply label (from template.txt) → route key (code_contract.ref) "start_qualification"
  if (text === "Начать") {
    console.log("Reply received: start_qualification");
    return { status: "start_qualification" };
  }
  console.log("Free-text reply — handle separately.");
  return { status: "other" };
}

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

module.exports = { sendTemplateMessage, handleIncomingMessage };

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

• Número de teléfono inválido o no normalizado
• Nombre de plantilla / namespace no aprobado o ausente
• Sin opt-in del cliente para mensajes comerciales de WhatsApp
• Cantidad de variables de plantilla incorrecta (422 de la API)
• Fallo de entrega — revisa el webhook de estado y la política de reintentos

Preguntas frecuentes

• ¿Necesito una plantilla aprobada? Sí — los mensajes cold-start de WhatsApp requieren una plantilla aprobada por Meta.
• ¿Puedo personalizar el texto? Las variables del cuerpo son dinámicas; el texto fijo y las etiquetas de botones se definen en la plantilla de Meta.
• ¿Cómo verifico la entrega? sent: true solo confirma aceptación. Rastrea la entrega vía webhook hooks[] o GET …/hookInfo?messageId=<id>.
• ¿Qué pasa si no se entrega? Registra el hook failed/undelivered, verifica opt-in y estado de la plantilla, luego reintenta o usa otro canal.
• ¿Puedo conectarlo a mi CRM o backend? Sí — dispara la llamada a la API desde el webhook de tu plataforma o manejador de eventos.

Recursos relacionados

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