Authentifizierungsvorlagen

Wenn deine mobile App Nutzer*innen die Möglichkeit bietet, Einmalpasswörter oder Verifizierungscodes per WhatsApp zu empfangen, musst du deine Authentifizierungsvorlage hinzufügen.

Authentifizierungsvorlagen bestehen aus Folgendem:

• Fester vordefinierter Text: <VERIFICATION_CODE> ist dein Verifizierungscode.
• Einem optionalen Sicherheits-Disclaimer: Zu deiner eigenen Sicherheit teile diesen Code nicht.
• Einem optionalen Ablaufhinweis: Dieser Code läuft in <NUM_MINUTES> Minuten ab.
• Entweder einem „Durch Tippen automatisch ausfüllen“-Button, einem „Code kopieren“-Button oder gar keinem Button, wenn sie Authentifizierung ohne Eingabe verwenden.

Da „Durch Tippen automatisch ausfüllen“-Buttons die beste Nutzungserfahrung bieten, sind sie die bevorzugte Lösung. Jedoch werden „Durch Tippen automatisch ausfüllen“-Buttons derzeit nur in Android unterstützt und erfordern zusätzliche Änderungen am Code deiner App.

Weitere Informationen dazu, wann die Verwendung einer Authentifizierungsvorlage angemessen ist, findest du in den zusätzlichen Richtlinien.

„Durch Tippen automatisch ausfüllen“-Authentifizierungsvorlagen

Authentifizierungsvorlagen enthalten einen „Durch Tippen automatisch ausfüllen“-Button.

Wenn ein*e WhatsApp-Benutzer*in auf den Button zum automatischen Ausfüllen tippt, löst der WhatsApp-Client eine Aktivität aus, die deine App öffnet und ihr das Passwort oder den Code bereitstellt.

Unter „Durch Tippen automatisch ausfüllen“-Authentifizierungsvorlagen findest du weitere Informationen zu deren Verwendung.

„Code kopieren“-Authentifizierungsvorlagen

Mit „Code kopieren“-Authentifizierungsvorlagen kannst du ein Einmalpasswort oder einen Einmalcode zusammen mit einem „Code kopieren“-Button an deine Nutzer*innen senden.

Wenn ein*e WhatsApp-Benutzer*in auf den „Code kopieren“-Button tippt, kopiert der WhatsApp-Client das Passwort oder den Code in die Zwischenablage des Geräts. Der*die Benutzer*in kann dann zu deiner App wechseln und das Passwort oder den Code in die Benutzer*innenoberfläche deiner App einfügen.

Unter „Code kopieren“-Authentifizierungsvorlagen findest du weitere Informationen zu deren Verwendung.

Vorlagen für die Authentifizierung ohne Eingabe

Mit Vorlagen für die Authentifizierung ohne Eingabe können Nutzer*innen Einmalpasswörter oder Einmalcodes über WhatsApp empfangen, ohne dass sie deine App verlassen müssen.

Wenn ein*e Nutzer*i ein Passwort oder einen Code in deiner App anfordert und du es/ihn über eine Vorlage für die Authentifizierung ohne Eingabe bereitstellst, überträgt der WhatsApp-Client das enthaltene Passwort oder den Code, das/den deine App dann mit einem Broadcast-Empfänger abrufen kann.

Unter Vorlagen für die Authentifizierung ohne Eingabe findest du weitere Informationen zu deren Verwendung.

Best Practices

• Bestätige die WhatsApp-Telefonnummer des*der Benutzer*in, bevor du das Einmalpasswort oder den Code an diese Nummer sendest.
• Mache deinen Benutzer*innen deutlich, dass das Passwort oder der Code an ihre WhatsApp-Telefonnummer gesendet wird, insbesondere, wenn du mehrere Möglichkeiten anbietest, wie Benutzer*innen Passwörter oder Codes empfangen können. Weitere Tipps findest du unter Zustimmung einholen.
• Wenn Benutzer*innen das Passwort oder den Code in deine App einfügen oder deine App dieses/diesen über den „Durch Tippen automatisch ausfüllen“-Button erhält, lasse sie eindeutig wissen, dass deine App den Code erfasst hat.

Siehe auch Best Practices für die Authentifizierung von Benutzer*innen via WhatsApp.

Time-To-Live

Wenn wir nicht in der Lage sind, einem*einer WhatsApp-Benutzer*in eine Nachricht zuzustellen, versuchen wir weiterhin die Nachricht für einen Zeitraum zuzustellen, der auch Time-To-Live genannt wird.

Standardmäßig haben Nachrichten eine Gültigkeitsdauer von 30 Tagen. Neu erstellte Authentifizierungsvorlagen haben jedoch eine standardmäßige Gültigkeitsdauer von 10 Minuten.

Wenn wir eine Authentifizierungsvorlage für einen Zeitraum, der die Time-To-Live überschreitet, nicht zustellen können, beenden wir die wiederholten Zustellungsversuche und die Nachricht wird verworfen. Wenn die Zeit zwischen der Sendeanforderung deiner Authentifizierungsvorlagen-Nachricht die Time-To-Live überschreitet und du keinen Webhook erhältst, kannst du daraus ableiten, dass die Nachricht verworfen wurde.

Um die standardmäßige Time-To-Live beim Erstellen einer Authentifizierungsvorlage zu überschreiben, füge die message_send_ttl_seconds-Eigenschaft mit einem Wert zwischen 60 und 600 Sekunden hinzu.

