# Enviar un OTP por WhatsApp con Node.js

URL: https://wa.genuka.com/es/docs/guides/whatsapp-otp-nodejs
Language: Spanish

> 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](https://wa.genuka.com/es/docs/quickstart).
* Una clave API, usada **solo del lado del servidor** — consulta [Autenticación](https://wa.genuka.com/es/docs/authentication).
* 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](https://developers.facebook.com/documentation/business-messaging/whatsapp/solution-providers/overview)).
  Sin él, la plantilla se aprueba, pero cada código vuelve con el error `131042` — consulta
  [error 131042](https://wa.genuka.com/es/docs/errors/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](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/authentication-templates/authentication-templates)).

| 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](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/authentication-templates/copy-code-button-authentication-templates)).

> [!NOTE]
> **¿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](https://wa.genuka.com/es/docs/api#plantillas). Empieza con `COPY_CODE`.

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

1. ### Envía la plantilla

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

   **curl**

   ```bash title="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" }
         ] }
       ]
     }'
   ```

   **Node.js**

   ```ts title="create-otp-template.ts"
   const response = await fetch("https://wa.genuka.com/api/v1/templates", {
     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,
       name: "login_code",
       language: "en",
       category: "AUTHENTICATION",
       // Pasados 5 minutos, Meta deja de intentar la entrega: de todos modos el código habría vencido.
       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" }],
         },
       ],
     }),
   });

   console.log(response.status, await response.json());
   ```

   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".

2. ### 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.

**Node.js**

```ts title="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;
}
```

**curl**

```bash title="POST /api/v1/messages"
curl -X POST https://wa.genuka.com/api/v1/messages \
  -H "Authorization: Bearer $GENUKA_WA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connectionId": "con_1",
    "to": "+237699001122",
    "template": { "name": "login_code", "language": "en", "otp": "482913" }
  }'
```

```json title="Respuesta"
{ "data": { "messageId": "wamid.HBg…" } }
```

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

> [!WARNING]
> **El idioma debe coincidir exactamente**
>
> Para Meta, `en` y `en_US` son dos códigos de idioma distintos
> ([supported languages](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/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](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes)).

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

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

```ts title="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ó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](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/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](https://wa.genuka.com/es/docs/guides/receive-messages-webhooks) para la verificación
de la firma.

```ts title="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](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/status)).

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](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/authentication-templates/authentication-best-practices)).
* **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 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](https://wa.genuka.com/es/docs/errors/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](https://docs.360dialog.com/docs/resources/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](https://wa.genuka.com/es/docs/errors/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](https://developers.facebook.com/documentation/business-messaging/whatsapp/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](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing)),
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](https://wa.genuka.com/es#pricing).

### ¿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](https://developers.facebook.com/documentation/business-messaging/whatsapp/getting-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](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/authentication-templates/authentication-templates)
* [Meta — Copy code authentication templates](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/authentication-templates/copy-code-button-authentication-templates)
* [Meta — Time-to-live](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/time-to-live)
* [Meta — Authentication best practices](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/authentication-templates/authentication-best-practices)
* [Meta — Supported languages](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/supported-languages)
* [Meta — Status messages webhook](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/status)
* [Meta — Getting opt-in](https://developers.facebook.com/documentation/business-messaging/whatsapp/getting-opt-in)
* [Meta — Error codes](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes)
* [Meta — Partners (Tech Providers and Solution Partners)](https://developers.facebook.com/documentation/business-messaging/whatsapp/solution-providers/overview)
* [Meta — Messaging limits](https://developers.facebook.com/documentation/business-messaging/whatsapp/messaging-limits)
* [Meta — Pricing](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing)
* [360dialog — Authentication messages](https://docs.360dialog.com/docs/resources/authentication-messages)
