Vorlagennachrichten

WhatsApp-Nachrichtenvorlagen sind spezielle Nachrichtenformate, mit denen Unternehmen Benachrichtigungen oder Kund*innenservice-Nachrichten versenden können, sofern die Empfänger*innen dem zugestimmt haben. Das können zum Beispiel Erinnerungen an Termine, Versandinformationen, Problemlösungen oder aktualisierte Zahlungsdaten sein.

Bevor du eine Vorlagennachricht senden kannst, musst du eine Vorlage erstellen. Weitere Informationen findest du unter Nachrichtenvorlagen für dein WhatsApp Business-Konto erstellen. Wenn dein Konto noch nicht verifiziert ist, kannst du eine unserer vorab genehmigten Vorlagen verwenden.

Aktuell kannst du die folgenden Vorlagenarten senden:

• Textbasierte Nachrichtenvorlagen
• Medienbasierte Nachrichtenvorlagen
• Interaktive Nachrichtenvorlagen
• Standortbasierte Nachrichtenvorlagen
• Authentifizierungsvorlagen mit Einmalpasswort-Buttons
• Vorlagen für Nachrichten mit mehreren Produkten

Alle in diesem Leitfaden erwähnten API-Aufrufe müssen mit einem Zugriffsschlüssel authentifiziert werden. Entwickler*innen können ihre API-Aufrufe mit Zugriffsschlüsseln authentifizieren, die im App-Dashboard über WhatsApp > API-Einrichtung generiert wurden. Lösungspartner müssen sich mit einem Zugriffsschlüssel mit der Berechtigung whatsapp_business_messaging authentifizieren.

Pacing

Neu erstellte oder nicht pausierte Marketingvorlagen unterliegen dem Vorlagen-Pacing. Siehe Vorlagen-Pacing.

Textbasierte Nachrichtenvorlagen

Wenn du eine textbasierte Nachrichtenvorlage senden möchtest, starte einen POST-Aufruf an /PHONE_NUMBER_ID/messages und hänge ein Nachrichtenobjekt mit type=template an. Füge anschließend ein template-Objekt hinzu.

Beispielanfrage:

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "template",
  "template": {
    "name": "TEMPLATE_NAME",
    "language": {
      "code": "LANGUAGE_AND_LOCALE_CODE"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "text-string"
          },
          {
            "type": "currency",
            "currency": {
              "fallback_value": "VALUE",
              "code": "USD",
              "amount_1000": NUMBER
            }
          },
          {
            "type": "date_time",
            "date_time": {
              "fallback_value": "DATE"
            }
          }
        ]
      }
    ]
  }
}'

{
  "messaging_product": "whatsapp",
  "contacts": [{
      "input": "PHONE_NUMBER",
      "wa_id": "WHATSAPP_ID",
    }]
  "messages": [{
      "id": "wamid.ID",
    }]
}

Medienbasierte Nachrichtenvorlagen

Wenn du eine medienbasierte Nachrichtenvorlage senden möchtest, starte einen POST-Aufruf an /PHONE_NUMBER_ID/messages und hänge ein Nachrichtenobjekt mit type=template an. Füge anschließend ein template-Objekt hinzu. Unterstützt Medien-HTTP-Caching.

Verwende den POST-Endpunkt WhatsApp-Unternehmenstelefonnummer > Nachrichten, um eine medienbasierte Vorlagennachricht zu senden. Lege die type-Eigenschaft auf template fest und verwende die template-Eigenschaft, um dein Vorlagenobjekt und sein Medienobjekt zu definieren.

Wenn du dein Medienobjekt definierst, kannst du entweder dein Medien-Asset auf unsere Server hochladen und dessen Medien ID verwenden (indem du die id-Eigenschaft nutzt) oder das Asset auf deinem Server hosten und dessen URL verwenden (indem du die link-Eigenschaft nutzt). Wenn du link verwendest, muss sich dein Asset auf einem öffentlich zugänglichen Server befinden, sonst kann die Nachricht nicht gesendet werden.

Um das Fehlerrisiko zu verringern und unnötige Anfragen an deinen öffentlichen Server zu vermeiden, empfehlen wir dir, deine Medien-Assets hochzuladen und ihre IDs beim Senden von Nachrichten zu verwenden.

