Erstellen und Verwalten von Vorlagen

Vorlagen werden verwendet, wenn du Vorlagennachrichten über die von Meta gehostete Cloud API oder die On-Premises API sendest. Die Cloud API prüft Vorlagen und Variablenparameter anhand von maschinellem Lernen, um die Sicherheit und Integrität der Cloud API-Services zu gewährleisten. Beim Prüfen von Vorlagen und Variablentext durch die Cloud API werden keine Informationen mit WhatsApp geteilt.

Du kannst Vorlagen entweder mit der Business Management API oder über den WhatsApp Business Manager erstellen. Die Anzahl von Nachrichtenvorlagen, über die ein WhatsApp Business-Konto verfügen kann, wird von dessen Mutterunternehmen bestimmt. Wenn das Mutterunternehmen nicht verifiziert ist, ist jedes seiner WhatsApp Business-Konten auf 250 Vorlagen beschränkt. Wenn das Mutterunternehmen jedoch verifiziert ist und mindestens eines seiner WhatsApp Business-Konten über eine geschäftliche Telefonnummer mit genehmigtem Display-Namen verfügt, kann jedes seiner WhatsApp Business-Konten bis zu 6.000 Vorlagen haben.

Bevor du beginnst

Voraussetzungen:

• Ein Systembenutzer-Zugriffsschlüssel, der mit dem Unternehmen verknüpft ist
• Die Berechtigung whatsapp_business_management
• Die WhatsApp Business Account-ID für das Unternehmen
• Der Medien-Asset-Handle für jede Dokument-, Bild- oder Videodatei, die in der Medienvorlage verwendet werden soll. Um den Medien-Asset-Handle abzurufen, musst du das Medien-Asset über die Resumable Upload API hochladen.

Einschränkungen

• Das Namensfeld für Nachrichtenvorlagen ist auf 512 Zeichen beschränkt.
• Das Inhaltsfeld für Nachrichtenvorlagen ist auf 1.024 Zeichen beschränkt.
• Eine Vorlage kann nur bearbeitet werden, wenn sie den Status Genehmigt, Abgelehnt oder Pausiert hat. Eine Vorlage kann einmal am Tag bearbeitet werden und bis zu zehnmal im Monat.
• WhatsApp-Unternehmenskonten können nur 100 Nachrichtenvorlagen pro Stunde erstellen.
• Vorlagen, die aus vier oder mehr Buttons oder einem Schnellantwort-Button und einem oder mehreren Buttons anderer Art bestehen, können auf WhatsApp Desktop-Clients nicht angezeigt werden. WhatsApp-Benutzer, die eine dieser Vorlagennachrichten erhalten, werden aufgefordert, die Nachricht stattdessen auf einem Telefon anzuzeigen.

Lokalisierung

Du kannst beim Erstellen einer Vorlage eine Nachrichtenvorlage in einer bestimmten Sprache hinzufügen. Diese Vorlagen werden auf deine Mengenbeschränkung angerechnet. Achte bei der Bereitstellung von Übersetzungen auf Konsistenz. Weitere Informationen findest du im Hilfebereich im Artikel Warum sehe ich in meinem Rückruf die Fehler „Struktur nicht verfügbar“.

Erstellen von Vorlagen

Sende eine POST-Anfrage an den Endpunkt WhatsApp Business-Konto > Nachrichtenvorlagen, um eine Vorlage zu erstellen.

Anfragesyntax

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates

Anfrageinhalt

{
  "name": "<NAME>",
  "category": "<CATEGORY>",
  "allow_category_change": <ALLOW_CATEGORY_CHANGE>,
  "language": "<LANGUAGE>",
  "components": [<COMPONENTS>]
}

Texteigenschaften

Vorlagenkategorien

Vorlagen müssen anhand der folgenden Kategorien kategorisiert werden. Kategorien haben Auswirkungen auf die Preisgestaltung und die von dir ausgewählte Kategorie wird bei der Vorlagenerstellung geprüft.

• AUTHENTICATION
• MARKETING
• UTILITY

