Modèles d’authentification

Les modèles d’authentification seront disponibles en Inde à partir du 1er juillet 2024.

Si votre application mobile propose aux utilisateurs et utilisatrices de recevoir des mots de passe à usage unique ou des codes de vérification via WhatsApp, vous devez utiliser un modèle d’authentification.

Ces modèles d’authentification contiennent les éléments suivants :

Un texte prédéfini : <VERIFICATION_CODE> est votre code de vérification.
Un avertissement de sécurité facultatif : Pour votre sécurité, ne partagez pas ce code.
Un avertissement d’expiration (facultatif) : Ce code expire dans <NUM_MINUTES> minutes.
Un bouton de saisie automatique en un clic, un bouton de copie de code ou aucun bouton si vous utilisez l’authentification sans clic.

Les boutons de saisie automatique en un clic sont la solution privilégiée, car ils offrent la meilleure expérience d’utilisation. Toutefois, seuls les systèmes d’exploitation Android prennent actuellement en charge les boutons de saisie automatique en un clic, sous réserve d’autres modifications du code de votre application.

Voir les règles supplémentaires pour savoir dans quels cas utiliser un modèle d’authentification.

Modèles d’authentification du bouton de saisie automatique en un clic

Les modèles d’authentification comprennent un bouton de saisie automatique en un clic.

Lorsqu’un utilisateur ou une utilisatrice de WhatsApp appuie sur le bouton de saisie automatique, le client WhatsApp déclenche une activité qui ouvre votre application et lui délivre le mot de passe ou le code.

Voir Modèles d’authentification du bouton de saisie automatique en un clic pour découvrir comment les utiliser.

Modèles d’authentification du bouton de copie du code

Les modèles d’authentification de copie du code vous permettent d’envoyer un mot de passe ou un code à usage unique ainsi qu’un bouton de copie du code à vos utilisateurs et utilisatrices.

Lorsque ce bouton est activé, le client WhatsApp copie le mot de passe ou le code dans le Presse-papiers de l’appareil. L’utilisateur ou l’utilisatrice peut ensuite basculer sur votre application et coller le mot de passe ou le code dans votre application.

Voir Modèles d’authentification du bouton de copie du code pour découvrir comment les utiliser.

Modèles d’authentification sans clic

Les modèles d’authentification sans clic permettent aux utilisateurs et utilisatrices de recevoir des mots de passe ou codes à usage unique via WhatsApp sans quitter votre application.

Lorsque les utilisateur·ices demandent un mot de passe ou un code que vous leur envoyez via un modèle d’authentification sans clic, le client WhatsApp diffuse le mot de passe ou le code inclus de sorte que votre application puisse le capturer avec un récepteur de diffusion.

Voir Modèles d’authentification sans clic pour découvrir comment les utiliser.

Recommandations

Confirmez le numéro de téléphone WhatsApp de l’utilisateur·ice avant de lui envoyer le code ou mot de passe à usage unique.
Indiquez clairement à votre utilisateur·ice que le mot de passe ou le code sera envoyé à son numéro de téléphone WhatsApp, en particulier si vous lui proposez plusieurs façons de recevoir un mot de passe ou un code. Pour d’autres astuces, voir Obtenir un consentement.
Lorsque l’utilisateur·ice colle le mot de passe ou le code dans votre application ou que votre application le reçoit via un bouton de saisie automatique en un clic, faites clairement savoir à l’utilisateur·ice que votre application l’a capturé.

Voir aussi Recommandations pour l’authentification des utilisateur·ices via WhatsApp.

Durée de vie

Quand nous ne parvenons pas à distribuer un message à un utilisateur ou une utilisatrice WhatsApp, nous poursuivons les tentatives de distribution du message durant une période appelée durée de vie.

Par défaut, les messages ont une durée de vie de 30 jours, mais les modèles d’authentification qui viennent d’être créés ont une durée de vie par défaut de 10 minutes.

