Genuka WA docs

Inviare codici OTP WhatsApp da Node.js

Invia password monouso su WhatsApp da Node.js con Genuka WA: modello di autenticazione, pulsante per copiare il codice, scadenza, verifica e fallback via SMS.

Per inviare un codice monouso WhatsApp da Node.js con Genuka WA, crea una volta un modello AUTHENTICATION con un pulsante per copiare il codice, poi chiama POST /api/v1/messages con la scorciatoia otp. Meta scrive il testo del messaggio; tu fornisci solo il codice, e il tuo server gestisce scadenza e verifica. Il passaggio che sfugge a molti: l'azienda deve prima superare la verifica dell'azienda di Meta (o un altro percorso di crescita di Meta).

Ultimo aggiornamento: 8 ottobre 2026

Cosa mi serve prima di iniziare?

  • Un numero collegato a Genuka WA e il suo connectionId: vedi la guida rapida.
  • Una chiave API, usata solo lato server: vedi Autenticazione.
  • Node.js 22 o successivo: una linea LTS ancora supportata, con fetch nativo.
  • Un'azienda che abbia superato la verifica dell'azienda di Meta (o un altro percorso di crescita di Meta). È il requisito che si scopre troppo tardi: senza, Meta rifiuta di creare il modello, con un messaggio di errore che incolpa l'app invece dell'azienda. L'ultima sezione di questa guida ne parla.
  • Un metodo di pagamento sul WhatsApp Business Account, presso Meta. Genuka è un Meta Tech Provider, non un BSP: Meta fattura direttamente l'account, e un cliente registrato tramite un Tech Provider deve aggiungere il proprio metodo di pagamento (Meta, Partners). Senza, il modello viene approvato ma ogni codice torna indietro con l'errore 131042: vedi errore 131042.

Come funziona un OTP WhatsApp?

Un codice monouso viaggia in un modello di categoria AUTHENTICATION. A differenza delle altre categorie, non ne scrivi il testo: Meta fornisce un corpo predefinito e vi inserisce il tuo codice, e tu scegli solo le opzioni intorno (documentazione Meta).

ParteCosa scegliRegola di Meta
CorpoNiente: testo predefinito, il tuo codice viene inseritoNessun testo personalizzato
Avviso di sicurezzaadd_security_recommendation: trueFacoltativo
Footercode_expiration_minutesDa 1 a 90 minuti
PulsanteOTP con otp_type: COPY_CODEEtichetta fino a 25 caratteri
CodiceGenerato dal tuo serverFino a 15 caratteri
Durata di validità (TTL)messageSendTtlSecondsMeta: 10 min per impostazione predefinita, da 30 s a 15 min; Genuka WA accetta da 60 a 600 s

URL, media ed emoji non sono supportati in questo tipo di modello (documentazione Meta, copy code button).

Copia codice, one-tap o zero-tap?

COPY_CODE funziona su qualsiasi telefono: l'utente tocca il pulsante e incolla il codice. ONE_TAP e ZERO_TAP passano il codice alla tua app Android e richiedono il suo package_name e il suo signature_hash: vedi il riferimento API. Inizia con COPY_CODE.

Come creo il modello di autenticazione?

Invia il modello

Una chiamata, una volta sola. Annota la lingua che scegli: ogni invio deve usare esattamente la stessa.

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 risposta 201 contiene il modello salvato, con il suo id e il suo status. Nella dashboard, l'equivalente è Modelli › Nuovo modello, categoria Autenticazione, pulsante "Copy code".

Attendi l'approvazione

Meta esamina il modello. Il verdetto ti arriva in tre modi:

  • un webhook template_status il cui data.event è APPROVED o REJECTED, se il tuo endpoint è iscritto a template.status_changed (o a tutti gli eventi);
  • GET /api/v1/templates/{id}, che restituisce lo stato e la sua cronologia;
  • POST /api/v1/templates/sync, che rilegge gli stati da Meta se un webhook è andato perso.

Si può inviare solo un modello approved.

Come invio il codice da Node.js?

La scorciatoia otp mette il codice in entrambi i punti che Meta richiede per un modello di autenticazione: il parametro del corpo e il parametro del pulsante. Non scrivi tu i components.

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 e messageSendTtlSeconds
const MAX_ATTEMPTS = 5;

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

