Cloud API

WhatsApp Business Platform > Cloud API

Übersicht

Über die Cloud API, gehostet von Meta, können mittelständische und große Unternehmen im großen Maßstab mit Kund*innen kommunizieren. Mit der API können Unternehmen Systeme aufbauen, die Tausende Kund*innen mit Mitarbeiter*innen oder Bots verbinden, und zwar für programmgesteuerte und manuelle Kommunikation. Außerdem können Unternehmen die API mit einer Vielzahl von Backend-Systemen integrieren, wie z. B. CRM- und Marketingplattformen.

HTTP-Protokoll

Die Cloud API baut auf die Graph API auf. Daher werden Anfragen mithilfe des HTTP-Protokolls und Kombinationen aus URL-Parametern, Headern und Anfragetext ausgedrückt. Ein üblicher Aufruf an die Cloud API über die UNIX-basierte Befehlszeile sieht zum Beispiel so aus:

curl 'https://graph.facebook.com/v17.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+16505555555",
  "type": "text",
  "text": {
    "preview_url": true,
    "body": "Here'\''s the info you requested! https://www.meta.com/quest/quest-3/"
  }
}'

Wenn du dich noch nicht gut mit der Graph API auskennst, lies bitte die Graph API-Dokumentation, um mehr über die Grundlagen zu erfahren. Die Hauptunterschiede zwischen der Graph API und der Cloud API liegen darin, welche Zugriffsschlüssel-Typen du üblicherweise verwendest, sowie in den Ressourcenberechtigungen, der Abfragesyntax und der Webhooks-Syntax. Diese Unterschiede werden in den entsprechenden Abschnitten der Dokumentation zur Cloud API genauer beschrieben.

Ressourcen

Dies sind die primären Ressourcen, die du bei der Verwendung der API nutzen wirst.

Business-Portfolio

Für die Verwendung der API benötigst du ein Unternehmensportfolio. Wenn du kein Portfolio hast, wirst du aufgefordert, im Rahmen unseres Prozesses Erste Schritte ein Konto zu erstellen. Business-Portfolios dienen als Container für Ihr WhatsApp Business-Konto (WABA) und Ihre Unternehmenstelefonnummern.

Weitere Informationen über Business-Portfolios findest du im Hilfebereich in unserem Artikel Info zu Business-Portfolios in der Meta Business Suite.

WhatsApp Business-Konten

Ein WhatsApp Business-Konto repräsentiert ein Unternehmen auf der WhatsApp Business-Platform und enthält hauptsächlich Metadaten über ein bestimmtes Unternehmen. Die meisten anderen WhatsApp-Ressourcen, wie WhatsApp Business.Telefonnummern und WhatsApp-Nachrichtenvorlagen sind mit einem WABA verknüpft.

Du kannst ein WABA erstellen, indem du die Schritte in unserem Dokument Erste Schritte befolgst. Weitere Informationen über WABAs und ihre Einschränkungen findest du unter WhatsApp-Unternehmenskonten.

WhatsApp Business-Telefonnummern

Eine WhatsApp Business-Telefonnummer (Unternehmenstelefonnummer) stellt eine echte Telefonnummer dar, die, sobald sie für die Cloud API registriert ist, zum Senden und Empfangen von WhatsApp-Nachrichten an und von WhatsApp-Benutzer*innen über die API verwendet werden kann.

Unternehmenstelefonnummern bestehen enthalten hauptsächlich Metadaten über die Nummer selbst und dein Unternehmen. Diese Metadaten können im WhatsApp-Client angezeigt werden, wenn Benutzer*innen mit deiner Unternehmenstelefonnummer interagieren.

Du kannst eine Unternehmenstelefonnummer erstellen, indem du die Schritte in unserem Dokument Erste Schritte befolgst. Beachte, dass Beschränkungen und Einschränkungen für Unternehmenstelefonnummern und deren Verwendung gelten. Diese werden in unserem Dokument Unternehmenstelefonnummern detailliert beschrieben.