Medien-Assets können auch zwischengespeichert werden. Siehe Medien-HTTP-Caching.

Beispielanfrage:

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "template",
  "template": {
    "name": "TEMPLATE_NAME",
    "language": {
      "code": "LANGUAGE_AND_LOCALE_CODE"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": {
              "link": "https://URL"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "TEXT-STRING"
          },
          {
            "type": "currency",
            "currency": {
              "fallback_value": "VALUE",
              "code": "USD",
              "amount_1000": NUMBER
            }
          },
          {
            "type": "date_time",
            "date_time": {
              "fallback_value": "MONTH DAY, YEAR"
            }
          }
        ]
      }
    ]
  }
}'

{
  "messaging_product": "whatsapp",
  "contacts": [{
      "input": "PHONE_NUMBER",
      "wa_id": "WHATSAPP_ID",
    }]
  "messages": [{
      "id": "wamid.ID",
    }]
}

Interaktive Nachrichtenvorlagen

Mit interaktiven Nachrichtenvorlagen kannst du mehr Inhalte an Empfänger senden, die über die Inhalte von Standard- und Medien-Nachrichtenvorlagen hinausgehen, nämlich interaktive Buttons. Hierzu verwendest du das Objekt „components“. Es gibt zwei Arten von vordefinierten Buttons:

• Call-to-Action: Damit können deine Kund*innen eine Telefonnummer anrufen und eine Website besuchen.
• Schnellantwort: Damit können deine Kund*innen eine einfache Textnachricht zurückgeben.

Diese Buttons können an Textnachrichten oder Mediennachrichten angehängt werden. Sobald deine interaktiven Nachrichtenvorlagen erstellt und genehmigt wurden, kannst du sie in Benachrichtigungsnachrichten sowie in Kund*innenservice-Nachrichten verwenden.

Wenn du eine interaktive Nachrichtenvorlage senden möchtest, starte einen POST-Aufruf an /PHONE_NUMBER_ID/messages und hänge ein Nachrichtenobjekt mit type=template an. Füge anschließend ein template-Objekt mit dem von dir ausgewählten button hinzu.

Beispielanfrage:

curl -X  POST \
 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "template",
  "template": {
    "name": "TEMPLATE_NAME",
    "language": {
      "code": "LANGUAGE_AND_LOCALE_CODE"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": {
              "link": "http(s)://URL"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "TEXT_STRING"
          },
          {
            "type": "currency",
            "currency": {
              "fallback_value": "VALUE",
              "code": "USD",
              "amount_1000": NUMBER
            }
          },
          {
            "type": "date_time",
            "date_time": {
              "fallback_value": "MONTH DAY, YEAR"
            }
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "quick_reply",
        "index": "0",
        "parameters": [
          {
            "type": "payload",
            "payload": "PAYLOAD"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "quick_reply",
        "index": "1",
        "parameters": [
          {
            "type": "payload",
            "payload": "PAYLOAD"
          }
        ]
      }
    ]
  }
}'

{
  "messaging_product": "whatsapp",
  "contacts": [{
      "input": "PHONE_NUMBER",
      "wa_id": "WHATSAPP_ID",
    }]
  "messages": [{
      "id": "wamid.ID",
    }]
}

Standortbasierte Nachrichtenvorlagen

Um eine Vorlage zu senden, die einen Standort-Header verwendet, muss deine Anfrage ein Standort-Header-Objekt enthalten.

Syntax

{
  "type": "header",
  "parameters": [
    {
      "type": "location",
      "location": {
        "latitude": "<LATITUDE>",
        "longitude": "<LONGITUDE>",
        "name": "<NAME>",
        "address": "<ADDRESS>"
      }
    }
  ]
}

Eigenschaften

Beispielanfrage

Dies ist eine Beispielanfrage zum Senden einer vorhandenen Vorlage, die die folgenden Komponenten verwendet:

• einen Standort-Header
• einen Text-Body mit einer Variablen
• einen Footer
• einen Schnellantwort-Button

curl -L 'https://graph.facebook.com/v16.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "12245554792",
  "type": "template",
  "template": {
    "name": "order_delivery_update",
    "language": {
      "code": "en_US"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "location",
            "location": {
              "latitude": "37.483307",
              "longitude": "122.148981",
              "name": "Pablo Morales",
              "address": "1 Hacker Way, Menlo Park, CA 94025"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Pablo"
          },
          {
            "type": "text",
            "text": "566701"
          }
        ]
      }
    ]
  }
}'

