Senden von Nachrichten

Dieses Dokument beschreibt, wie die API verwendet werden kann, um Nachrichten an WhatsApp-Benutzer*innen zu senden.

Arten von Nachrichten

Du kannst die API verwenden, um folgende Arten von Nachrichten zu senden. Alle diese Nachrichten, außer Reaktionsnachrichten, können als Antwort auf eine vorherige Nachricht gesendet werden.

Mit Adressnachrichten kannst du ganz einfach eine Lieferadresse von WhatsApp-Benutzer*innen anfordern.
Audionachrichten zeigen ein Audiosymbol und einen Link zu einer Audiodatei an. Wenn WhatsApp-Benutzer*innen auf das Symbol tippen, wird der WhatsApp-Client geladen, um die Audiodatei abzuspielen.
Mit Kontaktnachrichten kannst du umfassende Kontaktinformationen direkt an WhatsApp-Benutzer*innen senden, z. B. Namen, Telefonnummern, physische Adressen und E-Mail-Adressen.
Dokumentnachrichten zeigen ein Dokumentsymbol an, das mit einem Dokument verknüpft ist. Darauf können WhatsApp-Benutzer*innen tippen, um das Dokument herunterzuladen.
Bildnachrichten zeigen ein einzelnes Bild mit einer optionalen Bildunterschrift an.
Mit interaktiven CTA-URL-Button-Nachrichten kannst du einem Button eine beliebige URL zuordnen, sodass du keine langen oder kryptischen Roh-URLs in den Nachrichtentext einfügen musst.
Mit interaktiven Flow-Nachrichten kannst du strukturierte Nachrichten senden, die für deine Kund*innen natürlicher oder leichter zu lesen sind. Du kannst beispielsweise WhatsApp Flows verwenden, um Termine zu buchen, Produkte zu durchsuchen, Kund*innenfeedback zu sammeln, neue Leads zu erhalten und vieles mehr.
Mit interaktiven Listennachrichten kannst du WhatsApp-Benutzer*innen eine Liste mit auswählbaren Optionen zur Verfügung stellen.
Interaktive Standortabfragenachrichten enthalten einen Nachrichtentext und einen Button zum Senden des Standorts. Wenn ein*e WhatsApp-Benutzer*in auf den Button tippt, wird ein Bildschirm zum Teilen des Standorts angezeigt, über den Benutzer*innen ihren Standort teilen können.
Interaktive Nachrichten mit Antwort-Buttons ermöglichen es dir, bis zu drei vordefinierte Antworten zu senden, aus denen Benutzer*innen wählen können.
Mit Standortnachrichten kannst du Koordinaten mit dem Längen- und Breitengrad eines Standorts an WhatsApp-Benutzer*innen senden.
Stickernachrichten zeigen animierte oder statische Stickerbilder in einer WhatsApp-Nachricht an.
Textnachrichten sind Nachrichten, die nur Textinhalt und eine optionale Linkvorschau enthalten.
Mit Vorlagennachrichten kannst du Marketing-, Verwaltungs- und Authentifizierungsvorlagen an WhatsApp-Benutzer*innen senden. Im Gegensatz zu allen anderen Nachrichtentypen ist es bei Vorlagennachrichten nicht erforderlich, dass zwischen dir und dem*der Nachrichtenempfänger*in ein 24-Stunden-Kund*innenservice-Zeitfenster besteht, bevor die Nachricht gesendet werden kann.
Videonachrichten zeigen eine Thumbnail-Vorschau eines Videobildes mit einer optionalen Bildunterschrift an. Wenn WhatsApp-Benutzer*innen auf die Vorschau tippen, wird das Video geladen und angezeigt.
Reaktionsnachrichten sind Emoji-Reaktionen, die du auf eine WhatsApp-Nachricht anwenden kannst, die du zuvor erhalten hast.

Kund*innenservice-Fenster

Wenn dir ein*e WhatsApp-Benutzer*in eine Nachricht sendet, wird ein 24-stündiger Timer, der als Kund*innenservice-Fenster bezeichnet wird, gestartet (oder aktualisiert).

Alle Nachrichtentypen, mit Ausnahme von Vorlagennachrichten, können nur dann an eine*n WhatsApp-Benutzer*in gesendet werden, wenn zwischen dir und dem*der Benutzer*in ein offenes Kund*innenservice-Fenster besteht.

Vorlagennachrichten können jederzeit an Benutzer*innen gesendet werden, sofern diese dem Empfang von Nachrichten von dir zugestimmt haben.

Anfragen

Alle Anfragen zum Senden von Nachrichten verwenden den Endpunkt POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID/messages:

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/messages