WhatsApp-Nachrichtenvorlagen

WhatsApp-Nachrichtenvorlagen (Vorlage) sind anpassbare Vorlagen, die du über die API mit verschiedenen Vorlagenkomponenten konstruieren kannst. Sobald sie erstellt wurden, werden sie automatisch überprüft und können nach ihrer Genehmigung in Vorlagennachrichten verwendet werden.

Es gibt zwei grundlegende Arten von Nachrichten, die du über die API senden kannst: Freiformnachrichten und Vorlagennachrichten. Für Vorlagennachrichten gelten hierbei die meisten Einschränkungen, weil sie die Verwendung einer genehmigten WhatsApp-Nachrichtenvorlage erfordern. Da Vorlagen jedoch überprüft und genehmigt werden müssen, bevor sie verwendet werden können, erhalten Vorlagennachrichten weniger wahrscheinlich negatives Feedback von den Empfänger*innen, welches deine Möglichkeit, Nachrichten an Kund*innen zu gefährden könnte.

Weitere Informationen über Vorlagen findest du in unserem Dokument Vorlagen.

Webhooks

Webooks sind im Grunde JSON-Payloads, die mit dem HTTP-Protokoll an einen öffentlichen Endpunkt auf deinem Server gesendet werden. Die Cloud API ist stark auf Webhooks angewiesen, da die Inhalte aller Nachrichten, die von einem*einer WhatsApp-Benutzer*in an deine Unternehmenstelefonnummer gesendet werden, als Webhook gesendet werden und alle Statusmeldungen für ausgehende Nachrichten ebenfalls als Webhook gemeldet werden.

Wir stellen eine Beispiel-App für Webhooks bereit, die du in Glitch klonen und zu Testzwecken verwenden kannst. Die App exportiert Webhooks-Payloads direkt in eine Konsole, sodass du deren Inhalt sehen kannst. Beachte, dass du an einem gewissen Punkt schließlich deinen eigenen Endpunkt auf deinem eigenen Server erstellen musst, der Webhooks gemäß deiner eigenen Unternehmenslogik verarbeitet.

Weitere Informationen zu Webhooks und deren Verarbeitung findest du unter Meta-Webhooks und in unserem Dokument Webhooks für WhatsApp Business Accounts.

Testressourcen

Sobald du die Schritte in unserem Dokument Erste Schritte durchgeführt hast, werden automatisch ein Test-WABA- und eine Test-Unternehmenstelefonnummer für dich erstellt.

Test-WABAs und Test-Telefonnummern sind für Testzwecke nützlich, da sie die meisten Nachrichtenlimits umgehen und keine hinterlegte Zahlungsmethode erforderlich ist, um Vorlagennachrichten zu versenden.

Du kannst dein Business-Portfolio und seine Testressourcen löschen, wenn:

  • du Admin des mit der App verbundenen Business-Portfolios bist
  • keine anderen Apps mit dem Business-Portfolio verknüpft sind
  • das Business-Portfolio nicht mit anderen WABAs verknüpft ist
  • der WABA nicht mit anderen Unternehmenstelefonnummern verknüpft ist

So löschst du dein Business-Portfolio und seine Testressourcen:

  1. Gehe zu App-Dashboard > WhatsApp > Konfiguration.
  2. Suche den Abschnitt Testkonto.
  3. Klicke auf den Button Löschen.

Authentifizierung und Autorisierung

Zugriffsschlüssel

Die API unterstützt drei Arten von Token:

  • Systemnutzer-Zugriffsschlüssel
  • Business-Integration-Systemnutzer-Zugriffsschlüssel
  • Nutzungs-Zugriffsschlüssel

Unter Zugriffsschlüssel kannst du ermitteln, welche Art von Token du verwenden solltest. Beachte, dass Token über Anfrage-Header weitergegeben werden sollten, nicht als Abfrage-String-Parameter.

Berechtigungen