Si nous ne parvenons pas à distribuer un modèle d’authentification pendant sa durée de vie, nous ne tenterons plus de le renvoyer. Si le temps écoulé entre votre demande d’envoi d’un message basé sur un modèle d’authentification est supérieur à la durée de vie du modèle d’authentification, et que vous ne recevez aucun webhook, vous pouvez en déduire que le message n’a pas été distribué.

Pour remplacer la durée de vie par défaut lors de la création d’un modèle d’authentification, ajoutez la propriété message_send_ttl_seconds définie sur une valeur comprise entre 60 et 600 secondes.

Les modèles existants créés avant la mise à disposition de cette fonctionnalité ont une durée de vie de 30 jours. Si vous le souhaitez, vous pouvez modifier un modèle existant ainsi que sa durée de vie en définissant sa propriété message_send_ttl_seconds.

Vous pouvez également définir la propriété message_send_ttl_seconds d’un modèle d’authentification sur -1. Ainsi, la durée de vie sera définie sur 30 jours.

Nous vous recommandons de définir la durée de vie de tous vos modèles d’authentification, de préférence sur une valeur égale ou inférieure au délai d’expiration de votre code, pour vous assurer que votre clientèle dispose d’un code encore utilisable lorsqu’elle reçoit un message.

Notez que la distribution des messages webhook d’échec peut avoir un retard mineur. Il est donc préférable de prévoir un petit délai avant de considérer un message comme non distribué.

Envoi de messages basés sur un modèle d’authentification

Utilisez l’API Cloud ou l’API On-Premises pour envoyer des messages basés sur un modèle d’authentification approuvé.

Aperçus des modèles

Vous pouvez générer des aperçus du texte d’un modèle d’authentification dans différentes langues, qui incluent ou excluent la chaîne de recommandation de sécurité et la chaîne du code d’expiration, à l’aide du point de terminaison Compte WhatsApp Business > Aperçus du modèle de message.

Syntaxe de la requête

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

Paramètres de chaîne de requête

Espace réservé Description Exemple de valeur

Espace réservé	Description	Exemple de valeur
`<LANGUAGE>` Liste de valeurs séparées par une virgule	Facultatif. Liste des codes de langue et de paramètres régionaux séparés par une virgule, correspondant aux versions traduites que vous souhaitez obtenir. Si vous omettez ce paramètre, vous obtenez une version traduite dans toutes les langues prises en charge.	`en_US,es_ES`
`<ADD_SECURITY_RECOMMENDATION>` Booléen	Facultatif. Définissez ce paramètre sur `true` si vous souhaitez que la chaîne de recommandation de sécurité soit incluse dans le corps de la réponse. Si vous omettez ce paramètre, la chaîne de la recommandation de sécurité ne sera pas incluse.	`true`
`<CODE_EXPIRATION_MINUTES>` Int64	Facultatif. Définissez ce paramètre sur un entier si vous souhaitez que la chaîne d’expiration du code soit incluse dans le pied de la réponse. Si vous omettez ce paramètre, la chaîne de la recommandation de sécurité ne sera pas incluse dans le pied. La valeur indique le délai d’expiration du code en minutes. Minimum `1`, maximum `90`.	`10`
`<BUTTON_TYPES>` Liste de chaînes séparées par une virgule	Obligatoire. Liste de chaînes séparées par une virgule indiquant le type de bouton. Si vous incluez ces paramètres, la réponse contiendra le texte du bouton pour chaque bouton inclus. Pour les modèles d’authentification cette valeur doit être `OTP`.	`OTP`

<LANGUAGE>

Liste de valeurs séparées par une virgule

Facultatif.

Liste des codes de langue et de paramètres régionaux séparés par une virgule, correspondant aux versions traduites que vous souhaitez obtenir.

Si vous omettez ce paramètre, vous obtenez une version traduite dans toutes les langues prises en charge.

en_US,es_ES

<ADD_SECURITY_RECOMMENDATION>

