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
fetchnativo. - 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).
| Parte | Lo que eliges | Regla de Meta |
|---|---|---|
| Cuerpo | Nada — texto predefinido, se inserta tu código | Sin texto personalizado |
| Aviso de seguridad | add_security_recommendation: true | Opcional |
| Pie | code_expiration_minutes | De 1 a 90 minutos |
| Botón | OTP con otp_type: COPY_CODE | Etiqueta de hasta 25 caracteres |
| Código | Generado por tu servidor | Hasta 15 caracteres |
| Tiempo de vida (TTL) | messageSendTtlSeconds | Meta: 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.
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_statuscuyodata.eventesAPPROVEDoREJECTED, si tu endpoint está suscrito atemplate.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.
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.
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ón | Dónde se define | Qué hace |
|---|---|---|
code_expiration_minutes | Pie de la plantilla | Lo que lee el usuario: "vence en 5 minutos" |
messageSendTtlSeconds | Plantilla | Pasado ese plazo, Meta deja de intentar la entrega |
| Vencimiento en el servidor | Tu base de datos | El ú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.
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
deliverednireaddespué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 Meta | Significado | Reacción |
|---|---|---|
131026 | Mensaje imposible de entregar, por ejemplo un número sin WhatsApp | Cambia a SMS, no reintentes |
131056 | Demasiados mensajes al mismo destinatario en poco tiempo | Espera antes de reenviar |
130429 | Se alcanzó el rendimiento máximo de la Cloud API | Reintenta con un tiempo de espera creciente |
132001 | La plantilla no existe en ese idioma o no está aprobada | Corrige el nombre o el idioma |
131042 | Problema con el método de pago en la cuenta de Meta del cliente: no sale ningún código | Cambia 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 elbusinessVerificationStatusde la cuenta y unaverificationUrlque abre el Centro de seguridad del negocio; - el
health_statusde 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
- Meta — Authentication templates
- Meta — Copy code authentication templates
- Meta — Time-to-live
- Meta — Authentication best practices
- Meta — Supported languages
- Meta — Status messages webhook
- Meta — Getting opt-in
- Meta — Error codes
- Meta — Partners (Tech Providers and Solution Partners)
- Meta — Messaging limits
- Meta — Pricing
- 360dialog — Authentication messages
Guías de la API de WhatsApp Business
Guías de la API de WhatsApp Business con Genuka WA: códigos OTP, notificaciones de pedidos, campañas, webhooks, coexistencia, precios de Meta y agentes de IA.
Notificaciones de pedidos por WhatsApp desde tu backend
Envía confirmaciones de pedido, avisos de envío y de entrega por WhatsApp desde tu backend: plantillas de utilidad, variables, idempotencia y estados de entrega.