Im Dokument zur Vorlagenkategorisierung findest du Informationen, die dir bei der Wahl der richtigen Kategorie beim Erstellen von Vorlagen helfen.

Vorlagenkomponenten

Vorlagen bestehen basierend auf deinen Unternehmensanforderungen aus verschiedenen Text-, Medien- und interaktiven Komponenten. In der Dokumentation zu Vorlagenkomponenten findest du eine Liste aller möglichen Komponenten und ihrer Voraussetzungen sowie Beispiele und Beispielabfragen.

Definiere beim Erstellen einer Vorlage ihre Komponenten, indem du der „components“-Eigenschaft im Text der Anfrage einen Array von Komponentenobjekten zuweist.

Dies ist z. B. ein Array, das eine Text-Komponente mit zwei Variablen und Beispielwerten enthält sowie eine Telefonnummer-Button-Komponente und eine URL-Button-Komponente:

[
  {
    "type": "BODY",
    "text": "Thank you for your order, {{1}}! Your confirmation number is {{2}}. If you have any questions, please use the buttons below to contact support. Thank you for being a customer!",
    "example": {
      "body_text": [
        [
          "Pablo","860198-230332"
        ]
      ]
    }
  },
  {
    "type": "BUTTONS",
    "buttons": [
      {
        "type": "PHONE_NUMBER",
        "text": "Call",
        "phone_number": "15550051310"
      },
      {
        "type": "URL",
        "text": "Contact Support",
        "url": "https://www.luckyshrub.com/support"
      }
    ]
  }
]

In der Dokumentation zu Vorlagenkomponenten findest du eine Liste aller möglichen Komponenten und ihrer Voraussetzungen sowie Beispiele und Beispielabfragen.

Beachte, dass für Vorlagen mit der Kategorie AUTHENTICATION eigene Komponentenanforderungen gelten. Siehe Authentifizierungsvorlagen.

Kategorieprüfung

Wenn du eine Anfrage zur Vorlagenerstellung sendest, prüfen wir sofort die Kategorie anhand unserer Richtlinien zur Vorlagenkategorisierung.

• Wenn wir mit der von dir festgelegten Kategorie einverstanden sind, erstellen wir die Voralge und setzen ihren status auf PENDING. Anschließend wird die Vorlage einer Vorlagenüberprüfung unterzogen.
• Wenn wir mit der von dir festgelegten Kategorie nicht einverstanden sind, erstellen wir die Vorlage, setzen ihren status jedoch auf REJECTED und lösen einen Webhook zur Statusaktualisierung der Nachrichtenvorlage aus, bei dem für reason der Wert INCORRECT_CATEGORY festgelegt ist. Wir empfehlen dir, auf diesen Webhook zu warten, um abgelehnte Vorlagen zu identifizieren, oder das Feld rejected_reason bei neu erstellten Vorlagen anzufordern, das den Wert TAG_CONTENT_MISMATCH enthält.

In beiden Fällen wird der anfängliche Status der Vorlage als Teil der API-Antwort zurückgegeben.

Wenn dein Vorlagenstatus im Rahmen der Kategorieprüfung REJECTED lautet, hast du mehrere Möglichkeiten:

• Bearbeite die Komponenten der Vorlage so, dass sie unseren Richtlinien entsprechen.
• Bearbeite die Kategorie der Vorlage so, dass sie unseren Richtlinien entspricht.
• Erstelle eine neue Vorlage.

Automatische Kategorisierung

Du kannst die Eigenschaft allow_category_change in deine Anfrage aufnehmen, damit wir automatisch eine Kategorie anhand des Inhalts deiner Vorlage und unserer Richtlinien zur Vorlagenkategorisierung zuweisen. Dies kann verhindern, dass der Status deiner Vorlage aufgrund falscher Kategorisierung sofort auf REJECTED festgelegt wird.

Beachte, dass die automatische Kategorisierung nur beim Erstellen einer Vorlage möglich ist.

Vorlagenüberprüfung

