AccediInizia la prova gratuita
Meta Tech Provider

Inviare codici di verifica (OTP) su WhatsApp

Per inviare un codice di verifica (OTP) su WhatsApp, un'azienda crea un template di autenticazione, il formato fisso di Meta "<code> is your verification code." con un pulsante di copia del codice o con un pulsante a un tocco, e il suo backend lo invia tramite la Cloud API con il codice inserito due volte, nel corpo e nel pulsante. I codici hanno al massimo 15 caratteri, e l'avviso di scadenza facoltativo va da 1 a 90 minuti.

easyCoexistence collega il tuo numero WhatsApp Business alla Cloud API di Meta tramite Coexistence e fornisce al tuo backend ciò che serve per inviare template di autenticazione: l'endpoint Send, il token di accesso e, tramite la tua AI, create_template e get_template_status.

15 characters

Il parametro più lungo accettato da un template di autenticazione; URL, media ed emoji non sono consentiti nel suo contenuto né nei suoi parametri.

1 to 90 minutes

Intervallo di code_expiration_minutes, che aggiunge al messaggio la riga "This code expires in N minutes."

10 minutes

Time-to-live predefinito di un template di autenticazione; può essere impostato da 30 secondi a 15 minuti.

131062

Errore restituito quando un template di autenticazione viene inviato a un ID utente con ambito aziendale invece che a un numero di telefono.

Primary device

I messaggi di autenticazione vengono recapitati solo al dispositivo WhatsApp principale dell'utente; i dispositivi collegati vedono invece un avviso.

20 msg/s

Throughput fisso di un numero Coexistence, il limite massimo per un picco di codici di accesso.

Che cos'è un template di autenticazione WhatsApp?

Il solo formato consentito da Meta per password monouso e codici di verifica: se un'app offre i codici tramite WhatsApp, deve usarne uno, e i template di utilità o di marketing non possono contenere una password. Il testo è fisso, "<code> is your verification code.", con due righe facoltative, "For your security, do not share this code." e "This code expires in <N> minutes." Ciò che scegli è il pulsante. WhatsApp disattiva l'inoltro di questi messaggi e, su iOS 26 e versioni successive, il codice viene proposto anche come suggerimento della tastiera senza alcun intervento da parte tua.

Copy codeTapping copies the code to the clipboard; the user pastes it in your app or site
One-tap autofillAndroid: the button opens your app and hands it the code; needs app changes and a handshake
Zero-tapAndroid only, no button: your app receives the code through a broadcast receiver

Come si crea il template di autenticazione?

Scegline uno dalla Template Library in WhatsApp Manager, oppure invialo tramite l'API, cosa che la tua AI può fare con create_template e la categoria AUTHENTICATION. Non invii alcun testo nel corpo: Meta lo genera dalle tue impostazioni, nella lingua che scegli, e trasforma il pulsante OTP in un pulsante URL alla creazione. Un template per ogni lingua. Il create_template del connettore non passa message_send_ttl_seconds, quindi si applica il time-to-live predefinito di 10 minuti, a meno che tu non lo modifichi tramite l'API di Meta.

create_template arguments for a copy-code template
{
  "connection_id": "<from list_numbers>",
  "name": "login_code",
  "language": "en_US",
  "category": "AUTHENTICATION",
  "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" }
    ]}
  ]
}

Come invia il codice il tuo backend?

Una richiesta all'endpoint /messages del numero per ogni codice, con il token di accesso ottenuto da get_api_credentials o dalla scheda "Plug in your own system" della dashboard. Lo stesso codice va inserito due volte: nel parametro del corpo e nel parametro del pulsante URL all'indice 0, e il destinatario deve essere un numero di telefono. Prima dell'invio, il backend genera il codice, memorizza un hash con un orario di scadenza e un contatore dei tentativi, e poi confronta ciò che l'utente digita con quell'hash.

Sending a login code from your backend
POST https://graph.facebook.com/<VERSION>/<PHONE_NUMBER_ID>/messages
Authorization: Bearer <ACCESS_TOKEN>

{
  "messaging_product": "whatsapp",
  "to": "5511987654321",
  "type": "template",
  "template": {
    "name": "login_code",
    "language": { "code": "en_US" },
    "components": [
      { "type": "body",
        "parameters": [{ "type": "text", "text": "482913" }] },
      { "type": "button", "sub_type": "url", "index": "0",
        "parameters": [{ "type": "text", "text": "482913" }] }
    ]
  }
}

Perché il codice arriva dal backend e non da un'automazione?

Perché il sistema che fa accedere l'utente deve creare il codice, ricordarlo e verificarlo, e solo quel sistema sa quando serve un codice. Le automazioni rispondono ai messaggi che i clienti inviano, e una schermata di accesso non scrive mai sul tuo numero. Il template stesso le esclude: il pulsante OTP trasporta il codice come variabile del pulsante, e il passaggio «Invia un template» compila solo le variabili del corpo, quindi non può inviare un template di autenticazione. La tua AI può inviarne uno tramite send_template, che passa i componenti dei pulsanti a Meta, ma è per un test, non per un flusso di accesso.

