# Inviare codici OTP WhatsApp da Node.js

URL: https://wa.genuka.com/it/docs/guides/whatsapp-otp-nodejs
Language: Italian

> 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](https://wa.genuka.com/it/docs/quickstart).
* Una chiave API, usata **solo lato server**: vedi [Autenticazione](https://wa.genuka.com/it/docs/authentication).
* 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](https://developers.facebook.com/documentation/business-messaging/whatsapp/solution-providers/overview)).
  Senza, il modello viene approvato ma ogni codice torna indietro con l'errore `131042`: vedi
  [errore 131042](https://wa.genuka.com/it/docs/errors/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](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/authentication-templates/authentication-templates)).

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

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

## Come creo il modello di autenticazione?

1. ### Invia il modello

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

   **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",
       // Dopo 5 minuti Meta smette di tentare la consegna: il codice sarebbe comunque scaduto.
       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 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".

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

**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 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;
}
```

**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="Risposta"
{ "data": { "messageId": "wamid.HBg…" } }
```

Un `200` significa che Meta ha **accettato** il messaggio, non che è arrivato. La consegna è
confermata via webhook, con lo stesso `messageId`.

> [!WARNING]
> **La lingua deve corrispondere esattamente**
>
> Per Meta, `en` e `en_US` sono due codici di lingua distinti
> ([supported languages](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/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](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes)).

## Come verifico il codice digitato dall'utente?

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

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

| 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](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/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](https://wa.genuka.com/it/docs/guides/receive-messages-webhooks) per la verifica
della firma.

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

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

### 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](https://developers.facebook.com/documentation/business-messaging/whatsapp/getting-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](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)
