En esta sección
Guías / Códigos OTP por WhatsApp

Códigos OTP por WhatsApp

Envía códigos de verificación por WhatsApp desde tu backend con una plantilla de autenticación. Tú generas y validas el código; Meteor lo entrega.

Actualizada el Ver .md
StackNode · SDK de TypeScript
Endpointschannels.createTemplate · channels.templates · contacts.create · channels.whatsapp.sendTemplate con purpose: 'authentication'

Sirve para el registro, el inicio de sesión o la confirmación de un pago en tu plataforma: tu usuario escribe su número, le llega un código por WhatsApp y lo escribe de vuelta en tu pantalla.

Quién hace qué

Es lo primero que hay que tener claro, porque define todo lo demás:

PasoLo hace
Generar el código (por ejemplo, 6 dígitos al azar)Tu backend
Guardarlo con su vencimiento y sus intentosTu backend
Entregarlo por WhatsApp con la plantilla de autenticaciónMeteor
Comparar lo que la persona escribió con lo que guardasteTu backend

Meteor no genera ni valida el código, y no lo guarda: en el chat del contacto queda solo la nota «Código de verificación enviado por WhatsApp», nunca el código. Así el código vive en un solo lugar, el tuyo.

Lo que necesitas

El envío de OTP está disponible para todas las cuentas. Meteor puede apagarlo en una cuenta puntual; si te pasa, la respuesta es authentication_send_not_enabled y hay que escribir a soporte.

1. Crear la plantilla de autenticación (una sola vez)

Meta fija la forma de estas plantillas: el texto lo pone Meta en el idioma de la plantilla («*123456* es tu código de verificación»). Tú solo eliges si lleva el aviso de seguridad y cuántos minutos dura el código.

const canales = await met.channels.list();
const whatsapp = canales.find((c) => c.type === 'whatsapp')!;

await met.channels.createTemplate(whatsapp.id, {
  name: 'codigo_verificacion',
  language: 'es',
  category: 'AUTHENTICATION',
  components: [
    // Sin `text`: Meta rechaza un BODY con texto en esta categoría.
    { type: 'BODY', add_security_recommendation: true },
    { type: 'FOOTER', code_expiration_minutes: 10 },
    // Botón para copiar el código. Sin `text`: Meta pone «Copiar código».
    { type: 'BUTTONS', buttons: [{ type: 'OTP', otp_type: 'COPY_CODE' }] },
  ],
});

La plantilla nace en revisión (PENDING). Antes de usarla, confirma que quedó APPROVED y de qué cuenta es:

const { data } = await met.channels.templates(whatsapp.id, { name: 'codigo_verificacion' });
const otp = data.find((t) => t.name === 'codigo_verificacion' && t.language === 'es');
// otp.status === 'APPROVED' && otp.category === 'AUTHENTICATION'

Si tienes varias cuentas de WhatsApp en el canal, la plantilla tiene que estar aprobada en la cuenta de la línea que envía (ver Plantillas de WhatsApp por API).

2. El contacto tiene que existir

El código va a un contacto de tu workspace, no a un número suelto. Si la persona es nueva, créalo primero con su número:

const contacto = await met.contacts.create({ name: 'Ana Pérez', phone: '+573001234567' });

Un contacto bloqueado en Meteor no recibe códigos.

3. Generar el código y enviarlo

import { randomInt } from 'node:crypto';

const codigo = String(randomInt(0, 1_000_000)).padStart(6, '0');
await guardarCodigo(usuario.id, codigo, { venceEn: '10m', intentos: 0 }); // tu base

await met.channels.whatsapp.sendTemplate(whatsapp.id, {
  contact_id: contacto.id,
  template_name: 'codigo_verificacion',
  language: 'es',
  purpose: 'authentication',
  components: [
    { type: 'body', parameters: [{ type: 'text', text: codigo }] },
    // El botón de copiar lleva el MISMO código.
    { type: 'button', sub_type: 'url', index: '0', parameters: [{ type: 'text', text: codigo }] },
  ],
});

Con purpose: 'authentication' Meteor verifica, antes de mandar nada, que la plantilla sea de autenticación, que esté aprobada en la cuenta de la línea y que el contacto sea de tu workspace. Si algo no cuadra, no se envía ningún mensaje.

Este envío no toca la atención del chat: no reactiva al Met ni cambia la asignación de la conversación.

Probar sin enviar: dry_run: true valida la plantilla, la línea y el contacto y devuelve el destinatario, sin llamar a Meta. La respuesta nunca trae el código.

4. Validar el código

Cuando la persona escribe el código en tu pantalla, lo comparas tú con lo que guardaste. Unas reglas que conviene respetar:

Errores

CódigoHTTPQué pasóQué hacer
authentication_send_not_enabled403El envío de OTP está apagado en tu cuentaEscribir a soporte
authentication_template_required403La plantilla no existe con ese nombre e idioma, no está aprobada o no es AUTHENTICATION en la cuenta de la líneaRevisar channels.templates
authentication_template_unverifiable503No se pudo confirmar la plantilla o la cuenta con MetaReintentar en unos segundos
authentication_contact_unverifiable503No se pudo verificar el contactoReintentar
—404El contacto no es de tu workspaceCrear el contacto (paso 2)
authentication_provider_rejected400WhatsApp no aceptó el envío; trae provider_codeVer el código de Meta (por ejemplo 131026: el número no tiene WhatsApp)

Para reintentos sin duplicar el envío, usa una clave de idempotencia (ver Errores e idempotencia), y revisa los topes de tu plan en Límites.