Der Inhalt der Post-Anfrage variiert je nach Art der Nachricht, die du senden möchtest, aber die Payload folgt der folgenden allgemeinen Syntax:

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "<WHATSAPP_USER_PHONE_NUMBER>",
  "type": "<MESSAGE_TYPE>",
  "<MESSAGE_TYPE>": {<MESSAGE_CONTENTS>}
}

Der Wert der Eigenschaft type in der Payload des Post-Inhalts gibt die zu sendende Art von Nachricht an. Außerdem muss eine diesem Typ entsprechende Eigenschaft enthalten sein, die den Inhalt der Nachricht beschreibt.

Dies ist beispielsweise eine Anfrage zum Senden einer Textnachricht an eine*n WhatsApp-Benutzer*in. Beachte, dass type auf text festgelegt ist und ein text-Objekt folgt, das den Inhalt der Nachricht beschreibt:

curl 'https://graph.facebook.com/v20.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+16505551234",
  "type": "text",
  "text": {
    "preview_url": true,
    "body": "As requested, here'\''s the link to our latest product: https://www.meta.com/quest/quest-3/"
  }
}'

Die Textnachricht würde im WhatsApp-Client demnach folgendermaßen aussehen, wenn sie erfolgreich an den*die WhatsApp-Benutzer*in zugestellt wurde:

Antworten

Wenn die API deine Anfragen zum Senden einer Nachricht erfolgreich akzeptiert, ohne dass in der Anfrage selbst Fehler auftreten, sendet sie die folgende Antwort:

{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "<WHATSAPP_USER_PHONE_NUMBER>",
      "wa_id": "<WHATSAPP_USER_ID>"
    }
  ],
  "messages": [
    {
      "id": "<WHATSAPP_MESSAGE_ID>"
      "message_status": "<PACING_STATUS>"
    }
  ]
}

Beachte, dass diese Antwort nur bedeutet, dass die API deine Anfrage erfolgreich akzeptiert hat. Sie bedeutet nicht, dass deine Nachricht erfolgreich zugestellt wurde. Der Status der Nachrichtenzustellung wird über Nachrichten-Webhooks übermittelt.

Die Eigenschaft message_status wird nur beim Senden von Vorlagennachrichten eingeschlossen, die eine Vorlage verwenden, die einem Pacing unterzogen wird.

Webhooks

An WhatsApp-Benutzer*innen gesendete Nachrichten lösen Nachrichten-Webhooks aus. Abonniere dieses Thema daher unbedingt, um Benachrichtigungen zum Nachrichtenstatus zu erhalten.

Commerce-Nachrichten

Commerce-Nachrichten sind interaktive Nachrichten, die zusammen mit einem Produktkatalog verwendet werden. Unter Produkte mit Kund*innen teilen findest du Informationen zur Verwendung dieses Nachrichtentyps.

Antworten

Du kannst jede Art von Nachricht als Antwort auf eine vorherige Nachricht senden. Die vorherige Nachricht wird oben in der neuen Nachricht in einer Kontextsprechblase als Zitat angezeigt.

Einschränkungen

Die Kontextsprechblase wird nicht oben in der als Antwort gesendeten zugestellten Nachricht angezeigt, wenn:

• die vorherige Nachricht gelöscht oder in den Langzeitspeicher verschoben wurde (Nachrichten werden normalerweise nach 30 Tagen in den Langzeitspeicher verschoben, es sei denn, du hast die lokale Speicherung aktiviert).
• du mit einer Audio-, Bild- oder Videonachricht antwortest und der*die WhatsApp-Benutzer*in KaiOS verwendet.
• du den WhatsApp-Client verwendest, um mit einer Push-to-Talk-Nachricht zu antworten, und der*die WhatsApp-Benutzer*in KaiOS verwendet.
• du mit einer Vorlagennachricht antwortest.

Anfragesyntax

POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/messages

Anfrageinhalt

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "<WHATSAPP_USER_PHONE_NUMBER>",
  "context": {
    "message_id": "WAMID_TO_REPLY_TO"
  },

  /* Message type and type contents goes here */

}

Parameter für den Beitragstext

Beispielanfrage

Beispiel einer Textnachricht als Antwort auf eine vorherige Nachricht.

curl 'https://graph.facebook.com/v19.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+16505551234",
  "context": {
    "message_id": "wamid.HBgLMTY0NjcwNDM1OTUVAgASGBQzQTdCNTg5RjY1MEMyRjlGMjRGNgA="
  },
  "type": "text",
  "text": {
    "body": "You'\''re welcome, Pablo!"
  }
}'