Vorlagen mit dem Status PENDING werden einer Vorlagenüberprüfung unterzogen. Wir überprüfen den Inhalt aller neu erstellen oder bearbeiteten Vorlagen, um sicherzustellen, dass sie unseren Content-Richtlinien entsprechen. Basierend auf dem Ergebnis dieser Überprüfung ändern wir den Status automatisch in APPROVED oder REJECTED, was wiederum einen Webhook zur Statusaktualisierung der Nachrichtenvorlage auslöst.

Vorlagenstatus

Basierend auf dem Ergebnis der Kategorie- und Vorlagenüberprüfung ändern oder setzen wir den status deiner Vorlage auf einen der folgenden Werte:

• APPROVED – Die Vorlage hat die Vorlagenüberprüfung bestanden und wurde genehmigt. Sie kann jetzt in Vorlagennachrichten gesendet werden.
• PENDING – Die Vorlage hat die Kategorieüberprüfung bestanden und wird derzeit einer Vorlagenüberprüfung unterzogen.
• REJECTED – Die Vorlage hat die Kategorie- oder Vorlagenüberprüfung nicht bestanden. Du kannst das Feld „rejected_reason“ für die Vorlage anfordern, um den Grund zu erhalten.

Du findest alle möglichen Felder und Status in der Endpunktreferenz für WhatsApp-Nachrichtenvorlagen.

Antwort

Bei Erfolg gibt die API eine Antwort mit der ID, dem Status und der Kategorie der neu erstellen Vorlage zurück. Es gibt drei mögliche Ergebnisse:

• Wir waren mit der von dir festgelegten Kategorie einverstanden und die Vorlage wird derzeit einer Vorlagenüberprüfung unterzogen (status ist auf PENDING festgelegt).
• Wir waren mit der dir festgelegten Kategorie nicht einverstanden (status ist auf REJECTED festgelegt).
• Wir haben die Vorlage automatisch genehmigt (status ist auf APPROVED festgelegt). Dies ist nur bei Authentifizierungsvorlagen mit Einmalpasswort-Buttons möglich.

{
    "id": "<ID>",
    "status": "<STATUS>",
    "category": "<CATEGORY>"
}

Antworteigenschaften

Beispielanfrage

Dies ist eine Beispielanfrage für das Erstellen einer Vorlage für ein saisonales Angebot, die aus folgenden Komponenten besteht:

• einem Text-Header
• einem Haupttext
• einem Footer
• zwei Schnellantwort-Buttons

Weitere Beispiele findest du unter Beispielanfragen.

curl 'https://graph.facebook.com/v19.0/102290129340398/message_templates' \
-H 'Authorization: Bearer EAAJB...' \
-H 'Content-Type: application/json' \
-d '
{
  "name": "seasonal_promotion",
  "language": "en_US",
  "category": "MARKETING",
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Our {{1}} is on!",
      "example": {
        "header_text": [
          "Summer Sale"
        ]
      }
    },
    {
      "type": "BODY",
      "text": "Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.",
      "example": {
        "body_text": [
          [
            "the end of August","25OFF","25%"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "Use the buttons below to manage your marketing subscriptions"
    },
    {
      "type":"BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Unsubscribe from Promos"
        },
        {
          "type":"QUICK_REPLY",
          "text": "Unsubscribe from All"
        }
      ]
    }
  ]
}'

Beispielantwort

{
    "id": "572279198452421",
    "status": "PENDING",
    "category": "MARKETING"
}

Senden von Vorlagen

Nutze die Cloud API oder die On-Premises API, um eine Vorlage in einer Vorlagennachricht zu senden.

Best Practices für Marketing-Vorlagen

„Abmelden“-Button für Marketing-Nachrichten

Wir empfehlen dir, einen Schnellantwort-Button zu deinen Vorlagen hinzuzufügen, die als MARKETING kategorisiert wurden. So können Kund*innen sich einfacher vom Erhalt deiner Marketing-Nachrichten abmelden. Auf diese Weise können Nutzer*innen dem Erhalt deiner Marketing-Nachrichten widersprechen, ohne dein Geschäft zu blockieren. Möglicherweise kannst du dann das Nachrichtenvolumen schneller skalieren. In diesem Artikel findest du weitere Details zu den Vorteilen des „Abmelden“-Buttons für deine Marketing-Vorlagen.