Die API ist von folgenden Berechtigungen der Graph API abhängig. Die genaue Kombination der Berechtigungen, die deine App benötigt, hängt davon ab, auf welche Endpunkte deine App zugreift.

  • business_management: Erforderlich für die Interaktion mit einem Business-Portfolio.
  • whatsapp_business_management: Erforderlich für die Interaktion mit einem WABA und seinen Analysen oder einer seiner Vorlagen oder Unternehmenstelefonnummern.
  • whatsapp_business_messaging: Erforderlich, um Nachrichten an WhatsApp-Benutzer*innen zu senden und von ihnen zu empfangen.

Diese Berechtigungen werden normalerweise erteilt, wenn Zugriffsschlüssel in der Meta Business Suite generiert werden. Weitere Informationen findest du in den Abschnitten zur Tokengenerierung in unserem Dokument Zugriffsschlüssel.

Versionierung

Bei der Versionierung wird das Versionierungsprotokoll für Graph API verwendet. Das bedeutet, dass alle Endpunktanfragen eine Versionsnummer beinhalten können. Jede Version wird etwa zwei Jahre lang verfügbar sein, bevor sie eingestellt wird und nicht mehr abgerufen werden kann.

Durchsatz

Für jede registrierte Unternehmenstelefonnummer unterstützt die Cloud API standardmäßig bis zu 80 Nachrichten pro Sekunde (mps) und bis zu 1.000 mps durch automatisches Upgrade.

Der Durchsatz umfasst alle eingehenden und ausgehenden Nachricht sowie alle Nachrichtentypen. Beachte, dass Unternehmenstelefonnummern unabhängig von ihrem Durchsatz, den Business Use Case-Ratenbegrenzungen und Template-Nachrichtenlimits ihres WhatsApp-Unternehmenskontos unterliegen.

Wenn du versuchst, mehr Nachrichten zu senden, als deine aktuelle Durchsatzrate zulässt, gibt die API den Fehlercode 130429 zurück, bis du dich wieder innerhalb deiner zulässigen Durchsatzrate befindest. Außerdem sind Durchsatzraten für Messaging-Kampagnen vorgesehen, an denen unterschiedliche Telefonnummern von WhatsApp-Benutzer*innen beteiligt sind. Wenn du versuchst, zu viele Nachrichten an dieselbe Telefonnummer eines*einer WhatsApp-Benutzer*in zu senden, kann es zu einem Fehler bei der Kopplungsratenbegrenzung kommen.

Höherer Durchsatz

Wenn du unsere Berechtigungsanforderungen erfüllst, rüsten wir deine Unternehmenstelefonnummer automatisch auf 1.000 mps auf, ohne dass dir dadurch Kosten entstehen. Ein höherer Durchsatz bedeutet keine zusätzlichen Kosten und beeinflusst die Preisgestaltung nicht.

Der Upgrade-Prozess kann bis zu 1 Minute dauern. Während dieser Zeit kann die Nummer nicht auf unserer Plattform verwendet werden. Wenn sie in einer API-Anfrage verwendet wird, gibt die API den Fehlercode 131057 zurück. Sobald für eine Unternehmenstelefonnummer ein Upgrade durchgeführt wurde, wird sie automatisch für zukünftige Durchsatzerhöhungen ohne Downtime aktualisiert.

Qualifikationskriterien

Webhooks

Deine Webhook-Server sollten die dreifache Kapazität des ausgehenden und die einfache Kapazität des voraussichtlich eingehenden Nachrichtenverkehrs bewältigen können. Wenn du zum Beispiel 1.000 mps bei einer voraussichtlichen Reaktionsrate von 30 % sendest, sollte es für deine Server möglich sein, mehr als 3.000 Nachrichtenstatus-Webhooks sowie 300 eingehende Nachrichten-Webhooks zu verarbeiten.

Da wir versuchen Webhooks gleichzeitig zuzustellen, empfehlen wir, deine Webhook-Server zu konfigurieren und Belastungstests durchzuführen, damit diese gleichzeitige Anfragen mit dem folgenden Latenzstandard verarbeiten können:

  • Die Median-Latenz darf 250 ms nicht überschreiten.
  • Weniger als 1 % darf 1 s überschreiten.

