WhatsApp Business API para reenvío de otp

Descripción del caso de uso

Reenvía un nuevo código de verificación de un solo uso vía plantilla de autenticación de WhatsApp cuando el usuario toca «Reenviar código». Cada intento usa parámetros de cuerpo + botón copy-code con un valor recién generado.

Ejemplo de plantilla

{{1}} es tu código de verificación. Por tu seguridad, no compartas este código con nadie.

[Copiar código]

Las plantillas de autenticación requieren el OTP en dos lugares de la API — cuerpo y botón copy-code. Envíos solo con cuerpo devuelven sent: false.

Variables y propósito

• {{1}} — código de verificación de un solo uso recién generado (dígitos)

Ejemplo completado

123456 es tu código de verificación. Por tu seguridad, no compartas este código con nadie.

[Copiar código]

Cuándo usarlo

• reenvío tras expiración
• reintento de entrega
• flujos con límite de tasa

Valor para el negocio

• User requests a new verification code after timeout or non-delivery
• System generates a fresh one-time code and resolves the recipient phone
• Authentication template is built with the code in body and copy-code button
• WhatsApp message is delivered to the user
• User submits the new code; backend validates it and continues the original flow

Flujo de trabajo

1. El usuario toca «Reenviar código» tras expiración o mensaje no recibido.
2. El backend invalida el código anterior, genera uno nuevo y envía la plantilla.
3. El usuario copia el nuevo código y lo envía.
4. El backend valida y continúa el flujo de verificación original.
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 GET …/hookInfo?messageId=<id> y maneja fallos si es necesario.

Implementación técnica

Requisitos previos

• Plantilla de autenticación aprobada (copy-code) en el canal 1MSG.
• Límites de reenvío e invalidación del código anterior en tu backend.
• Teléfono en formato internacional; OTP en cuerpo y botón al momento del envío.

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_CODE = "___";    // {{1}} otp code

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

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

  // params carries body and button blocks.
  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(code) }, // {{1}} otp code
        ],
      },
      {
        type: "button",
        sub_type: "url",
        index: "0",
        parameters: [{ type: "text", text: String(code) }],
      },
    ],
  };

  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;
}

if (require.main === module) {
  sendTemplateMessage({
    phone: TEST_PHONE,
    code: TEST_CODE,
  }).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