Genuka WA docs

Enviar un OTP por WhatsApp con Node.js

Envía códigos de un solo uso (OTP) por WhatsApp desde Node.js con Genuka WA: plantilla de autenticación, botón para copiar el código, vencimiento, verificación y respaldo por SMS.

Para enviar un código de un solo uso por WhatsApp desde Node.js con Genuka WA, crea una sola vez una plantilla AUTHENTICATION con un botón para copiar el código y luego llama a POST /api/v1/messages con el atajo otp. Meta redacta el texto del mensaje; tú solo proporcionas el código, y tu servidor se encarga del vencimiento y de la verificación. El paso que muchos pasan por alto: el negocio debe superar primero la verificación del negocio de Meta (u otra vía de escalamiento de Meta).

Última actualización: 8 de octubre de 2026

¿Qué necesito antes de empezar?

  • Un número conectado a Genuka WA y su connectionId — consulta el inicio rápido.
  • Una clave API, usada solo del lado del servidor — consulta Autenticación.
  • Node.js 22 o posterior: una versión LTS todavía con soporte, con fetch nativo.
  • Un negocio que haya superado la verificación del negocio de Meta (u otra vía de escalamiento de Meta). Es el requisito que se descubre demasiado tarde: sin él, Meta se niega a crear la plantilla, con un mensaje de error que culpa a la app en lugar del negocio. La última sección de esta guía lo explica.
  • Un método de pago en la cuenta de WhatsApp Business, en Meta. Genuka es un Tech Provider de Meta, no un BSP: Meta factura directamente a la cuenta, y un cliente incorporado por un Tech Provider debe agregar su propio método de pago (Meta, Partners). Sin él, la plantilla se aprueba, pero cada código vuelve con el error 131042 — consulta error 131042.

¿Cómo funciona un OTP por WhatsApp?

Un código de un solo uso viaja en una plantilla de categoría AUTHENTICATION. A diferencia de las demás categorías, tú no escribes su texto: Meta proporciona un cuerpo predefinido e inserta en él tu código, y tú solo eliges las opciones que lo rodean (documentación de Meta).

ParteLo que eligesRegla de Meta
CuerpoNada — texto predefinido, se inserta tu códigoSin texto personalizado
Aviso de seguridadadd_security_recommendation: trueOpcional
Piecode_expiration_minutesDe 1 a 90 minutos
BotónOTP con otp_type: COPY_CODEEtiqueta de hasta 25 caracteres
CódigoGenerado por tu servidorHasta 15 caracteres
Tiempo de vida (TTL)messageSendTtlSecondsMeta: 10 min por defecto, de 30 s a 15 min; Genuka WA acepta de 60 a 600 s

Las URLs, los archivos multimedia y los emojis no se admiten en este tipo de plantilla (documentación de Meta, copy code button).

¿Copiar código, un toque o sin toque?

COPY_CODE funciona en todos los teléfonos: el usuario toca el botón y pega el código. ONE_TAP y ZERO_TAP entregan el código a tu app de Android y necesitan su package_name y su signature_hash — consulta la referencia de la API. Empieza con COPY_CODE.

¿Cómo creo la plantilla de autenticación?

Envía la plantilla

Una llamada, una sola vez. Anota el idioma que eliges: cada envío debe usar exactamente el mismo.

POST /api/v1/templates
curl -X POST https://wa.genuka.com/api/v1/templates \
  -H "Authorization: Bearer $GENUKA_WA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connectionId": "con_1",
    "name": "login_code",
    "language": "en",
    "category": "AUTHENTICATION",
    "messageSendTtlSeconds": 300,
    "components": [
      { "type": "BODY", "add_security_recommendation": true },
      { "type": "FOOTER", "code_expiration_minutes": 5 },
      { "type": "BUTTONS", "buttons": [
        { "type": "OTP", "otp_type": "COPY_CODE", "text": "Copy code" }
      ] }
    ]
  }'

La respuesta 201 contiene la plantilla guardada, con su id y su status. En el panel, lo equivalente es Plantillas › Nueva plantilla, categoría Autenticación, botón "Copy code".

Espera la aprobación

Meta revisa la plantilla. El veredicto te llega de tres maneras:

  • un webhook template_status cuyo data.event es APPROVED o REJECTED, si tu endpoint está suscrito a template.status_changed (o a todos los eventos);
  • GET /api/v1/templates/{id}, que devuelve el estado y su historial;
  • POST /api/v1/templates/sync, que vuelve a leer los estados desde Meta si se perdió un webhook.

Solo se puede enviar una plantilla approved.

¿Cómo envío el código desde Node.js?

El atajo otp coloca el código en los dos lugares que Meta exige para una plantilla de autenticación: el parámetro del cuerpo y el parámetro del botón. No tienes que escribir los components tú mismo.

otp.ts
import crypto from "node:crypto";

const API = "https://wa.genuka.com/api/v1";
const CODE_TTL_MS = 5 * 60_000; // coincide con code_expiration_minutes y messageSendTtlSeconds
const MAX_ATTEMPTS = 5;