Wir versuchen, fehlgeschlagene Webhooks bis zu sieben Tage lang erneut zuzustellen (mit exponentiellem Backoff).

Mediennachrichten

Damit du den höheren Durchsatz in vollem Umfang nutzen kannst, empfehlen wir dir, deine Medien-Assets auf unsere Server hochzuladen und die zurückgegebene Medien-IDs in Mediennachrichten zu verwenden, anstatt die Assets auf deinen eigenen Servern zu hosten und Medien-Asset-URLs zu verwenden. Wenn du deine Assets lieber auf deinen eigenen Servern hostest (oder dies tun musst), solltest du Medien-Caching verwenden.

Durchsatzrate abrufen

Verwende den WhatsApp Business-Telefonnummer-Endpunkt, um die aktuelle Durchsatzrate einer Telefonnummer abzurufen:

GET /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>?fields=throughput

Migration

Wenn du eine Unternehmenstelefonnummer migrierst, die mit Multiconnect zwei oder mehr Shards von der On-Premises API zur Cloud API ausführt, wird die Telefonnummer automatisch auf einen höheren Durchsatz hochgestuft.

Durchsatzratenbegrenzungen

Siehe Durchsatzratenbegrenzungen der WhatsApp Business Management API.

Zusätzlich zu diesen Durchsatzratenbegrenzungen haben wir detailliertere Limits für einzelne Ressourcen wie Vorlagennachrichten und Testtelefonnummern für Unternehmen:

Verfügbare Metriken

Als Cloud API-Benutzer*in kannst du die Anzahl der gesendeten und zugestellten Nachrichten sowie weitere Metriken einsehen. Mehr dazu erfährst du unter Kontokennzahlen abrufen.

Skalierung

Die Cloud API wird innerhalb der Meta-Infrastruktur automatisch entsprechend deiner Arbeitslast und gemäß deiner Ratenbegrenzung (Nachrichtenvolumen und Anzahl an WABAs) skaliert.

Datenschutz und Sicherheit

Nähere Informationen findest du in unserer Übersicht über Datenschutz und Sicherheit.

Verschlüsselung

Mit der Cloud API ist jede WhatsApp-Nachricht weiterhin durch Verschlüsselung nach Signal-Protokoll geschützt. Damit werden Nachrichten gesichert, bevor sie das Gerät verlassen. Das bedeutet, dass Nachrichten mit einem WABA sicher an das vom Unternehmen gewählte Ziel zugestellt werden.

Die Cloud API verwendet nach Branchenstandard übliche Verschlüsselungsverfahren, um Daten während der Übertragung und im Ruhezustand zu sichern. Die API nutzt die Graph API zum Senden von Nachrichten und Webhooks für den Empfang von Events, jeweils nach Branchenstandard über HTTPS mit TLS-Schutz. Nähere Informationen findest du in unserem Whitepaper mit einem Überblick über die Verschlüsselung.

Nähere Informationen findest du in unserem Whitepaper mit einem Überblick über die Verschlüsselung.

Kopplungsratenbegrenzung

Unternehmenstelefonnummern dürfen alle 6 Sekunden nur eine Nachricht an dieselbe Telefonnummer eines*einer WhatsApp-Benutzer*in senden (0,17 Nachrichten/Sekunde). Dies entspricht ungefähr 10 Nachrichten pro Minute oder 600 Nachrichten pro Stunde. Wenn du dieses Limit überschreitest, gibt die API den Fehlercode 131056 zurück, bis du dich wieder unter deinem Limits befindest.

