Modelli di autenticazione

I modelli di autenticazione saranno disponibili in India a partire dal 1° luglio 2024.

Se la tua app mobile offre agli utenti la possibilità di ricevere password monouso o codici di verifica tramite WhatsApp, devi usare un modello di autenticazione.

I modelli di autenticazione sono costituiti da:

Testo predefinito fisso: <VERIFICATION_CODE> è il tuo codice di verifica.
Un disclaimer di sicurezza facoltativo: Per garantire la tua sicurezza, non condividere questo codice.
Un avviso di scadenza facoltativo: Questo codice scadrà tra <NUM_MINUTES> minuti.
Un pulsante per l'inserimento automatico con un tocco, un pulsante per copiare il codice o nessun pulsante se usi la modalità zero tocchi.

I pulsanti per l'inserimento automatico con un tocco sono la soluzione preferita perché offrono l'esperienza utente migliore. Tuttavia, sono attualmente supportati solo su Android e richiedono ulteriori modifiche al codice della tua app.

Consulta le linee guida aggiuntive per informazioni su quando è appropriato usare un modello di autenticazione.

Modelli di autenticazione per l'inserimento automatico con un tocco

I modelli di autenticazione includono un pulsante per l'inserimento automatico con un tocco.

Quando un utente WhatsApp tocca questo pulsante, il client WhatsApp attiva un'attività che apre l'app e le trasmette la password o il codice.

Per scoprire come usare questi modelli, consulta Modelli di autenticazione per l'inserimento automatico con un tocco.

Modelli di autenticazione per copiare il codice

I modelli di autenticazione per copiare il codice ti consentono di inviare agli utenti una password o un codice monouso unitamente a un pulsante per copiare il codice.

Quando un utente WhatsApp tocca il pulsante per copiare il codice, il client WhatsApp copia la password o il codice negli appunti del dispositivo. L'utente può quindi passare alla tua app e incollare la password o il codice.

Per scoprire come usare questi modelli, consulta Modelli di autenticazione per copiare il codice.

Modelli di autenticazione zero tocchi

I modelli di autenticazione zero tocchi consentono ai tuoi utenti di ricevere password o codici monouso via WhatsApp senza dover uscire dall'app.

Quando un utente nella tua app richiede una password o un codice e tu lo invii usando un modello di autenticazione zero tocchi, il client WhatsApp trasmette la password o il codice, che la tua app può acquisire con un ricevitore broadcast.

Per scoprire come usare questi modelli, consulta Modelli di autenticazione zero tocchi.

Best practice

Conferma il numero di telefono WhatsApp dell'utente prima di inviare la password o il codice monouso a quel numero.
Comunica chiaramente all'utente che la password o il codice saranno inviati al suo numero di telefono WhatsApp, specialmente se offri più modi per ricevere tali informazioni. Per consigli aggiuntivi, consulta Ottenere un consenso esplicito.
Quando l'utente incolla la password o il codice nella tua app o quest'ultima lo riceve come parte del flusso di inserimento automatico con un tocco, comunica all'utente in modo chiaro che l'informazione è stata ricevuta dall'app.

Consulta anche Best practice per autenticare gli utenti tramite WhatsApp.

Time-to-live

Qualora non riuscissimo a consegnare un messaggio a un utente WhatsApp, continueremo a tentare la consegna per un periodo di tempo noto come time-to-live.

Per impostazione predefinita, i messaggi hanno un time-to-live di 30 giorni, ma i modelli di autenticazione appena creati hanno un time-to-live predefinito di 10 minuti.

Se non riusciamo a consegnare un modello di autenticazione per un periodo di tempo che supera il suo time-to-live, smettiamo di riprovare e ignoriamo il messaggio. Se il tempo tra la tua richiesta di invio del messaggio del modello di autenticazione supera il time-to-live e non ricevi alcun webhook, devi supporre che il messaggio sia stato ignorato.

Per sovrascrivere il time-to-live predefinito quando crei un modello di autenticazione, includi la proprietà message_send_ttl_seconds con un valore impostato tra 60 e 600 secondi.

I modelli esistenti creati prima che questa funzionalità fosse resa disponibile hanno un time-to-live di 30 giorni. Se lo desideri, puoi modificare un modello esistente e sovrascriverne il time-to-value impostandone la proprietà message_send_ttl_seconds.

Puoi anche impostare la proprietà message_send_ttl_seconds di un modello di autenticazione su -1. Questo imposterà il time-to-live a 30 giorni.

Ti invitiamo a impostare un time-to-live per tutti i tuoi modelli di autenticazione preferibilmente uguale o inferiore al tempo di scadenza del codice, per assicurarti che i tuoi clienti ricevano un messaggio solo quando un codice è ancora utilizzabile.

