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
fetchnativo. - 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).
| Parte | Cosa scegli | Regola di Meta |
|---|---|---|
| Corpo | Niente: testo predefinito, il tuo codice viene inserito | Nessun testo personalizzato |
| Avviso di sicurezza | add_security_recommendation: true | Facoltativo |
| Footer | code_expiration_minutes | Da 1 a 90 minuti |
| Pulsante | OTP con otp_type: COPY_CODE | Etichetta fino a 25 caratteri |
| Codice | Generato dal tuo server | Fino a 15 caratteri |
| Durata di validità (TTL) | messageSendTtlSeconds | Meta: 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.
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_statusil cuidata.eventèAPPROVEDoREJECTED, se il tuo endpoint è iscritto atemplate.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.
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.
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.
| Durata | Dove si imposta | Cosa fa |
|---|---|---|
code_expiration_minutes | Footer del modello | Ciò che legge l'utente: "scade tra 5 minuti" |
messageSendTtlSeconds | Modello | Oltre, Meta smette di tentare la consegna |
| Scadenza lato server | Il tuo database | L'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.
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
deliveredoreaddopo 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 Meta | Significato | Reazione |
|---|---|---|
131026 | Messaggio non consegnabile, per esempio un numero senza WhatsApp | Passa all'SMS, non riprovare |
131056 | Troppi messaggi allo stesso destinatario in poco tempo | Attendi prima di reinviare |
130429 | Raggiunto il throughput della Cloud API | Riprova con un backoff crescente |
132001 | Modello mancante in quella lingua o non approvato | Correggi il nome o la lingua |
131042 | Problema con il metodo di pagamento sull'account Meta del cliente: nessun codice parte | Passa 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 ilbusinessVerificationStatusdell'account e unverificationUrlche apre il Centro sicurezza dell'azienda; - lo
health_statusdel 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
- 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
Guide all'API WhatsApp Business
Guide all'API WhatsApp Business con Genuka WA: codici OTP, notifiche d'ordine, campagne, webhook, coesistenza, prezzi Meta e agenti IA.
Notifiche d'ordine WhatsApp dal tuo backend
Invia da WhatsApp conferme d'ordine, aggiornamenti di spedizione e di consegna dal tuo backend: modelli di utilità, variabili, idempotenza e stati di consegna.