Authentifizierungsvorlagen

Wenn du versuchst, alte Authentifizierungsvorlagen (Vorlagen ohne Einmalpasswort-Buttons) zu senden, deren Variablenwerte mehr als 15 Zeichen umfassen oder Links oder Emojis enthalten oder die Textkörperkomponente der Vorlage einen Link enthält, wird der Fehlercode 100 zurückgegeben. Erstelle und verwende stattdessen eine Authentifizierungsvorlage mit einem Einmalpasswort-Button.

Siehe Authentifizierungsvorlagen und Senden von Authentifizierungsvorlagen.

Zustellungsreihenfolge bei mehreren Nachrichten

Wenn du mehrere Nachrichten sendest, kann nicht garantiert werden, dass die Reihenfolge, in der Nachrichten zugestellt werden, mit der Reihenfolge deiner API-Anfragen übereinstimmt. Wenn deine Nachrichten in einer bestimmten Reihenfolge zugestellt werden müssen, stelle sicher, dass du die Statusmeldung delivered in einer Webhook-Nachricht erhalten hast, bevor du die nächste Nachricht in deiner Nachrichtensequenz sendest.

Nachrichtenbeschränkungen für Marketingvorlagen pro Benutzer*in

Wir führen neue Ansätze ein, beginnend mit Verbraucher*innen in Indien, die hochwertige Benutzungserlebnisse schaffen und das Engagement von Marketingvorlagennachrichten maximieren. Dazu gehört unter anderem, die Anzahl der Marketingvorlagennachrichten, die eine Person in einem bestimmten Zeitraum von einem Unternehmen erhält, zu begrenzen, beginnend mit einer kleinen Anzahl von Unterhaltungen, die weniger wahrscheinlich gelesen werden. Beachte, dass die Beschränkung auf der Grundlage der Anzahl der Marketingvorlagennachrichten bestimmt wird, die die Person bereits von einem Unternehmen erhalten hat, und sich nicht speziell auf dein Unternehmen bezieht.

Die Beschränkung gilt nur für Marketing-Vorlagennachrichten, die normalerweise eine neue Marketing-Unterhaltung eröffnen würden. Wenn bereits eine Marketing-Unterhaltung zwischen dir und einem*einer WhatsApp-Benutzer*in geöffnet ist, sind die an den*die Benutzer*in gesendeten Marketingvorlagennachrichten nicht betroffen.

Wenn eine Marketingvorlagennachricht aufgrund der Beschränkung nicht an eine*n bestimmte*n Benutzer*in übermittelt wird, gibt die Cloud API den Fehlercode 131026 und die On-Premises API den Fehlercode 1026 zurück. Beachte jedoch, dass diese Fehlercodes ein breites Spektrum an Problemen abdecken, die dazu führen können, dass eine Nachricht nicht zugestellt wird. Aus Datenschutzgründen geben wir nicht bekannt, ob die Nachricht aufgrund der Beschränkung nicht zugestellt wurde. Weitere Informationen findest du im Fehlerbehebungsdokument der Cloud-API und im Dokument „Warum beträgt meine Auslieferungsrate nicht 100 %?“ In den FAQ findest du Beschreibungen der Gründe für die Nichtzustellung und was du tun kannst, um die zugrunde liegende Ursache zu ermitteln.

Wenn du einen dieser Fehlercodes erhältst und vermutest, dass er auf die Beschränkung zurückzuführen ist, vermeide es, die Vorlagennachricht sofort erneut zu senden, da dies nur zu einer weiteren Fehlerantwort führt. Versuche es stattdessen in immer größeren Zeitschritten erneut, bis die Nachricht zugestellt wird, da die Beschränkung für unterschiedliche Zeiträume gelten kann.

Wir werden unseren Ansatz weiter verfeinern und schätzen deine Partnerschaft, während wir in die bestmögliche Erfahrung von WhatsApp für dein Unternehmen und deine Kund*innen investieren.

Problembehebung

Wenn du Probleme mit der Zustellung von Nachrichten hast, findest du unter Nachricht nicht zugestellt weitere Informationen.