Booléen

Facultatif.

Définissez ce paramètre sur true si vous souhaitez que la chaîne de recommandation de sécurité soit incluse dans le corps de la réponse.

Si vous omettez ce paramètre, la chaîne de la recommandation de sécurité ne sera pas incluse.

true

<CODE_EXPIRATION_MINUTES>

Int64

Facultatif.

Définissez ce paramètre sur un entier si vous souhaitez que la chaîne d’expiration du code soit incluse dans le pied de la réponse.

Si vous omettez ce paramètre, la chaîne de la recommandation de sécurité ne sera pas incluse dans le pied.

La valeur indique le délai d’expiration du code en minutes.

Minimum 1, maximum 90.

10

<BUTTON_TYPES>

Liste de chaînes séparées par une virgule

Obligatoire.

Liste de chaînes séparées par une virgule indiquant le type de bouton.

Si vous incluez ces paramètres, la réponse contiendra le texte du bouton pour chaque bouton inclus.

Pour les modèles d’authentification cette valeur doit être OTP.

OTP

Exemple de requête

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...'

Exemple de réponse

{
  "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"
    }
  ]
}

Gestion groupée

Utilisez le point de terminaison Compte WhatsApp Business > Actualiser ou insérer des modèles de message pour créer ou mettre à jour plusieurs modèles d’authentification dans différentes langues incluant ou non les avertissements facultatifs d’expiration et de sécurité.

Si un modèle associé au même nom et à la même langue existe déjà, il sera mis à jour à l’aide des contenus de la requête. Dans le cas contraire, un nouveau modèle sera créé.

Syntaxe de la requête

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/upsert_message_templates

Corps de la requête 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
        }
      ]
    }
  ]
}

Propriétés

Toutes les propriétés de création de modèles sont prises en charge, à l’exception des suivantes :

La propriété language n’est pas prise en charge. À la place, utilisez languages et définissez sa valeur sur un tableau de chaînes représentant les codes de langue et de paramètre régional. Par exemple : ["en_US","es_ES","fr"].
La propriété text n’est pas prise en charge.
La propriété autofill_text n’est pas prise en charge.

Exemple de requête de copie de code

Cet exemple crée trois modèles d’authentification en anglais, espagnol et français, avec des boutons de copie de code. Chaque modèle est nommé « authentication_code_copy_code_button » et inclut la recommandation de sécurité et le délai d’expiration.

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"
        }
      ]
    }
  ]
}'

Exemple de requête de saisie automatique en un clic

Cet exemple (1) met à jour un modèle existant associé au nom « authentication_code_autofill_button » et à la langue « en_US » et (2) crée deux nouveaux modèles d’authentification en espagnol et en français avec des boutons de saisie automatique en un clic. Les deux nouveaux modèles créés sont nommés « authentication_code_autofill_button » et ils incluent la recommandation de sécurité et le délai d’expiration.

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"
        }
      ]
    }
  ]
}'

Exemple de réponse

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

Exemple d’application

Regardez notre exemple d’application WhatsApp avec mot de passe à usage unique (OTP) pour Android sur GitHub. Cet exemple d’application montre comment envoyer et recevoir des mots de passe à usage unique et des codes via l’API, comment intégrer les boutons de saisie automatique en un seul appui et de copie de code, comment créer un modèle et comment lancer un exemple de serveur.

Voir aussi

Compte business officiel : vous pouvez demander le statut de Compte business officiel afin d’instaurer un climat de confiance avec vos utilisateur·ices, ce qui réduira la probabilité qu’ils ou elles rejettent ou ignorent vos messages.
Webhooks pour les accusés de lecture : nous vous recommandons de vous abonner au champ webhooks de messages afin d’être informé·e lorsqu’un·e utilisateur·ice reçoit et lit votre modèle d’authentification avec un bouton de mot de passe à usage unique. Voir Webhooks pour l’API Cloud ou Webhooks pour l’API On-Premises.