Abrufen von Vorlagen

Sende eine GET-Anfrage an den Endpunkt WhatsApp Business-Konto > Nachrichtenvorlagen, um eine Liste der Vorlagen eines WhatsApp Business-Kontos abzurufen.

Anfragesyntax

GET /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates
  ?fields=<FIELDS>
  &limit=<LIMIT>

Abfrage-String-Parameter

Beispielanfrage

curl 'https://graph.facebook.com/v19.0/102290129340398/message_templates?fields=name,status&limit=3' \
-H 'Authorization: Bearer EAAJB...'

Beispielantwort

{
  "data": [
    {
      "name": "seasonal_promotion_text_only",
      "status": "APPROVED",
      "id": "564750795574598"
    },
    {
      "name": "seasonal_promotion_video",
      "status": "PENDING",
      "id": "1252715608684590"
    },
    {
      "name": "seasonal_promotion_image_header",
      "status": "PENDING",
      "id": "1372429296936443"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MgZDZD"
    },
    "next": "https://graph.facebook.com/v19.0/102290129340398/message_templates?fields=name%2Cstatus&limit=3&after=MgZDZD"
  }
}

Beispielanfrage (abgelehnte Vorlagen)

Du kannst nur Vorlagen mit bestimmten Feldwerten zurückgeben, indem du das Feld und den gewünschten Wert in deiner Anfrage angibst. Gib beispielsweise status=REJECTED an, um nur abgelehnte Vorlagen abzurufen.

curl 'https://graph.facebook.com/v19.0/104996122399160/message_templates?fields=name,status&status=REJECTED' \
-H 'Authorization: Bearer EAAJB...'

Beispielantwort

{
  "data": [
    {
      "name": "seasonal_promotion_text_only_v4",
      "status": "REJECTED",
      "id": "564750795574598"
    },
    {
      "name": "discount_qualifier",
      "status": "REJECTED",
      "id": "163917509772674"
    },
    {
      "name": "limited_time_offer_tuscan_getaway_2023",
      "status": "REJECTED",
      "id": "202389039167147"
    },
    {
      "name": "2023_mar_promo_2",
      "status": "REJECTED",
      "id": "1116034925734553"
    },
    {
      "name": "2023_mar_promo",
      "status": "REJECTED",
      "id": "952600926095321"
    }
  ]
}

Vorlagen-Namespace abrufen

Der Namespace der Nachrichtenvorlage ist erforderlich, um Nachrichten unter Verwendung der Nachrichtenvorlagen zu senden.

Um den Namespace für eine Vorlage abzurufen, sendest du eine GET-Anfrage an den /{whatsapp-business-account-ID}-Endpunkt und schließt das message_template_namespace-Feld ein.

Beispielanfrage

curl -i -X GET "https://graph.facebook.com/v19.0/{whatsapp-business-account-ID}
  ?fields=message_template_namespace
  &access_token={system-user-access-token}"

Bei einer erfolgreichen Anfrage wird ein JSON-Objekt mit der WhatsApp Business-Konto-ID und dem Namespace zurückgegeben:

{
    "id": "1972385232742141",
    "message_template_namespace": "12abcdefghijk_34lmnop" 
}

Bearbeiten von Vorlagen

Sende eine POST-Anfrage an den Endpunkt WhatsApp-Nachrichtenvorlage, um eine Vorlage zu bearbeiten. Über den Bereich WhatsApp Manager > Konto-Tools > Nachrichtenvorlagen kannst du Vorlagen auch manuell bearbeiten.

Einschränkungen