/** Il corpo della risposta: `data` in caso di successo, altrimenti `error` (più `meta` se Meta ha rifiutato). */
type ApiResult = {
  data?: { messageId: string };
  error?: string;
  message?: string;
  meta?: { errorClass?: string; retryable?: boolean; code?: number };
};

// In memoria per l'esempio. In produzione: Redis o il tuo database, con la stessa scadenza,
// altrimenti un secondo server non conoscerà il codice emesso dal primo.
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 generatore crittografico, mai 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 internazionale con il +, ad es. "+237699001122"
      // Imposta sempre `language`: senza, l'invio punta a "en_US".
      template: { name: "login_code", language: "en", otp: code },
    }),
  });

  // Un 5xx della CDN non è JSON: senza questo catch, l'errore di parsing nasconderebbe lo stato.
  const body = (await response.json().catch(() => ({}))) as ApiResult;
  if (!response.ok || !body.data) {
    // body.meta.errorClass ti dice chi può risolvere: vedi "E se il codice non arriva mai?"
    throw new Error(`OTP not sent: ${response.status} ${body.error ?? ""} — ${body.message ?? ""}`);
  }

  // Un nuovo codice sostituisce il precedente: un solo codice valido per numero alla volta.
  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 che Meta ha accettato il messaggio, non che è arrivato. La consegna è confermata via webhook, con lo stesso messageId.

La lingua deve corrispondere esattamente

Per Meta, en e en_US sono due codici di lingua distinti (supported languages): un modello approvato in en non esiste in en_US. Inviare in una lingua in cui il modello non esiste, o non è approvato, fallisce con l'errore 132001 (codici di errore di Meta).

Come verifico il codice digitato dall'utente?

La verifica non passa mai da WhatsApp: avviene interamente dalla tua parte.

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

  // Limita i tentativi: un codice a 6 cifre cede a 1,000,000 tentativi nel caso peggiore, molti meno se nessuno li conta.
  if (entry.attempts >= MAX_ATTEMPTS) return false;
  entry.attempts += 1;

  // Due digest SHA-256 esadecimali: stessa lunghezza, confronto a tempo costante.
  const ok = crypto.timingSafeEqual(
    Buffer.from(entry.codeHash, "hex"),
    Buffer.from(hash(phone, input.trim()), "hex"),
  );

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

Quattro regole tengono insieme il tutto: un codice per numero alla volta, uso singolo, un numero limitato di tentativi e una scadenza decisa dal tuo server.

Come imposto scadenza e durata di validità?

Coesistono tre durate. Impostale allo stesso valore.

DurataDove si impostaCosa fa
code_expiration_minutesFooter del modelloCiò che legge l'utente: "scade tra 5 minuti"
messageSendTtlSecondsModelloOltre, Meta smette di tentare la consegna
Scadenza lato serverIl tuo databaseL'unica che conta quando verifichi

Quando un messaggio non può essere consegnato, WhatsApp riprova per la durata di validità del modello e poi lo scarta; se nel frattempo non è arrivato alcuno stato delivered o read, considera il messaggio perso (documentazione Meta, time-to-live). Un codice consegnato dopo la scadenza è peggio di uno mai consegnato: l'utente lo digita, viene rifiutato e non capisce perché.

E se il codice non arriva mai?

Segui il messaggio tramite il suo messageId nel tuo ricevitore di webhook: vedi Ricevere risposte e stati via webhook per la verifica della firma.

Nel tuo ricevitore di webhook (firma già verificata)
if (event.type === "message_status") {
  const { id: messageId, status, errors } = event.data;
  // `read` conta come consegnato: a volte Meta non invia `delivered` (vedi sotto).
  if (status === "delivered" || status === "read") await markOtpDelivered(messageId);
  if (status === "failed") await markOtpUndeliverable(messageId, errors?.[0]?.code);
}

Non aspettare solo delivered. Quando l'utente ha la chat aperta nel momento in cui arriva il messaggio (il caso tipico per un codice che sta aspettando), Meta lo considera consegnato e letto insieme e invia solo read (documentazione Meta, statuses).

Poi, nella tua interfaccia:

  • Errore esplicito: proponi subito un altro canale. Meta stessa raccomanda di lasciar scegliere agli utenti tra WhatsApp, email e SMS (best practice di Meta).
  • Nessun delivered o read dopo una trentina di secondi: mostra "Ricevi il codice via SMS" invece di inviare un secondo codice WhatsApp allo stesso numero.
  • Reinvio: imponi un intervallo tra le richieste e invalida il codice precedente a ogni invio.