Che cosa rende sicuro un flusso OTP su WhatsApp?

Le best practice di Meta e i limiti del formato indicano la stessa checklist. Nessuna voce richiede altro oltre al tuo backend e alla Cloud API:

  • Conferma il numero WhatsApp con l'utente prima del primo codice, e spiega che il codice arriverà su WhatsApp.
  • Imposta il time-to-live uguale o inferiore alla scadenza del codice, così un recapito in ritardo non mostra mai un codice scaduto.
  • Limita tentativi e reinvii per numero, e fai scadere i codici al primo utilizzo.
  • Non rendere il codice WhatsApp l'unico fattore per il recupero dell'account: i numeri di telefono riassegnati possono ancora raggiungere un vecchio account WhatsApp.
  • Osserva il webhook di stato e proponi SMS o e-mail quando un codice non viene recapitato.

Che cosa cambia se il numero funziona anche nell'app WhatsApp Business?

L'invio funziona come su qualsiasi numero Cloud API, fino a 20 messaggi al secondo. Meta riporta nelle chat dell'app i messaggi inviati tramite l'API, quindi su un numero Coexistence anche i codici che invii compaiono in quelle chat sul telefono aziendale; tieni quel telefono solo con persone di cui ti fidi, oppure invia i codici da un numero separato. Le best practice di Meta chiedono inoltre che ogni azienda invii i template di autenticazione dal proprio numero, mai da uno condiviso tra aziende. L'autenticazione è una categoria di template a pagamento, addebitata per messaggio recapitato in base al paese del destinatario, con tariffe separate per autenticazione internazionale in alcuni mercati; easyCoexistence non applica alcun ricarico.

Come configurarlo

  1. Connect the numberConnect your WhatsApp Business number to easyCoexistence through Meta's Coexistence flow, or use a separate number reserved for codes.
  2. Create the authentication templateAsk your AI to submit login_code with create_template, category AUTHENTICATION, a copy-code button and an expiry, then check get_template_status for APPROVED.
  3. Store the credentials on your serverCall get_api_credentials or open "Plug in your own system" in the dashboard, and put the Send endpoint and access token in your backend's secrets.
  4. Build generate, send and verifyGenerate the code, store its hash with an expiry, send the template with the code in the body and button, then check the user's entry against the hash.
  5. Handle failuresRead failed statuses from the number's webhook, then offer SMS or email and show the user which number the code went to.

Errori comuni

  • Scrivere il codice in un template di utilità come "Your code is {{1}}". Meta consente le password solo nei template di autenticazione e rifiuta quelli di utilità o di marketing che le contengono.
  • Inviare il codice solo nel corpo. Il pulsante di copia codice richiede lo stesso valore come parametro; Meta si aspetta il codice due volte nella richiesta.
  • Mantenere un time-to-live di 30 giorni su un template di autenticazione più vecchio. Un telefono offline per un'ora riceve poi un codice scaduto; impostalo uguale o inferiore alla scadenza del codice.
  • Indirizzare il codice a un ID utente con ambito aziendale. I template di autenticazione vanno solo a numeri di telefono, e Meta restituisce l'errore 131062.
Farlo con EasyCoexistence

Il numero è monitorato 24/7, quindi una disconnessione che bloccherebbe i codici di accesso ti viene segnalata via e-mail. Da US$ 9 a US$ 0,75 per numero al mese, in calo man mano che aggiungi numeri, con i primi 3 giorni di prova gratuita.

Domande frequenti

È un codice OTP WhatsApp più economico di un codice SMS?

Meta addebita ogni messaggio di autenticazione recapitato alla tariffa del paese del destinatario, con tariffe speciali in alcuni mercati; i prezzi SMS variano per operatore e percorso. Confronta la tariffa di Meta con quella del tuo provider SMS per i tuoi paesi principali prima di passare.

È la stessa cosa del PIN di verifica in due passaggi di WhatsApp?

No. La verifica in due passaggi è il PIN a sei cifre che protegge il numero WhatsApp Business dell'azienda. Un template di autenticazione invia un codice ai tuoi clienti, così la tua app o il tuo sito può confermare la loro identità.

Gli utenti devono dare il consenso per ricevere i codici?

Sì. La policy di Meta richiede un'autorizzazione prima che un'azienda scriva a qualcuno, e le sue linee guida OTP suggeriscono di offrire una scelta di canali, come WhatsApp, SMS o e-mail. Scegliere WhatsApp nella schermata di accesso, accanto al numero, è quell'autorizzazione.

Un'agenzia può inviare codici per più clienti da un unico numero?

No. Le best practice di Meta richiedono che ogni azienda abbia un proprio account WhatsApp Business e un proprio numero di telefono per i template di autenticazione; condividerne uno tra aziende viola i termini e la policy di Meta. Collega invece un numero per ogni cliente.

Continua a leggere

Pronto per iniziare?

Configura WhatsApp Coexistence in pochi minuti, non in mesi. L'app continua a funzionare sul telefono.

Inizia la prova gratuita

Verificato il