• Nur Vorlagen mit dem Status APPROVED, REJECTED oder PAUSED können bearbeitet werden.
• Nur die Werte für category oder components einer Vorlage können bearbeitet werden.
• Den category-Wert einer genehmigten Vorlage kannst du nicht bearbeiten.
• Genehmigte Vorlagen können in einem Zeitraum von 30 Tagen bis zu zehnmal geändert werden oder einmal innerhalb von 24 Stunden. Abgelehnte oder pausierte Vorlagen können beliebig oft bearbeitet werden.
• Nachdem du eine genehmigte oder pausierte Vorlage bearbeitet hast, wird diese automatisch genehmigt, sofern sie die Vorlagenüberprüfung besteht.

Anfragesyntax

POST /<WHATSAPP_MESSAGE_TEMPLATE_ID>

Anfrageinhalt

{
  "category": "<CATEGORY>",
  "components": [<COMPONENTS>]
}

Eigenschaften

Beispielanfrage (Komponenten bearbeiten)

Beispielanfrage zum Ändern des Haupttexts einer Vorlage, der sowohl Marketing- als auch Utility-Inhalt enthielt, damit er nur noch Marketing-Content enthält.

curl 'https://graph.facebook.com/v19.0/564750795574598' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Our {{1}} is on!",
      "example": {
        "header_text": [
          "Spring Sale"
        ]
      }
    },
    {
      "type": "BODY",
      "text": "Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.",
      "example": {
        "body_text": [
          [
            "the end of April",
            "25OFF",
            "25%"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "Use the buttons below to manage your marketing subscriptions"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Unsubcribe from Promos"
        },
        {
          "type": "QUICK_REPLY",
          "text": "Unsubscribe from All"
        }
      ]
    }
  ]
}'

Beispielanfrage (nur Kategorie bearbeiten)

Beispielanfrage zum Ändern der Kategorie einer Vorlage von UTILITY in MARKETING.

curl 'https://graph.facebook.com/v19.0/1252715608684590' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "category": "MARKETING"
}'

Beispielantwort

Beispielantwort bei Erfolg.

{
  "success": true
}

Löschen von Vorlagen

Verwende den WhatsApp Business-Konto > Nachrichtenvorlagen-Endpunkt, um eine Vorlage anhand des Namens oder der ID zu löschen.

Hinweise

• Wenn du eine Vorlage löschst, die in einer Vorlagennachricht gesendet wurde, aber noch nicht zugestellt wurde (z. B. weil das Telefon des*der Kund*in ausgeschaltet ist), wird der Status der Vorlage auf PENDING_DELETION festgelegt und wir versuchen 30 Tage lang, die Nachricht zuzustellen. Nach Ablauf dieser Zeit erhältst du die Fehlermeldung „Struktur nicht verfügbar“ und der*die Kund*in empfängt die Nachricht nicht.
• Der Name einer genehmigten Vorlage, die gelöscht wurde, kann erst nach 30 Tagen wiederverwendet werden.

Löschen anhand des Namens

Wenn du eine Vorlage anhand des Namens löschst, werden alle Vorlagen mit dem entsprechenden Namen gelöscht (d. h. Vorlagen mit demselben Namen doch mit unterschiedlichen Sprachen werden ebenfalls gelöscht).

Anfragesyntax

DELETE /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates
  ?name=<NAME>

Beispielanfrage

curl -X DELETE 'https://graph.facebook.com/v16.0/102290129340398/message_templates?name=order_confirmation' \
-H 'Authorization: Bearer EAAJB...'

Beispielantwort

{
  "success": true
}

Löschen anhand der ID

Um eine Vorlage anhand der ID zu löschen, beziehe die ID der Vorlage zusammen mit ihrem Namen in deine Anfrage ein. Es wird nur die Vorlage mit der entsprechenden Vorlagen-ID gelöscht.

Anfragesyntax

DELETE /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates
  ?hsm_id=<HSM_ID>,
  &name=<NAME>

Beispielanfrage

curl -X DELETE 'https://graph.facebook.com/v19.0/102290129340398/message_templates?hsm_id=1407680676729941&name=order_confirmation' \
-H 'Authorization: Bearer EAAJB...'

Beispielantwort

{
  "success": true
}

Mehr dazu

Nächste Schritte

• Nächste Schritte für das Senden von Nachrichten mit der Cloud API