Tieni presente che potrebbe verificarsi un leggero ritardo nella consegna del webhook di messaggio non riuscito, quindi è consigliabile prevedere un breve tempo di attesa prima di dedurre che il messaggio è stato ignorato.

Invio di messaggi con modello di autenticazione

Usa l'API Cloud o l'API On-Premises per inviare modelli di autenticazione approvati in un modello di messaggio.

Anteprime del modello

Puoi generare anteprime del testo del modello di autenticazione in varie lingue che includono o escludono la stringa dei suggerimenti sulla sicurezza e la stringa di scadenza del codice usando l'endpoint Account WhatsApp Business > Anteprime del modello di messaggio.

Sintassi della richiesta

GET /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_template_previews
  ?category=AUTHENTICATION,
  &language=<LANGUAGE>, // Optional
  &add_security_recommendation=<ADD_SECURITY_RECOMMENDATION>, // Optional
  &code_expiration_minutes=<CODE_EXPIRATION_MINUTES>, // Optional
  &button_types=<BUTTON_TYPES> // Optional

Parametri della stringa della query

Segnaposto Descrizione Valore di esempio

Segnaposto	Descrizione	Valore di esempio
`<LANGUAGE>` Lista separata da virgole	Facoltativo. Lista separata da virgole di codici lingua e relative varianti delle versioni linguistiche che desideri vengano restituite. Se omesso, saranno restituite le versioni di tutte le lingue supportate.	`en_US,es_ES`
`<ADD_SECURITY_RECOMMENDATION>` Booleano	Facoltativo. Imposta su `true` se vuoi che la stringa del corpo dei suggerimenti sulla sicurezza venga inclusa nella risposta. Se omesso, la stringa dei suggerimenti sulla sicurezza non sarà inclusa.	`true`
`<CODE_EXPIRATION_MINUTES>` Int64	Facoltativo. Imposta su un intero se vuoi che la stringa del piè di pagina di scadenza del codice venga inclusa nella risposta. Se omesso, la stringa del piè di pagina di scadenza del codice non sarà inclusa. Il valore indica il numero di minuti fino alla scadenza del codice. Minimo `1`, massimo `90`.	`10`
`<BUTTON_TYPES>` Lista di stringhe separata da virgole	Obbligatorio. Lista di stringhe separata da virgole che indica il tipo di pulsante. Se incluso, la risposta includerà il testo del pulsante per ogni pulsante nella risposta. Per i modelli di autenticazione, questo valore deve essere `OTP`.	`OTP`

<LANGUAGE>

Lista separata da virgole

Facoltativo.

Lista separata da virgole di codici lingua e relative varianti delle versioni linguistiche che desideri vengano restituite.

Se omesso, saranno restituite le versioni di tutte le lingue supportate.

en_US,es_ES

<ADD_SECURITY_RECOMMENDATION>

Booleano

Facoltativo.

Imposta su true se vuoi che la stringa del corpo dei suggerimenti sulla sicurezza venga inclusa nella risposta.

Se omesso, la stringa dei suggerimenti sulla sicurezza non sarà inclusa.

true

<CODE_EXPIRATION_MINUTES>

Int64

Facoltativo.

Imposta su un intero se vuoi che la stringa del piè di pagina di scadenza del codice venga inclusa nella risposta.

Se omesso, la stringa del piè di pagina di scadenza del codice non sarà inclusa.

Il valore indica il numero di minuti fino alla scadenza del codice.

Minimo 1, massimo 90.

10

<BUTTON_TYPES>

Lista di stringhe separata da virgole

Obbligatorio.

Lista di stringhe separata da virgole che indica il tipo di pulsante.

Se incluso, la risposta includerà il testo del pulsante per ogni pulsante nella risposta.

Per i modelli di autenticazione, questo valore deve essere OTP.

OTP

Esempio di richiesta

curl 'https://graph.facebook.com/v17.0/102290129340398/message_template_previews?category=AUTHENTICATION&languages=en_US,es_ES&add_security_recommendation=true&code_expiration_minutes=10&button_types=OTP' \
-H 'Authorization: Bearer EAAJB...'

Esempio di risposta

{
  "data": [
    {
      "body": "*{{1}}* is your verification code. For your security, do not share this code.",
      "buttons": [
        {
          "autofill_text": "Autofill",
          "text": "Copy code"
        }
      ],
      "footer": "This code expires in 10 minutes.",
      "language": "en_US"
    },
    {
      "body": "Tu código de verificación es *{{1}}*. Por tu seguridad, no lo compartas.",
      "buttons": [
        {
          "autofill_text": "Autocompletar",
          "text": "Copiar código"
        }
      ],
      "footer": "Este código caduca en 10 minutos.",
      "language": "es_ES"
    }
  ]
}

