Generatore di messaggi OTP per SMS e WhatsApp

Cosa contiene un buon template SMS OTP

Un messaggio di verifica ha un solo compito: far arrivare il codice giusto alla persona giusta in fretta, in un modo difficile da abusare. La maggior parte degli utenti legge il codice dalla notifica sulla schermata di blocco, che mostra solo la prima riga circa. Mettete il codice all'inizio o vicino all'inizio e rendete chiaro il brand, così l'utente sa quale servizio lo ha inviato.

La lunghezza conta per costi e affidabilità. Un SMS GSM-7 contiene 160 caratteri. Quando un messaggio viene diviso, ogni parte ne contiene 153. Un solo carattere fuori dall'alfabeto GSM-7, come una lettera araba, un'emoji, un apostrofo tipografico o una lettera accentata come “ó” o “ç”, porta l'intero messaggio a UCS-2. Il limite scende così a 70 caratteri, o 67 per parte. Un OTP di due parti costa il doppio e ha una probabilità leggermente più alta che una parte arrivi in ritardo. Il generatore mostra codifica e numero di segmenti per ogni variante e può sostituire le lettere accentate con quelle semplici, così i messaggi in spagnolo, portoghese e francese restano in GSM-7.

• Codice per primo o all'inizio: "482913 è il tuo codice Acme" compare nell'anteprima della notifica.
• Nome del brand: dice agli utenti quale servizio ha inviato il codice e rende più difficile il phishing.
• Scadenza: "Scade tra 5 minuti" fissa un'aspettativa e limita gli abusi.
• Avviso: "Non condividere questo codice con nessuno, nemmeno con il nostro personale."
• Niente link: gli operatori spesso filtrano gli OTP che contengono URL, e i link abituano gli utenti a toccare link di phishing.

Autofill su Android: il formato SMS Retriever

L'API SMS Retriever di Google permette a un'app Android di leggere l'SMS di verifica senza il permesso SMS e senza che l'utente digiti nulla. Secondo la documentazione di Google, il messaggio non deve superare 140 byte, deve contenere il codice monouso e deve includere una stringa hash di 11 caratteri che identifica la vostra app. Quel limite di 140 byte equivale a 160 caratteri GSM-7 o 70 caratteri UCS-2, quindi in pratica il messaggio deve stare in un solo SMS.

L'hash è costituito dai primi 11 caratteri di un hash SHA-256 codificato in base64 del nome del pacchetto e del certificato di firma. L'esempio di Google lo mette su una riga a sé alla fine: "Your ExampleApp code is: 123ABC78", una riga vuota, poi "FA+9qCX9VSu". Calcolate l'hash dal vostro keystore di produzione e scrivetelo nel codice sul server. Google dice di non usare stringhe hash calcolate dinamicamente sul client. Le versioni più vecchie della documentazione richiedevano che il messaggio iniziasse con "<#>". La pagina attuale non elenca quel prefisso. Non fa danni, ma usa 4 caratteri. Se non potete controllare il formato del messaggio, l'alternativa è l'API SMS User Consent: l'utente tocca una volta per consentire alla vostra app di leggere quel singolo messaggio.

Autofill su iPhone e web: codici legati al dominio

iOS e macOS rilevano i codici negli SMS in arrivo e li suggeriscono sopra la tastiera quando il campo è contrassegnato come campo per codice monouso: textContentType = .oneTimeCode in un'app nativa, oppure autocomplete="one-time-code" su un input HTML, come descritto nella documentazione per sviluppatori di Apple. Da iOS 14 e macOS Big Sur, Safari supporta anche i codici monouso legati all'origine, un formato definito nella specifica WICG “Origin-bound one-time codes delivered via SMS”.

In quel formato l'ultima riga del messaggio è "@example.com #747723": il dominio con una @ davanti, poi esattamente uno spazio, poi il codice con un # davanti. Un terzo valore facoltativo, "@embedded.example", indica un sito incorporato. Il testo leggibile può precedere l'ultima riga. Qualsiasi altro testo tra i valori rende la riga non valida. L'AutoFill propone poi il codice solo su quel dominio o nelle app associate, il che rende molto più difficile il phishing. Il generatore costruisce un messaggio combinato che porta l'hash Android e l'ultima riga legata al dominio e, per le lingue in alfabeto latino, sta ancora in 140 byte. In arabo, inviate separatamente i formati Android e iOS.

Template di autenticazione WhatsApp: cosa potete e non potete cambiare

WhatsApp richiede un template di autenticazione per inviare password monouso, e Meta fissa il corpo. In inglese è "<code> is your verification code." Potete aggiungere la riga di sicurezza di Meta, "For your security, do not share this code.", e un piè di pagina di scadenza, "This code expires in <N> minutes.", dove code_expiration_minutes è compreso tra 1 e 90. Ogni versione linguistica usa la traduzione fissa di Meta. URL, contenuti multimediali ed emoji non sono supportati.

Il pulsante lo scegliete voi. Copia codice funziona ovunque. L'autofill one-tap apre la vostra app Android con il codice e richiede il nome del pacchetto, l'hash della firma e un handshake. Lo zero-tap (solo Android) non ha pulsante: WhatsApp trasmette il codice direttamente alla vostra app. Su iOS 26 e successivi, i suggerimenti della tastiera propongono il codice dalla notifica senza alcuna integrazione. Il codice può arrivare a 15 caratteri e compare due volte nella richiesta di invio, come parametro del corpo e come parametro del pulsante (sub_type "url"). Il testo del pulsante Copia codice è limitato a 25 caratteri. Impostate message_send_ttl_seconds perché i codici scaduti non vengano consegnati in ritardo. Meta consegna inoltre i messaggi di autenticazione sulla Cloud API solo al dispositivo principale dell'utente; i dispositivi collegati vedono un avviso mascherato.

Checklist di sicurezza e strategia di fallback

Il messaggio è la parte facile. La maggior parte delle frodi OTP e degli sforamenti di costo deriva da regole deboli attorno ad esso. Sono raccomandazioni molto diffuse, non requisiti di legge. Adattate i numeri al vostro rischio.

Usate una cascata per la consegna. Provate prima WhatsApp dove l'utente lo ha, ripiegate sull'SMS dopo un breve timeout (ad esempio 30–60 secondi senza ricevuta di consegna) e offrite come ultima risorsa una chiamata vocale che legge il codice per i telefoni fissi e la scarsa copertura. Nel GCC l'OTP è traffico transazionale, quindi le regole promozionali come il prefisso mittente “AD-” degli EAU non si applicano. Il vostro Sender ID deve comunque essere registrato nella maggior parte dei mercati, quindi verificate le regole locali prima del lancio.

• 6 cifre è il valore predefinito comune; generate i codici con un generatore casuale crittograficamente sicuro.
• Validità breve (5–10 minuti), monouso, e conservate solo un hash del codice.
• Limitate la frequenza degli invii per numero di telefono e per IP, imponete un tempo di attesa tra i reinvii e bloccate dopo circa 5 tentativi errati.
• Prevenite lo SMS pumping (traffico gonfiato artificialmente) consentendo solo i paesi di destinazione che servite.
• Non mettete mai il codice in un link o nell'URL e non chiedete mai agli utenti di leggerlo a un operatore.