type OtpEntry = { codeHash: string; expiresAt: number; attempts: number; messageId: string };

/** El cuerpo de la respuesta: `data` si tiene éxito; si no, `error` (más `meta` si Meta lo rechazó). */
type ApiResult = {
  data?: { messageId: string };
  error?: string;
  message?: string;
  meta?: { errorClass?: string; retryable?: boolean; code?: number };
};

// En memoria para el ejemplo. En producción: Redis o tu base de datos, con el mismo vencimiento,
// o un segundo servidor no conocerá el código que emitió el primero.
const store = new Map<string, OtpEntry>();

const hash = (phone: string, code: string) =>
  crypto.createHash("sha256").update(`${phone}:${code}`).digest("hex");

export async function sendOtp(phone: string): Promise<string> {
  // Un generador criptográfico, nunca Math.random().
  const code = crypto.randomInt(0, 1_000_000).toString().padStart(6, "0");

  const response = await fetch(`${API}/messages`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.GENUKA_WA_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      connectionId: process.env.GENUKA_WA_CONNECTION_ID,
      to: phone, // formato internacional con el +, p. ej. "+237699001122"
      // Define siempre `language`: sin él, el envío apunta a "en_US".
      template: { name: "login_code", language: "en", otp: code },
    }),
  });

  // Un 5xx de la CDN no es JSON: sin este catch, el error de parseo ocultaría el estado.
  const body = (await response.json().catch(() => ({}))) as ApiResult;
  if (!response.ok || !body.data) {
    // body.meta.errorClass te dice quién puede corregirlo: ver "¿Qué pasa si el código nunca llega?"
    throw new Error(`OTP not sent: ${response.status} ${body.error ?? ""} — ${body.message ?? ""}`);
  }

  // Un código nuevo reemplaza al anterior: un solo código válido por número a la vez.
  store.set(phone, {
    codeHash: hash(phone, code),
    expiresAt: Date.now() + CODE_TTL_MS,
    attempts: 0,
    messageId: body.data.messageId,
  });
  return body.data.messageId;
}

Un 200 significa que Meta aceptó el mensaje, no que haya llegado. La entrega se confirma por webhook, con el mismo messageId.

El idioma debe coincidir exactamente

Para Meta, en y en_US son dos códigos de idioma distintos (supported languages): una plantilla aprobada en en no existe en en_US. Enviar en un idioma en el que la plantilla no existe, o no está aprobada, falla con el error 132001 (códigos de error de Meta).

¿Cómo verifico el código que escribió el usuario?

La verificación nunca pasa por WhatsApp: ocurre por completo de tu lado.

otp.ts (continuación)
export function verifyOtp(phone: string, input: string): boolean {
  const entry = store.get(phone);
  if (!entry || Date.now() > entry.expiresAt) return false;

  // Limita los intentos: un código de 6 dígitos cae en 1,000,000 intentos en el peor caso, muchos menos si nadie los cuenta.
  if (entry.attempts >= MAX_ATTEMPTS) return false;
  entry.attempts += 1;

  // Dos digests SHA-256 en hexadecimal: misma longitud, comparación en tiempo constante.
  const ok = crypto.timingSafeEqual(
    Buffer.from(entry.codeHash, "hex"),
    Buffer.from(hash(phone, input.trim()), "hex"),
  );

  if (ok) store.delete(phone); // un solo uso
  return ok;
}

Cuatro reglas lo sostienen: un código por número a la vez, un solo uso, un número limitado de intentos y un vencimiento decidido por tu servidor.

¿Cómo debo configurar el vencimiento y el tiempo de vida?

Coexisten tres duraciones. Asígnales el mismo valor.

DuraciónDónde se defineQué hace
code_expiration_minutesPie de la plantillaLo que lee el usuario: "vence en 5 minutos"
messageSendTtlSecondsPlantillaPasado ese plazo, Meta deja de intentar la entrega
Vencimiento en el servidorTu base de datosEl único que cuenta cuando verificas

Cuando un mensaje no se puede entregar, WhatsApp reintenta durante el tiempo de vida de la plantilla y luego lo descarta; si hasta entonces no llegó ningún estado delivered o read, considera el mensaje perdido (documentación de Meta, time-to-live). Un código entregado después de vencer es peor que uno nunca entregado: el usuario lo escribe, se rechaza, y no puede saber por qué.

¿Qué pasa si el código nunca llega?

Sigue el mensaje por su messageId en tu receptor de webhooks — consulta Recibir respuestas y estados por webhook para la verificación de la firma.

En tu receptor de webhooks (firma ya verificada)
if (event.type === "message_status") {
  const { id: messageId, status, errors } = event.data;
  // `read` cuenta como entregado: a veces Meta no envía `delivered` (ver más abajo).
  if (status === "delivered" || status === "read") await markOtpDelivered(messageId);
  if (status === "failed") await markOtpUndeliverable(messageId, errors?.[0]?.code);
}

No esperes únicamente delivered. Cuando el usuario tiene el chat abierto en el momento en que llega el mensaje — el caso habitual para un código que está esperando — Meta lo considera entregado y leído a la vez y envía solo read (documentación de Meta, statuses).