Codice MetaSignificatoReazione
131026Messaggio non consegnabile, per esempio un numero senza WhatsAppPassa all'SMS, non riprovare
131056Troppi messaggi allo stesso destinatario in poco tempoAttendi prima di reinviare
130429Raggiunto il throughput della Cloud APIRiprova con un backoff crescente
132001Modello mancante in quella lingua o non approvatoCorreggi il nome o la lingua
131042Problema con il metodo di pagamento sull'account Meta del cliente: nessun codice partePassa all'SMS; il cliente sistema la fatturazione presso Meta: vedi errore 131042

Quando Meta rifiuta l'invio sul momento, o un controllo sul modello o sul numero lo blocca prima della chiamata, la risposta è un 400 (409 per un problema di configurazione) il cui error è send_<class>, con un oggetto meta che contiene errorClass e il code di Meta. È la classe a decidere: recipient_permanent (cambia canale), retryable o recipient_throttled (riprova più tardi), template o config (il problema è tuo, non dell'utente: avvisa il team). I rifiuti di Genuka WA stesso non hanno meta: leggi error. 400 missing_fields e 400 recipient_is_sender sono bug nella richiesta. Gli altri bloccano ogni codice finché l'account non viene sistemato: 402 subscription_past_due (la prova o il periodo pagato è scaduto), 402 plan_limit_messages (la quota del periodo è esaurita), 409 number_released, 403 account_deactivated e 404 connection_not_found. In uno qualsiasi di questi casi, invia subito il codice via SMS o email e avvisa il team: l'utente sta aspettando sulla schermata di accesso.

Perché Meta rifiuta di creare il mio modello di autenticazione?

Meta riserva la categoria AUTHENTICATION agli account che soddisfano due condizioni: hanno completato uno dei suoi percorsi di crescita (in pratica la verifica dell'azienda di Meta o la verifica guidata dal partner) e hanno un limite di messaggi di almeno 2.000 (360dialog, documentazione authentication messages). Le categorie MARKETING e UTILITY non sono interessate.

Ecco cosa vediamo sugli account collegati a Genuka WA quando l'azienda non è verificata:

  • Graph rifiuta la creazione con "Application does not have permission for this action". Nomina l'app, ma la causa è l'azienda del cliente: nessuna chiave o impostazione di permesso la cambierà. Genuka WA risponde quindi 403 business_not_verified, con il businessVerificationStatus dell'account e un verificationUrl che apre il Centro sicurezza dell'azienda;
  • lo health_status del WhatsApp Business Account riporta l'errore 141010, "The Business has not passed business verification".

La soluzione è completare la verifica dell'azienda nel Meta Business Suite del cliente, poi creare di nuovo il modello. I dettagli sono nella pagina dell'errore 141010.

Puoi anche leggere un indizio in GET /api/v1/numbers/{connectionId}/health: il campo messagingLimitTier. Un nuovo portafoglio aziendale parte da 250 destinatari unici ogni 24 ore fuori dalla finestra del servizio clienti; la verifica dell'azienda è uno dei modi per portarlo a 2.000 (documentazione Meta, messaging limits).

FAQ

Posso personalizzare il testo del messaggio OTP?

No. Il corpo di un modello di autenticazione è fissato da Meta; tu imposti solo l'avviso di sicurezza, la durata mostrata nel footer e l'etichetta del pulsante.

Quanto costa un OTP WhatsApp?

Meta addebita i modelli consegnati per categoria e paese del destinatario (prezzi di Meta), fatturati direttamente al WhatsApp Business Account del cliente. Genuka WA non aggiunge ricarichi: ogni invio conta semplicemente sulla quota di messaggi del tuo abbonamento: vedi i piani.

L'utente deve scrivermi prima di ricevere un codice?

No: un modello può essere inviato fuori dalla finestra di 24 ore. Ti serve però il consenso della persona, e Meta pone due condizioni: indicare chiaramente che accetta di ricevere messaggi dalla tua azienda, e nominare quell'azienda (documentazione Meta, opt-in). Sulla schermata di accesso, una riga come "Ricevi il mio codice di accesso da [Nome dell'azienda] su WhatsApp" accanto al campo del numero di telefono copre entrambe.

Cosa succede se il numero non ha un account WhatsApp?

Lo stato torna failed con il codice 131026. Non riprovare su WhatsApp: proponi SMS o email.

Fonti

In questa pagina