Medien-Assets

Medien-Assets in gesendeten Nachrichten müssen an die Unternehmenstelefonnummer hochgeladen werden, die die Nachricht sendet, oder du musst das Asset auf einem öffentlichen Server hosten und seine URL in die Anfrage zum Senden der Nachricht aufnehmen.

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-HTTP-Caching

Die WhatsApp Cloud API unterstützt Medien-HTTP-Caching. Wenn du anstelle der ID (id) eines Assets, das du auf unsere Server hochgeladen hast, einen Link (link) zu einem Medien-Asset auf deinem Server verwendest, kannst du die unten stehenden Header in deine Serverantwort aufnehmen, wenn wir das Asset anfordern. So weist du uns an, dein Asset für die Wiederverwendung in zukünftigen Nachrichten zu cachen. Wenn du keinen dieser Header angibst, wird dein Asset nicht gecacht.

Cache-Control: <CACHE_CONTROL>
Last-Modified: <LAST_MODIFIED>
ETag: <ETAG>

Cache-Control

Der Cache-Control-Header teilt uns mit, wie das Asset-Caching erfolgen soll. Wir unterstützen die folgenden Anweisungen:

• max-age=n: Gibt an, wie viele Sekunden (n) das Asset gecacht werden soll. Wir verwenden das gecachte Asset in nachfolgenden Nachrichten, bis diese Zeitspanne abgelaufen ist. Anschließend fordern wir das Asset bei Bedarf erneut an. Beispiel: Cache-Control: max-age=604800.
• no-cache: Gibt an, dass das Asset gecacht werden kann, aber aktualisiert werden sollte, wenn sich der Wert des Last-Modified-Headers von dem einer früheren Antwort unterscheidet. Erfordert den Last-Modified-Header. Beispiel: Cache-Control: no-cache.
• no-store: Gibt an, dass das Asset nicht gecacht werden sollte. Beispiel: Cache-Control: no-store.
• private: Gibt an, dass das Asset für den*die Empfänger*in personalisiert wurde und nicht gecacht werden soll.

Last-Modified

Gibt den Zeitpunkt der letzten Änderung des Assets an. Wird mit Cache-Control: no-cache verwendet. Wenn sich der Last-Modified-Wert von dem einer früheren Antwort unterscheidet und Cache-Control: no-cache in der Antwort enthalten ist, aktualisieren wir unsere gecachte Version des Assets mit dem Asset in der Antwort. Beispiel: Date: Tue, 22 Feb 2022 22:22:22 GMT.

ETag

Der ETag-Header ist ein eindeutiger String, der eine bestimmte Version eines Assets identifiziert. Beispiel: ETag: "33a64df5". Dieser Header wird ignoriert, sofern nicht sowohl der Header Cache-Control als auch der Header Last-Modified in der Antwort enthalten sind. In diesem Fall cachen wir das Asset gemäß unserer eigenen internen Logik (die nicht offengelegt wird).

Beispielantwort mit Headern

HTTP/1.1 200 OK
Content-Type: image/png
Content-Length: 1024
Date: Tue, 22 Feb 2022 22:22:22 GMT
ETag: "33a64df5"
Cache-Control: max-age=604800

<IMAGE_PAYLOAD>

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.

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 oder Nachrichtengültigkeitsdauer genannt wird. Wenn wir eine Nachricht für einen Zeitraum, der die TTL überschreitet, nicht zustellen können, beenden wir die wiederholten Zustellungsversuche und die Nachricht wird verworfen.

• Die TTL beträgt für alle Nachrichten mit Ausnahme von Vorlagennachrichten, die eine Authentifizierungsvorlage verwenden, 30 Tage.
• Vorlagennachrichten, die eine Authentifizierungsvorlage verwenden, haben eine Standard-TTL von 10 Minuten.

Du kannst diese Standardwerte anpassen, indem du eine selbstdefinierte TTL für Authentifizierungs- und Dienstvorlagen festlegst. Siehe Anpassen der Time-to-Live.

Wenn du eine Nachricht sendest, aber keinen entsprechenden messages-Webhook erhältst, der anzeigt, dass die Nachricht zugestellt wurde, bevor die TTL überschritten wurde, solltest du davon ausgehen, dass die Nachricht verworfen wurde.

Wenn eine Nachricht aus einem anderen Grund fehlschlug und einen delivery failuremessages-Webhook auslöst, kann es zu einer kleinen Verzögerung kommen, bevor du den Webhook erhältst. Daher solltest du einen kleinen Puffer einbauen, bevor du davon ausgehst, dass die Nachricht verworfen wurde.

Problembehebung

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