Du kannst ggf. innerhalb von 6 Sekunden bis zu 45 Nachrichten kurz hintereinander versenden. Wenn du Nachrichten kurz hintereinander senden, wirkt sich das auf die Kopplungsratenbegrenzung aus, d. h. du wirst daran gehindert, nachfolgende Nachrichten an denselben*dieselbe Benutzer*in zu senden, bis die Zeitspanne verstrichen ist, die normalerweise erforderlich wäre, um die gleiche Menge an nicht aufeinanderfolgenden Nachrichten an den*die Benutzer*in zu senden. Beispielsweise dauert es ca. 2 Minuten, um 20 nicht aufeinanderfolgende Nachrichten an eine*n Benutzer*in zu senden. Wenn du also 20 Nachrichten kurz hintereinander sendest, musst du ca. 2 Minuten warten, bevor du eine weitere Nachricht an den*die Benutzer*in senden kannst.

Um zu vermeiden, dass die Wartezeiten nach Nachrichtenserie berechnet werden müssen, empfehlen wir, dass du, wenn eine Sendeanfrage einer Nachricht nach dem Senden eines Nachrichtenserie fehlschlägt, es 4^X Sekunden später erneut zu versuchen, wobei X = 0 ist, und nach jedem fehlgeschlagenen Versuch um 1 erhöht wird, bis die Anfrage erfolgreich ist.

Tools

WhatsApp Manager

Der WhatsApp Manager ist unsere Web-App, mit der du WhatsApp-Ressourcen wie WABAs, Unternehmenstelefonnummern und Vorlagen manuell verwalten kannst. Er bietet eine einfache Möglichkeit, Insights und Qualitätsbewertungen oder Einschränkungen für diese Ressourcen zu sehen. Die meisten WhatsApp Manager-Funktionen sind auch über die API verfügbar. Es gibt nur wenige Ausnahmen.

Es gibt verschiedene Möglichkeiten, auf den WhatsApp Manager zuzugreifen. Für die einzelnen Pfade wird angenommen, dass du alle in unserem Dokument Erste Schritte genannten Schritte bereits abgeschlossen hast.

Über die Meta Business Suite

  1. Melde dich bei der Meta Business Suite an.
  2. Wenn du mehrere Business-Portfolios hast, wähle im Dropdown-Menü links das Konto aus, zu dem der WABA gehört oder auf das er Zugriff hat, das in den WhatsApp Manager geladen werden soll.
  3. Navigiere im Menü links zu Konten > WhatsApp-Konten.
  4. Wähle den WABA aus.
  5. Klicke im Tab Zusammenfassung auf den Button WhatsApp Manager.

Über das App-Dashboard

  1. Gehe zu Meine Apps.
  2. Wähle die App aus, die mit dem WABA verknüpft ist, den du in den WhatsApp Manager laden möchtest.
  3. Navigiere im Menü links zu WhatsApp > Kurzanleitung.
  4. Klicke auf die Kachel Kontoinformationen im Abschnitt WhatsApp Business.

Über URL

Du kannst direkt zur WhatsApp Manager-Übersicht wechseln. Hier findest du alle WABAs, die einem bestimmten Business-Portfolio zugewiesen sind oder mit diesem geteilt werden, unter:

https://business.facebook.com/wa/manage/home/

In der Übersicht wird standardmäßig der neueste WABA geladen, den du erstellt hast oder auf den du Zugriff erhalten hast. Du kannst jedoch im Dropdown-Menü auf der linken Seite das Business-Portfolio auswählen, das den WABA enthält, auf den du zugreifen möchtest. Dadurch verlässt du jedoch die Übersicht und musst mit dem Menü auf der linken Seite zu Konten > WhatsApp-Konten > (wähle den gewünschten WABA) > Einstellungen > WhatsApp Manager (Button) navigieren.

Wenn du mehrere Business-Portfolios hast, kannst du alternativ die ID eines Kontos am Ende der URL anhängen und sie für einen einfacheren Zugriff mit einem Lesezeichen versehen:

https://business.facebook.com/wa/manage/home/?business_id=<META_BUSINESS_ACCOUNT_ID>

Postman

In unserem Arbeitsbereich der WhatsApp Business Platform findest du eine Postman-Sammlung zur Cloud API, die gängige Abfragen enthält.