WhatsApp Business API para notificación de nuevo lead al gerente

Descripción del caso de uso

El escenario envía al gerente de ventas una plantilla de WhatsApp personalizada cuando se captura un lead nuevo. El mensaje incluye el nombre del lead, datos de contacto y etiqueta de fuente. Un botón URL estático abre el registro del lead en el CRM.

Ejemplo de plantilla

🔔 Nuevo lead: {{1}}

Contacto: {{2}}

Fuente: {{3}}

Contacta al cliente lo antes posible mientras el interés está alto.

[Abrir en CRM]

El botón URL del CRM está fijado en la plantilla de Meta — solo las variables del cuerpo se envían vía API.

Variables y propósito

• {{1}} — nombre del lead o etiqueta corta (p. ej. Alejandro K., solicitud B2B)
• {{2}} — contacto del lead (teléfono, correo o línea de contacto combinada)
• {{3}} — fuente del lead (p. ej. formulario web, anuncio de Instagram, referido de partner)

Ejemplo completado

🔔 Nuevo lead: Alejandro K.

Contacto: +998901234567

Fuente: formulario web

Contacta al cliente lo antes posible mientras el interés está alto.

[Abrir en CRM]

Cuándo usarlo

• ventas internas
• agencias
• equipos pequeños

Valor para el negocio

• CRM or form integration captures a new lead event
• System resolves the manager phone and lead summary fields
• Internal notification template is built with name, contact, and source
• WhatsApp message is delivered to the sales manager
• Manager can open CRM immediately and contact the lead while interest is high

Flujo de trabajo

1. El CRM o integración de captura de leads emite un evento de lead nuevo.
2. El sistema obtiene el teléfono del gerente y los campos del resumen del lead.
3. Se construye una plantilla de notificación interna con tres variables en el cuerpo y un botón URL estático.
4. El gerente recibe la alerta en WhatsApp en su teléfono.
5. Se registra el resultado de entrega; el gerente abre el CRM con el botón para hacer 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

• Cuenta 1MSG con WhatsApp Business API conectada y plantilla de mensaje aprobada.
• Teléfono del gerente en formato internacional (sin + ni espacios) — MANAGER_PHONE en el código generado.
• Payload de lead nuevo: nombre del lead, contacto, fuente; URL del CRM fijada en el botón de la plantilla Meta.

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 MANAGER_PHONE = "___";            // manager phone in international format
const TEST_LEADNAME = "___";    // {{1}} lead name
const TEST_LEADCONTACT = "___";    // {{2}} lead contact
const TEST_LEADSOURCE = "___";    // {{3}} lead source

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, leadContact, leadSource }) {
  assertConfigured({
    CHANNEL_ID,
    API_TOKEN,
    TEMPLATE_NAME,
    TEMPLATE_NAMESPACE,
    TEMPLATE_LANGUAGE,
    phone,
    leadName,
    leadContact,
    leadSource,
  });

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

  // params carries body ONLY. Button text is fixed in the Meta template — no button param.
  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(leadContact) }, // {{2}} lead contact
          { type: "text", text: String(leadSource) }, // {{3}} lead source
        ],
      },
    ],
  };

  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 manager.");
  console.log("API response:", raw);
  return data;
}

if (require.main === module) {
  sendTemplateMessage({
    phone: MANAGER_PHONE,
    leadName: TEST_LEADNAME,
    leadContact: TEST_LEADCONTACT,
    leadSource: TEST_LEADSOURCE,
  }).catch((err) => {
    console.error("Execution failed:", err.message);
    process.exit(1);
  });
}

module.exports = { sendTemplateMessage };

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