Gestione di gruppo

Usa l'endpoint Account WhatsApp Business > Upsert modelli di messaggi per aggiornare o creare in gruppo modelli di autenticazione in più lingue che includano o escludano gli avvisi facoltativi in merito a sicurezza e scadenza.

Se esiste già un modello con nome e lingua corrispondenti, il modello verrà aggiornato con il contenuto della richiesta; altrimenti, verrà creato un nuovo modello.

Sintassi della richiesta

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/upsert_message_templates

Corpo del post

{
  "name": "<NAME>",
  "languages": [<LANGUAGES>],
  "category": "AUTHENTICATION",
  "components": [
    {
      "type": "BODY",
      "add_security_recommendation": <ADD_SECURITY_RECOMMENDATION> // Optional
    },
    {
      "type": "FOOTER",
      "code_expiration_minutes": <CODE_EXPIRATION_MINUTES> // Optional
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "OTP",
          "otp_type": "<OTP_TYPE>",
          "package_name": "<PACKAGE_NAME>", // One-tap buttons only
          "signature_hash": "SIGNATURE_HASH>", // One-tap buttons only
        }
      ]
    }
  ]
}

Proprietà

Sono supportate tutte le proprietà di creazione del modello, con queste eccezioni:

La proprietà language non è supportata. Invece, usa languages e imposta il suo valore su un array di stringhe di codici lingua e relative varianti. Ad esempio: ["en_US","es_ES","fr"].
La proprietà text non è supportata.
La proprietà autofill_text non è supportata.

Esempio di richiesta di copia del codice

Questo esempio crea tre modelli di autenticazione in inglese, spagnolo e francese, con pulsanti per la copia del codice. Ogni modello si chiama "authentication_code_copy_code_button" e include i suggerimenti sulla sicurezza e la scadenza.

curl 'https://graph.facebook.com/v17.0/102290129340398/upsert_message_templates' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "name": "authentication_code_copy_code_button",
  "languages": ["en_US","es_ES","fr"],
  "category": "AUTHENTICATION",
  "components": [
    {
      "type": "BODY",
      "add_security_recommendation": true
    },
    {
      "type": "FOOTER",
      "code_expiration_minutes": 10
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "OTP",
          "otp_type": "COPY_CODE"
        }
      ]
    }
  ]
}'

Esempio di richiesta di inserimento automatico con un tocco

Questo esempio (1) aggiorna un modello esistente con il nome "authentication_code_autofill_button" e la lingua "en_US" e (2) crea due nuovi modelli di autenticazione in spagnolo e francese con pulsanti per l'inserimento automatico con un tocco. Entrambi i modelli appena creati si chiamano "authentication_code_autofill_button" e includono i suggerimenti sulla sicurezza e la scadenza.

curl 'https://graph.facebook.com/v17.0/102290129340398/upsert_message_templates' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "name": "authentication_code_autofill_button",
  "languages": ["en_US","es_ES","fr"],
  "category": "AUTHENTICATION",
  "components": [
    {
      "type": "BODY",
      "add_security_recommendation": true
    },
    {
      "type": "FOOTER",
      "code_expiration_minutes": 15
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "OTP",
          "otp_type": "ONE_TAP",
          "package_name": "com.example.luckyshrub",
          "signature_hash": "K8a%2FAINcGX7"
        }
      ]
    }
  ]
}'

Esempio di risposta

{
  "data": [
    {
      "id": "954638012257287",
      "status": "APPROVED",
      "language": "en_US"
    },
    {
      "id": "969725527415202",
      "status": "APPROVED",
      "language": "es_ES"
    },
    {
      "id": "969725530748535",
      "status": "APPROVED",
      "language": "fr"
    }
  ]
}

App di esempio

Consulta la nostra App di esempio per la password monouso (OTP) di WhatsApp per Android su GitHub. L'app di esempio mostra come inviare e ricevere password e codici OTP tramite l'API, come integrare i pulsanti per l'inserimento automatico con un tocco e per copiare il codice, come creare un modello e come avviare un server di esempio.

Altri contenuti da consultare

Account business ufficiale: ti consigliamo di richiedere lo stato di account business ufficiale per generare fiducia tra i tuoi utenti, riducendo in tal modo la probabilità che rimuovano o ignorino i tuoi messaggi.
Webhook per le conferme di lettura: ti consigliamo di effettuare l'iscrizione al campo dei webhook dei messaggi in modo da ricevere notifiche quando un utente riceve e legge il tuo modello di autenticazione con un pulsante OTP. Consulta Webhook per l'API Cloud o Webhook per l'API On-Premises.