Bestehende Vorlagen, die vor der Bereitstellung dieser Funktionalität erstellt wurden, haben eine Time-To-Live von 30 Tagen. Falls gewünscht, kannst du eine vorhandene Vorlage bearbeiten und die entsprechende Time-To-Live überschreiben, indem du die message_send_ttl_seconds-Eigenschaft festlegst.

Du kannst die message_send_ttl_seconds-Eigenschaft einer Authentifizierungsvorlage auch auf -1 festlegen. Somit wird die Time-To-Live auf oder 30 Tage festgelegt.

Wir empfehlen dir, für alle deine Authentifizierungsvorlagen eine Time-To-Live festzulegen, die vorzugsweise gleich oder kürzer als die Ablaufzeit deines Codes ist, um zu gewährleisten, dass deine Kund*innen nur dann eine Nachricht erhalten, wenn ein Code noch nutzbar ist.

Beachte dabei, dass es zu einer geringfügigen Verzögerung bei der Zustellung des fehlgeschlagenen Nachrichten-Webhooks kommen kann und du daher möglicherweise einen kleinen Zeitpuffer einplanen solltest, bevor du ableitest, dass eine Nachricht verworfen wurde.

Authentifizierungsvorlagen-Nachrichten senden

Verwende die Cloud API oder On-Premises API, um genehmigte Authentifizierungsvorlagen in einer Vorlagennachricht zu senden.

• Authentifizierungsvorlagen-Nachrichten mit der Cloud API senden
• Authentifizierungsvorlagen-Nachrichten mit der On-Premises API senden

Vorlagenvorschauen

Über den Endpunkt WhatsApp-Unternehmenskonto > Nachrichtenvorlagenvorschauen kannst du Vorschauen des Authentifizierungsvorlagentextes in verschiedenen Sprachen generieren, die die Sicherheitsempfehlungs-Zeichenfolge und die Code-Ablaufzeichenfolge enthalten oder ausschließen.

Anfragesyntax

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

Abfrage-String-Parameter

Beispielanfrage

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

Beispielantwort

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

Massenverwaltung

Verwende den Endpunkt WhatsApp-Unternehmenskonto > Upsert Message Templates, um Authentifizierungsvorlagen, die die optionalen Sicherheits- und Ablaufwarnungen enthalten oder ausschließen, in mehreren Sprachen massenweise zu aktualisieren oder zu erstellen.

Wenn bereits eine Vorlage mit dem entsprechenden Namen und der entsprechenden Sprache existiert, wird die Vorlage mit dem Inhalt der Anfrage aktualisiert, andernfalls wird eine neue Vorlage erstellt.

Anfragesyntax

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/upsert_message_templates

Anfrageinhalt

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

Eigenschaften

Alle Vorlagenerstellungseigenschaften mit Ausnahme folgender werden unterstützt:

• Die Eigenschaft language wird nicht unterstützt. Verwende stattdessen languages und lege den Wert auf einen Bereich von Zeichenfolgen für Sprach- und Gebietsschemacodes fest. Beispiel: ["en_US","es_ES","fr"].
• Die Eigenschaft language wird nicht unterstützt.
• Die Eigenschaft language wird nicht unterstützt.

Beispielanfrage (Code kopieren)

In diesem Beispiel werden drei Authentifizierungsvorlagen in Englisch, Spanisch und Französisch mit Code-kopieren-Buttons erstellt. Jede Vorlage wird „authentication_code_copy_code_button“ genannt und enthält die Sicherheitsempfehlung und den Ablaufzeitpunkt.

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

Beispielanfrage (durch Tippen automatisch ausfüllen)

Mit diesem Beispiel (1) wird eine vorhandene Vorlage mit dem Namen „authentication_code_autofill_button“ und der Sprache „en_US“ aktualisiert und (2) es werden zwei neue Authentifizierungsvorlagen in Spanisch und Französisch mit „Durch Tippen automatisch ausfüllen“-Buttons erstellt. Beide neu erstellte Vorlage werden „authentication_code_autofill_button“ genannt und enthalten die Sicherheitsempfehlung und den Ablaufzeitpunkt.

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

Beispielantwort

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

Beispiel-App

Siehe unsere Beispiel-App für WhatsApp-Einmalpasswort (OTP) für Android in Github. Die Beispiel-App zeigt, wie du Einmalpasswörter und Codes über die API sendest und empfängst, wie du die Buttons „Durch Klicken automatisch ausfüllen“ und „Code kopieren“ integrierst, wie du eine Vorlage erstellst und wie du einen Beispielserver erstellst.

Siehe auch

• Offizielles Unternehmenskonto – Du kannst den Status „offizielles Unternehmenskonto“ anfordern, um das Vertrauen deiner Benutzer*innen zu stärken. So senkst du die Wahrscheinlichkeit, dass sie deine Nachrichten schließen oder ignorieren.
• Webhooks für Lesebestätigungen – Wir empfehlen dir, das Feld „Nachrichten-Webhooks“ zu abonnieren, damit du Benachrichtigungen erhältst, wenn ein*e Benutzer*in deine Authentifizierungsvorlagen-Nachricht ohne OTP-Button empfängt und liest. Siehe Webhooks für die Cloud API oder Webhooks für die On-Premises API.