Luego, en tu interfaz:

  • Fallo explícito: ofrece otro canal de inmediato. La propia Meta recomienda dejar que los usuarios elijan entre WhatsApp, correo electrónico y SMS (buenas prácticas de Meta).
  • Ningún delivered ni read después de unos treinta segundos: muestra "Recibir el código por SMS" en lugar de enviar un segundo código por WhatsApp al mismo número.
  • Reenvío: impón un plazo entre solicitudes e invalida el código anterior en cada envío.
Código de MetaSignificadoReacción
131026Mensaje imposible de entregar, por ejemplo un número sin WhatsAppCambia a SMS, no reintentes
131056Demasiados mensajes al mismo destinatario en poco tiempoEspera antes de reenviar
130429Se alcanzó el rendimiento máximo de la Cloud APIReintenta con un tiempo de espera creciente
132001La plantilla no existe en ese idioma o no está aprobadaCorrige el nombre o el idioma
131042Problema con el método de pago en la cuenta de Meta del cliente: no sale ningún códigoCambia a SMS; el cliente corrige la facturación en Meta — consulta error 131042

Cuando Meta rechaza el envío en el acto, o una verificación de la plantilla o del número lo bloquea antes de la llamada, la respuesta es un 400 (409 para un problema de configuración) cuyo error es send_<class>, con un objeto meta que contiene errorClass y el code de Meta. La clase lo resuelve: recipient_permanent (cambia de canal), retryable o recipient_throttled (inténtalo más tarde), template o config (el problema es tuyo, no del usuario — alerta al equipo). Los rechazos propios de Genuka WA no llevan meta: lee error. 400 missing_fields y 400 recipient_is_sender son errores en la solicitud. Los demás bloquean todos los códigos hasta que se corrija la cuenta: 402 subscription_past_due (la prueba o el período pagado ha vencido), 402 plan_limit_messages (la asignación del período se agotó), 409 number_released, 403 account_deactivated y 404 connection_not_found. Ante cualquiera de ellos, envía el código por SMS o por correo electrónico de inmediato y alerta al equipo: el usuario está esperando en la pantalla de inicio de sesión.

¿Por qué Meta se niega a crear mi plantilla de autenticación?

Meta reserva la categoría AUTHENTICATION a las cuentas que cumplen dos condiciones: haber completado una de sus vías de escalamiento — en la práctica, la verificación del negocio de Meta o la verificación dirigida por un socio — y tener un límite de mensajes de al menos 2.000 (360dialog, documentación de authentication messages). Las categorías MARKETING y UTILITY no se ven afectadas.

Esto es lo que vemos en las cuentas conectadas a Genuka WA cuando el negocio no está verificado:

  • Graph rechaza la creación con "Application does not have permission for this action". Menciona la app, pero la causa es el negocio del cliente: ninguna clave ni configuración de permisos lo cambiará. Por eso Genuka WA responde 403 business_not_verified, con el businessVerificationStatus de la cuenta y una verificationUrl que abre el Centro de seguridad del negocio;
  • el health_status de la cuenta de WhatsApp Business contiene el error 141010, "The Business has not passed business verification".

La solución es completar la verificación del negocio en el Meta Business Suite del cliente y luego crear de nuevo la plantilla. Los detalles están en la página del error 141010.

También puedes leer una pista en GET /api/v1/numbers/{connectionId}/health: el campo messagingLimitTier. Un portafolio comercial nuevo empieza con 250 destinatarios únicos cada 24 horas fuera de la ventana de atención al cliente; la verificación del negocio es una de las vías que lo lleva a 2.000 (documentación de Meta, messaging limits).

Preguntas frecuentes

¿Puedo personalizar el texto del mensaje OTP?

No. El cuerpo de una plantilla de autenticación lo fija Meta; tú solo defines el aviso de seguridad, la duración que se muestra en el pie y la etiqueta del botón.

¿Cuánto cuesta un OTP por WhatsApp?

Meta cobra las plantillas entregadas según la categoría y el país del destinatario (precios de Meta), y las factura directamente a la cuenta de WhatsApp Business del cliente. Genuka WA no agrega ningún margen: cada envío simplemente se descuenta de la asignación de mensajes de tu suscripción — consulta los planes.

¿El usuario tiene que escribirme antes de recibir un código?

No: una plantilla se puede enviar fuera de la ventana de 24 horas. Sí necesitas el acuerdo de la persona, y Meta fija dos condiciones: indicar claramente que acepta recibir mensajes de tu negocio, y nombrar ese negocio (documentación de Meta, opt-in). En la pantalla de inicio de sesión, una línea como "Recibir mi código de acceso de [Nombre del negocio] por WhatsApp" junto al campo del número de teléfono cubre ambas.

¿Qué pasa si el número no tiene cuenta de WhatsApp?

El estado vuelve como failed con el código 131026. No reintentes por WhatsApp: ofrece SMS o correo electrónico.

Fuentes

En esta página