Zum Inhalt springen
30 min read

Verbindung über die Meta Graph API

Eine bestehende WhatsApp Cloud API-Integration auf WizMessage umstellen, ohne sie neu zu schreiben — Metas Pfade, Metas Request-Bodies, Metas Fehler-Envelope, Webhooks in Metas eigenem Format und die Endpunkte zur Kontoverwaltung für Vorlagen, Business-Profil, QR-Codes und Flows.

Verbindung über die Meta Graph API

Es gibt zwei Möglichkeiten, WhatsApp-Nachrichten über WizMessage zu senden. Die WizMessage API ist die erste Wahl, wenn Sie bei null anfangen — sie bietet Ihnen benannte Vorlagenvariablen, eine Mapping-Benutzeroberfläche und ein reference-Feld, über das Sie Ihre eigenen Datensätze verknüpfen können.

Diese Seite dokumentiert die andere. Sie bildet Metas WhatsApp Cloud API so genau nach, dass Code, der bereits für Meta geschrieben wurde, hier nach der Änderung von zwei Dingen funktioniert: der Basis-URL und dem Token. Dieselben Pfade, dieselben Request-Bodies, dieselben Response-Bodies, derselbe Fehler-Envelope. Wenn Sie eine bestehende Integration, eine Bibliothek oder einen Entwickler haben, der die Cloud API bereits kennt, ist dies der kürzere Weg.

Sie ist nicht nur eine Schnittstelle zum Senden. Neben dem Messaging umfasst sie die Endpunkte zur Kontoverwaltung — das Erstellen und Löschen von Vorlagen, das Lesen und Umschreiben des Business-Profils, QR-Codes, Commerce-Einstellungen, die Sperrliste, Telefoneinstellungen und Flows — alles unter Metas eigenen Pfaden. Kontoverwaltung ist der Katalog, und Was hier nicht verfügbar ist ist die ebenso wichtige andere Hälfte.

Beide Schnittstellen nutzen dieselben API-Schlüssel, dieselben Berechtigungen und dieselben Ratenbegrenzungen. Nichts davon ist veraltet — wählen Sie pro Integration, und Sie können beide gleichzeitig nutzen.

Welche Option Sie benötigen

Die WizMessage API im Vergleich zur Meta-Graph-kompatiblen APIWählen Sie die Option, die zu dem passt, was Sie bereits habenWizMessage API/api/v1/externalbenannte VorlagenvariablenMapping-UI im Dashboardreference-Feld, Statusabfrageunser eigener JSON-Envelopeam besten, wenn Sie bei null anfangenMeta Graph API/v26.0/{phone-number-id}/…Metas Request-BodiesMetas Fehler-EnvelopeVorlagen und Profil verwaltenWebhooks in Metas Formatam besten, wenn Sie bereits Cloud-API-Code habenDieselben Schlüssel, dieselben Berechtigungen, dieselben Ratenbegrenzungen. Nutzen Sie gerne beide.
Zwei Schnittstellen, ein Konto. Keine von beiden wird eingestellt.

Die Grundlagen

Basis-URL und die Version im Pfad

https://wizmessage.com/v26.0/{phone-number-id}/messages

Das Versionssegment ist echt und erforderlich, aber sein Wert ändert nichts. Wir gleichen es als v{major}.{minor} ab und ignorieren es anschließend — die Plattform entscheidet, mit welcher Graph-Version sie upstream spricht.

Zwei Konsequenzen, die Sie kennen sollten:

  • Das Festhalten an einer alten Version funktioniert weiterhin. Wenn Meta die Version einstellt, die in Ihrem Code fest vorgegeben ist, laufen Aufrufe hier weiter. Sie müssen nichts einplanen.
  • v26 allein wird abgelehnt. Die Minor-Nummer ist nicht optional. v26.0 ist in Ordnung, v26 ist ein 404-Fehler.

Die {phone-number-id} muss die WhatsApp-Nummer hinter dem von Ihnen verwendeten API-Schlüssel sein. Alles andere wird abgelehnt — siehe Wenn eine ID nicht Ihnen gehört.

Authentifizierung

Senden Sie Ihren API-Schlüssel als Bearer-Token, genau so, wie Sie Meta ein Zugriffstoken senden würden.

HeaderWert
AuthorizationBearer pk_live_… — Ihr vollständiger API-Schlüssel, nicht das im Dashboard angezeigte Präfix.

X-API-Key wird hier ebenfalls akzeptiert, sodass ein Schlüssel, der bereits mit der WizMessage API funktioniert, keine Änderung des Headers benötigt. Bearer ist die zu bevorzugende Form: Es ist das, was ein unverändertes Meta-SDK sendet, und genau darum geht es bei dieser Schnittstelle.

Hinweis: „Require signature“ muss beim Schlüssel deaktiviert sein. Hier ist es keine reine Präferenz. Ein Schlüssel mit aktivierter Option kann keinen Meta-Graph-Webhook speichern — das Dashboard verweigert dies mit „Signed-request enforcement is not compatible with the Graph format — disable it on this key first“ — und jeder unsignierte Aufruf, den er über diese Schnittstelle ausführt, wird als code 190 mit 401 abgelehnt. Ein standardmäßiger Cloud-API-Client kann unsere Anfragesignatur nicht erzeugen, weshalb sich beides konzeptbedingt gegenseitig ausschließt.

Ihr Abonnement

Das API-Modul erfordert ein aktives Wiz Bot- oder Wiz Pro-Abonnement. Dies gilt für beide Schnittstellen — die WizMessage API und diese hier — und wird bei jedem Aufruf überprüft, nicht nur bei der Erstellung des Schlüssels.

Wenn das Abonnement abläuft, stoppt die API nicht im selben Moment. Der erste Aufruf nach dem Ablauf startet ein siebentägiges Zeitfenster und wird durchgelassen, und jede Antwort während dieses Zeitfensters enthält einen Header:

HeaderWert
X-Subscription-WarningSubscription inactive. API access ends in 5 day(s).

Nach Ablauf des Zeitfensters werden Aufrufe mit Graph-code 10 und Status 403 abgelehnt:

{
	"error": {
		"message": "(#10) Access denied. The API module requires an active Wiz Bot or Wiz Pro subscription. Renew at /subscriptions to restore access.",
		"type": "OAuthException",
		"code": 10,
		"fbtrace_id": "AKnBaXsYl7FlmMVw3ql5Ywo"
	}
}
Was mit dem API-Zugriff geschieht, nachdem ein Abonnement abgelaufen istein API-Schlüsselnormalkein HeaderKulanzfenster7 Tage, Aufrufe gelingen weiterhinX-Subscription-Warning bei jeder AntwortabgewiesenCode 10 bei 403erster Aufruf nach dem AblaufZeit läuft ab hierZeitfenster endetkeine weitere WarnungEine Verlängerung zu einem beliebigen Zeitpunkt stellt den Zugriff innerhalb weniger Minuten wieder her.
Der Ablauf selbst ändert nichts. Die Zeit läuft ab Ihrem nächsten Aufruf.

Drei Details, die darüber entscheiden, ob Sie es rechtzeitig bemerken:

  • Die Zeit läuft ab Ihrem ersten Aufruf, nicht ab dem Abrechnungsdatum. Ein Schlüssel, der nach einem Ablauf zwei Wochen lang ungenutzt bleibt, erhält dennoch seine vollen sieben Tage, beginnend mit seinem nächsten Aufruf.
  • Das Zeitfenster gilt pro API-Schlüssel, nicht pro Konto. Für jeden Schlüssel läuft eine eigene Frist ab seinem eigenen ersten Aufruf, sodass ein Schlüssel, mit dem Sie testen, und ein Schlüssel im Produktivbetrieb an unterschiedlichen Tagen ablaufen. Prüfen Sie den Header bei dem Schlüssel, auf den es ankommt.
  • Die Ablehnung erfolgt ohne Vorwarnung bei der Anfrage, die sie auslöst. X-Subscription-Warning ist die einzige Vorwarnung, die es gibt — protokollieren Sie sie, sonst erfahren Sie erst durch einen 403-Fehler davon.

Hinweis: Eine Verlängerung wird erst nach einigen Minuten wirksam, nicht innerhalb von Sekunden. Die Berechtigungsantwort wird fünf Minuten lang zwischengespeichert und der dahinterliegende Abonnementstatus für weitere fünf Minuten; eine Verlängerung, die vorgenommen wird, während eine Integration fehlschlägt, wird daher nicht gleich beim nächsten Wiederholungsversuch wirksam. Warten Sie einige Minuten, bevor Sie den Schluss ziehen, dass es nicht funktioniert hat.

Eine Nachricht senden

POST /{version}/{phone-number-id}/messages, mit dem Body von Meta. Wir validieren ihn nicht weiter, abgesehen von der Prüfung, ob es sich um eine WhatsApp-Nachricht handelt — Meta ist die maßgebliche Instanz dafür, wie eine gültige Nachricht aussieht, und Metas Fehlermeldungen sind besser als alle, die wir erfinden könnten.

POST https://wizmessage.com/v26.0/106540352242922/messages

{
	"messaging_product": "whatsapp",
	"recipient_type": "individual",
	"to": "919876543210",
	"type": "text",
	"text": { "preview_url": false, "body": "Your order has shipped." }
}

Hinweis: to akzeptiert hier reine Ziffern — 919876543210, kein +. Dies ist das Format von Meta und der häufigste Fehler beim Wechsel zwischen den beiden Schnittstellen: Die WizMessage API erfordert +E.164 und lehnt alles andere ab, während diese Schnittstelle Ihren Wert direkt an Meta weiterleitet. Die einzige Ausnahme ist POST /messages/contacts, was genau deshalb beide Formen akzeptiert, damit ein Graph-Body unverändert portiert werden kann.

Auch der Vorlagenversand entspricht der Struktur von Meta — positionelle Komponenten, keine benannten Variablen. Auf dieser Schnittstelle gibt es keine Mapping-Schicht, was der Kompromiss für die Kompatibilität ist.

{
	"messaging_product": "whatsapp",
	"to": "919876543210",
	"type": "template",
	"template": {
		"name": "payment_failed_alert",
		"language": { "code": "en" },
		"components": [
			{
				"type": "body",
				"parameters": [
					{ "type": "text", "text": "Priya Sharma" },
					{ "type": "text", "text": "12 Aug 2026" },
					{ "type": "text", "text": "Wiz Pro" }
				]
			}
		]
	}
}

Eine Kontaktkarte senden

type: "contacts" ist eine vCard — ein Name und was immer Sie sonst anhängen. Dies hat auf dieser Schnittstelle schon immer funktioniert und tut es noch immer, mit Metas unverändertem Body.

POST https://wizmessage.com/v26.0/106540352242922/messages

{
	"messaging_product": "whatsapp",
	"recipient_type": "individual",
	"to": "919876543210",
	"type": "contacts",
	"contacts": [
		{
			"name": {
				"formatted_name": "Priya Sharma",
				"first_name": "Priya",
				"last_name": "Sharma"
			},
			"phones": [
				{ "phone": "+911122334455", "type": "WORK", "wa_id": "911122334455" }
			],
			"emails": [
				{ "email": "[email protected]", "type": "WORK" }
			],
			"org": { "company": "Acme Retail", "department": "Support", "title": "Account Manager" }
		}
	]
}

name.formatted_name ist das einzige Feld, das WhatsApp voraussetzt. phones[].wa_id lohnt sich dennoch hinzuzufügen: Damit enthält die Karte einen Message-Button, der einen Chat mit dieser Person öffnet; ohne diese Angabe kann die Karte nur gespeichert werden.

Genau dieser Body lässt sich auch an POST /messages/contacts in der WizMessage API senden — Envelope-Schlüssel, reine Ziffern für to und alles inklusive. Es ist der einzige Endpunkt auf dieser Schnittstelle, der diese Struktur akzeptiert, und er existiert, weil die zwei Dinge, die dieser Pfad Ihnen nicht bieten kann, wertvoll sind: Ein Versand hier wird nicht unter einer message_id geführt, sodass es keinen abzufragenden Status und keinen abzugleichenden message.sent-Webhook gibt, und der Body wird kaum überprüft, bevor er Meta erreicht. Das Ändern der URL ist bereits die gesamte Migration.

Hinweis: Das Senden mehrerer Karten in einer Nachricht erfolgt über Metas contacts-Array, und Meta akzeptiert bis zu 257 davon. Der WizMessage-Endpunkt begrenzt dies auf zehn — ein Massenversand von Karten, der hier funktioniert, ist also einer der wenigen Bodies, die nicht unverändert übertragen werden können.

Eine Nachricht als gelesen markieren

Lesebestätigungen und Tippindikatoren werden an denselben Endpunkt gesendet, mit einem Body, der weder to noch type enthält. Die Funktion markAsRead() jedes Cloud API-SDKs setzt voraus, dass dies funktioniert, weshalb es genau so unterstützt wird, wie Meta es spezifiziert.

POST https://wizmessage.com/v26.0/106540352242922/messages

{
	"messaging_product": "whatsapp",
	"status": "read",
	"message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgUQ0Uz…"
}

Die Antwort lautet {"success": true} — nicht das Sende-Envelope unten. Verzweigen Sie anhand des Aufrufs, den Sie getätigt haben, anstatt zu versuchen, messages[0].id aus jeder Antwort auszulesen.

Was zurückkommt

Metas Antwort, unverändert:

{
	"messaging_product": "whatsapp",
	"contacts": [{ "input": "919876543210", "wa_id": "919876543210" }],
	"messages": [{ "id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgUQ0Uz…" }]
}

Diese wamid ist Ihre einzige Kennung für die Nachricht. Diese Schnittstelle hat ganz bewusst kein reference-Feld und keinen Endpunkt zur Statusabfrage — beides sind WizMessage-Ergänzungen, die Metas API nicht hat, sodass ihre Aufnahme die Kompatibilität brechen würde, für die diese Schnittstelle existiert.

Um den weiteren Verlauf einer Nachricht zu verfolgen, gleichen Sie die wamid mit den Zustellstatus ab, die auf Ihrem Webhook eingehen. Wenn Sie stattdessen lieber ein eigenes Feld zur Zuordnung hätten, ist genau dafür die reference der WizMessage API gedacht.

Fehler

Fehler werden in Metas Umschlag zurückgegeben, niemals in unserem. Woher der Fehler stammt, bestimmt, wie viel davon von uns kommt.

Wie ein Fehler Sie erreicht, je nachdem, ob Meta ihn erzeugt hatEin Fehler an dieser SchnittstelleMeta hat abgelehntwortgetreu weitergeleitetMetas Code und SubcodeMetas eigene fbtrace_idStatus stammt ebenfalls von MetaWir haben abgelehntAuthentifizierung, Berechtigung, Ratenbegrenzungin Metas Codes verfasstsodass ein Handler beide abdeckt401 · 403 · 429 · 400 · 500Gehen Sie nie davon aus, dass type OAuthException ist — Meta verwendet mehrere.
Metas eigene Fehler werden unberührt weitergeleitet. Unsere übernehmen Metas Codes.

Fehler, die wir auslösen

codeHTTPWann
190401Fehlender, unbekannter, widerrufener, gesperrter oder abgelaufener Schlüssel — oder ein nicht signierter Aufruf mit einem Schlüssel, der Signaturen erfordert. Wird auch ausgelöst, wenn das WhatsApp-Konto selbst seine Verbindung zu Meta verloren hat; siehe den Hinweis unten.
10403Dem Schlüssel fehlt die Berechtigung, die dieser Aufruf benötigt (siehe Berechtigungen), oder das Abonnement des Kontos ist abgelaufen und über die Kulanzfrist hinaus.
4429Das Minuten- oder Tageskontingent des Schlüssels ist aufgebraucht.
100400Fehlerhafte Anfrage, eine ID im Pfad, die nicht Ihnen gehört, oder ein Endpunkt, den diese Schnittstelle nicht bereitstellt.
2500Auf unserer Seite ist ein Fehler aufgetreten. Versuchen Sie es erneut.

Hinweis: Zwei verschiedene Dinge geben 190 zurück, und sie erfordern gegensätzliche Maßnahmen. Wenn die Meldung den Schlüssel erwähnt, rotieren Sie den Schlüssel oder geben Sie ihn erneut ein. Lautet sie „the connection to this WhatsApp Business Account needs to be renewed“, ist der Schlüssel in Ordnung und das Konto hat seine Verknüpfung zu Meta verloren — verbinden Sie es über das Dashboard erneut. Einen funktionierenden Schlüssel als Reaktion auf den zweiten Fall zu rotieren, verschwendet einen Nachmittag und ändert nichts.

Fehler, die Meta auslöst

Werden exakt wie empfangen weitergeleitet, mit Metas HTTP-Status. Alles, was Meta gesendet hat, bleibt erhalten — error_subcode, error_data.details und Metas eigene fbtrace_id:

{
	"error": {
		"message": "Unsupported post request. Object with ID '106540352242922' does not exist, cannot be loaded due to missing permissions, or does not support this operation.",
		"code": 100,
		"type": "GraphMethodException",
		"error_subcode": 33,
		"fbtrace_id": "AKnBaXsYl7FlmMVw3ql5Ywo"
	}
}

Hinweis: Beachten Sie den type in diesem Beispiel — GraphMethodException, nicht OAuthException. Meta verwendet mehrere Ausnahmetypen und wir normalisieren sie nicht. Werten Sie error.code aus, was eine Zahl und stabil ist; behandeln Sie type als Label für Menschen.

Wenn eine ID nicht Ihnen gehört

Jede ID im Pfad — die Telefonnummern-ID, die WABA-ID, eine Medien-ID — wird mit dem Konto hinter Ihrem Schlüssel abgeglichen, bevor irgendetwas anderes geschieht. Eine Nichtübereinstimmung gibt Code 100 zurück, formuliert so, wie Meta ein Objekt beschreibt, das Sie nicht sehen können:

Unsupported post request. Object with ID '…' does not exist, cannot be loaded due to missing permissions, or does not support this operation.

Dieser Wortlaut ist seitens Meta beabsichtigt und hier bewusst übernommen: Eine ID, die existiert, aber jemand anderem gehört, und eine ID, die überhaupt nicht existiert, müssen ununterscheidbar sein, da der Fehler andernfalls eine Möglichkeit bieten würde, die Telefonnummern anderer Personen herauszufinden.

Medien

Vier Endpunkte, die denen von Meta entsprechen.

MethodePfadFunktion
POST/{version}/{phone-number-id}/mediaEine Datei hochladen. Multipart, gibt {"id": "…"} zurück.
GET/{version}/{media-id}Metas Metadatenobjekt für die Datei.
GET/{version}/{media-id}/downloadDie Bytes.
DELETE/{version}/{media-id}Löschen, gibt {"success": true} zurück.
Eine Datei einmal hochladen und wiederholt sendenPOST /{v}/{pnid}/mediadie Datei selbst{ id }wiederverwendbarPOST /{v}/{pnid}/messagesauf die ID verweisenZugestelltStatusmeldungen treffen per Webhook ein
Der Upload gibt eine ID zurück. Diese ID fügen Sie in eine Nachricht ein.

Der eine bewusste Unterschied

GET /{version}/{media-id} gibt Metas Metadatenobjekt zurück — messaging_product, mime_type, sha256, file_size, id — aber die url verweist auf uns, nicht auf Metas Lookaside-Host.

Das muss sie auch. Metas Medien-URL kann nur mit dem Business-Token des WhatsApp-Kontos abgerufen werden, das auf unserer Seite liegt und diese niemals verlässt. Wir übergeben Ihnen daher eine URL, die Sie abrufen können: den oben genannten Download-Endpunkt, auf demselben Host und Versionssegment, das Sie aufgerufen haben, authentifiziert mit demselben Bearer-Token, das Sie bereits gesendet haben.

Clients behandeln diese URL als opak und rufen sie einfach per GET mit ihrem Token ab, weshalb ein unverändertes SDK davon nichts bemerkt. Wenn Ihr Code den Hostnamen als Sonderfall behandelt, ist dies die einzige Stelle, an der eine Änderung erforderlich sein wird.

Berechtigungen

Dieselben Berechtigungs-Chips wie bei der WizMessage API, auf denselben Schlüsseln. Woher die Berechtigung gelesen wird, hängt vom Aufruf ab: Der Sende-Endpunkt leitet sie aus dem Anfrage-Body ab, da Meta jeden Nachrichtentyp auf einen einzigen Pfad legt; überall sonst ergibt sie sich aus Pfad und Methode.

Senden und Medien:

AufrufBerechtigung
POST /{v}/{pnid}/messages mit "type": "template"send_template
dasselbe, type von image, video, audio, document oder stickersend_media
dasselbe, alles andere — text, interactive, reaction, location, contacts und Als-gelesen-Markierensend_text
POST /{v}/{pnid}/media — Uploadsend_media
DELETE /{v}/{media-id}send_media
GET /{v}/{media-id} und /downloadview_messages

Kontoverwaltung — siehe Konto verwalten:

AufrufBerechtigung
GET /{v}/{waba-id}/message_templatesview_templates
POST und DELETE /{v}/{waba-id}/message_templatesmanage_templates
GET /{v}/{waba-id}/template_analyticsview_analytics
GET auf Unternehmensprofil, QR-Codes, Commerce-Einstellungen, Blockierliste, Telefoneinstellungen und Flowsview_templates
POST auf dieselben sechsmanage_profile
DELETE /{v}/{pnid}/message_qrdls/{code} und DELETE /{v}/{pnid}/block_usersmanage_profile

Dies sind die einzigen beiden DELETE-Aufrufe auf der Verwaltungsseite. Für das Unternehmensprofil, die Commerce-Einstellungen, die Telefoneinstellungen oder Flows gibt es kein Löschen — ein DELETE auf eines davon wird mit code 100 abgelehnt, genau wie bei einem Endpunkt, der nicht existiert.

Hinweis: Der Medien-Upload erfordert hier send_media. Bei der WizMessage API ist überhaupt keine Berechtigung erforderlich, mit der Begründung, dass send_media das Senden einer Datei an einen Kunden regelt und nicht das Ablegen auf Metas Servern. Diese Schnittstelle vertritt die strengere Linie. Wenn Sie einen Schlüssel portieren und Uploads plötzlich 403 zurückgeben, ist dies der Grund dafür.

Hinweis: view_templates regelt weit mehr als nur Vorlagen. Das Lesen von Unternehmensprofil, QR-Codes, Commerce-Einstellungen, der Blockierliste, Telefoneinstellungen und Flows unterliegt allesamt dieser Berechtigung. Der Name ist historisch bedingt — er stammt aus einer Zeit vor allem, was in der zweiten Tabelle aufgeführt ist. Entfernen Sie das Häkchen beim Einschränken eines Schlüssels, geben sechs nicht damit zusammenhängende Leseaufrufe plötzlich 403 mit einer Meldung über Vorlagen zurück, was kein hilfreicher Hinweis ist.

Hinweis: Drei Chips gelten ausschließlich für Meta Graph. manage_templates, manage_profile und view_analytics regeln bei der WizMessage API nichts — sie existieren für die Endpunkte auf dieser Seite. Jedem bereits existierenden Schlüssel wurden alle drei gewährt, sodass nichts aufhörte zu funktionieren, was zuvor funktionierte; eine Einschränkung erfolgt durch bewusstes Abwählen im Bearbeitungsformular des Schlüssels.

Eine Ablehnung ist Graph-code 10 bei 403 — niemals unser PERMISSION_DENIED. Ein einziger Error-Handler deckt diese Schnittstelle vollständig ab.

Die Inhaberschaft wird vor der Berechtigung geprüft. Wenn die ID im Pfad nicht diejenige hinter Ihrem Schlüssel ist, lautet die Antwort code 100, und es wird niemals offengelegt, welche Berechtigung Ihnen fehlte — andernfalls würde der Fehler selbst zu einer Möglichkeit, fremde Konten auszuspähen.

Das Konto verwalten

Über das Senden hinaus stellt diese Schnittstelle Metas Kontoverwaltungs-Endpunkte unter Metas eigenen Pfaden bereit. Acht Ressourcen, und die Berechtigung, die Sie benötigen, hängt davon ab, ob Sie lesen oder schreiben.

Die Kontoverwaltungs-Endpunkte, gruppiert nach der jeweils erforderlichen BerechtigungAlles lesenalle acht RessourcenProfil, QR-Codes, CommerceSperrliste, Einstellungen, FlowsVorlagenview_templatesKonto schreibenProfil und PräsenzBusiness-Profil, QR-CodesCommerce, SperrlisteEinstellungen, Flowsmanage_profileVorlagen schreibenerstellen und löschenmessage_templatesAnalytik ist separatmanage_templatesVorlagen-Analytik hat einen eigenen Chip: view_analytics.
Lesen ist ein Chip. Schreiben teilt sich danach auf, was Sie schreiben.

Drei Dinge gelten für jeden Endpunkt in diesem Abschnitt, und sie sind der eigentliche Grund, warum dies überhaupt existieren kann:

  • Der Request-Body ist Metas eigener, unverändert und unvalidiert weitergeleitet. Wir dokumentieren Metas Bodys hier nicht noch einmal und wir prüfen sie nicht. Metas Referenz ist die Spezifikation, und Metas Fehler ist das, was zurückkommt, wenn Sie etwas falsch machen — was ein besserer Fehler ist als jeder, den wir erfinden könnten.
  • Ein Body wird nur bei POST gesendet. Ein an ein DELETE angehängter Body wird verworfen, bevor die Anfrage uns verlässt. Metas Löschen von Vorlagen nimmt ?name= oder ?hsm_id= als Query-Parameter entgegen, nicht als Body, funktioniert also wie dokumentiert; alles andere, was einen Delete-Body erwartet, wird nicht funktionieren.
  • Ihr Query-String wird weitergeleitet, abzüglich access_token und appsecret_proof. Diese beiden werden entfernt, da Meta ein Query-String-Token gegenüber dem Authorization-Header bevorzugt und sie durchzulassen Ihr Bearer-Token optional machen würde. Ein Client, der sich per Query-String authentifiziert, wird feststellen, dass dies stillschweigend ignoriert wird — verwenden Sie den Header.

Hinweis: Die WABA-ID und die Telefonnummern-ID in diesen Pfaden müssen diejenigen sein, die hinter Ihrem Schlüssel stehen. Das wird geprüft, bevor irgendetwas unser Netzwerk verlässt, und eine Nichtübereinstimmung führt zu demselben code 100, der unter Wenn eine ID nicht Ihnen gehört beschrieben wird.

Hinweis: paging.next verweist auf Meta, nicht auf uns. Antworten werden exakt so zurückgegeben, wie Meta sie gesendet hat; ein next-Link in einer paginierten Antwort ist daher eine graph.facebook.com-URL — und Ihr API-Schlüssel authentifiziert Sie dort nicht. Paginieren Sie, indem Sie paging.cursors.after entnehmen und die Anfrage mit ?after= erneut an diesen Host stellen.

Vorlagen

GET    https://wizmessage.com/v26.0/{waba-id}/message_templates?limit=25
POST   https://wizmessage.com/v26.0/{waba-id}/message_templates
DELETE https://wizmessage.com/v26.0/{waba-id}/message_templates?name=order_shipped
MethodeBerechtigungRückgabe
GETview_templatesMetas { data, paging }
POSTmanage_templatesMetas Erstellungsantwort
DELETEmanage_templatesMetas Löschantwort

GET akzeptiert limit (1–100, Standardwert 25) und after für Cursor-Paginierung.

Hinweis: GET akzeptiert nur limit und after. Metas sonstige Filter an diesem Edge — name, status, fields, language, category, name_or_content — werden stillschweigend verworfen, nicht abgelehnt. Eine Anfrage nach ?status=APPROVED gibt einen 200-Status zurück, der jede Vorlage enthält, genehmigt oder nicht. Filtern Sie auf Ihrer Seite, oder verwenden Sie after, um die vollständige Liste zu paginieren. Dies ist die einzige Stelle auf dieser Seite, an der ein portierter Client eine falsche Antwort statt eines Fehlers erhält; es lohnt sich also, Ihren Code daraufhin zu überprüfen.

Vorlagen-Analytik

GET https://wizmessage.com/v26.0/{waba-id}/template_analytics

Erfordert view_analytics. Meta verlangt start und antwortet ohne diesen Parameter mit code 100 — „(#100) The parameter start is required“. granularity und die restlichen Parameter stammen von Meta; leiten Sie diese durch, kommen sie unverändert an.

Business-Profil

GET  https://wizmessage.com/v26.0/{phone-number-id}/whatsapp_business_profile?fields=about,address,description,email,profile_picture_url,websites,vertical
POST https://wizmessage.com/v26.0/{phone-number-id}/whatsapp_business_profile

GET erfordert view_templates und gibt Metas { data } zurück. POST erfordert manage_profile.

QR-Codes

GET    https://wizmessage.com/v26.0/{phone-number-id}/message_qrdls
POST   https://wizmessage.com/v26.0/{phone-number-id}/message_qrdls
DELETE https://wizmessage.com/v26.0/{phone-number-id}/message_qrdls/{code}

GET erfordert view_templates und gibt Metas { data } zurück. POST und DELETE erfordern manage_profile.

Der Pfad /{code} ist ausschließlich für DELETE. Es gibt kein GET oder POST auf einen einzelnen Code — lesen Sie die Sammlung aus und wählen Sie daraus.

Commerce-Einstellungen

GET  https://wizmessage.com/v26.0/{phone-number-id}/whatsapp_commerce_settings
POST https://wizmessage.com/v26.0/{phone-number-id}/whatsapp_commerce_settings

GET erfordert view_templates und gibt Metas { data } zurück. POST erfordert manage_profile.

Blockierte Kunden

GET    https://wizmessage.com/v26.0/{phone-number-id}/block_users
POST   https://wizmessage.com/v26.0/{phone-number-id}/block_users
DELETE https://wizmessage.com/v26.0/{phone-number-id}/block_users

GET erfordert view_templates und gibt Metas { data } zurück. POST und DELETE erfordern manage_profile. Beachten Sie, dass das Aufheben einer Blockierung ein DELETE auf die Sammlung selbst ist, nicht auf einen Pfad pro Kunde.

Telefonnummern-Einstellungen

GET  https://wizmessage.com/v26.0/{phone-number-id}/settings
POST https://wizmessage.com/v26.0/{phone-number-id}/settings

GET erfordert view_templates und gibt { calling, storage_configuration } zurück. POST erfordert manage_profile.

Hinweis: Der Pfad lautet /settings. Einige API-Referenzen von Drittanbietern nennen dies whatsapp_calling_settings — dieser Pfad existiert bei Meta nicht und gibt hier code 2500 zurück, da wir ihn weiterleiten und Meta ihn ablehnt. Siehe Was hier nicht verfügbar ist.

Flows

GET  https://wizmessage.com/v26.0/{waba-id}/flows
POST https://wizmessage.com/v26.0/{waba-id}/flows

GET erfordert view_templates und gibt Metas { data, paging } zurück. POST erfordert manage_profile.

Was hier nicht verfügbar ist

Alles oben Genannte wurde an einem Live-WhatsApp-Konto bestätigt. Ebenso alles Nachfolgende – weshalb dieser Abschnitt Ihnen sagen kann, warum ein Endpunkt fehlt, und genau das entscheidet in der Regel darüber, was Sie als Nächstes tun.

Was ein nicht verfügbarer Endpunkt zurückgibt. Alles, was nicht auf der obigen Liste steht, antwortet mit Metas eigenem Wortlaut für einen Pfad, den Meta nicht bedient – code 100 bei 400:

Unsupported get request. Object with ID '…' does not exist, cannot be loaded due to missing permissions, or does not support this operation.

Ein Pfad, der zwar unterstützt wird, aber mit einer Methode aufgerufen wird, die er nicht anbietet, gibt denselben Code mit einer kürzeren Meldung zurück: „Unsupported delete request.“ Beide sind absichtlich nicht von einem Objekt zu unterscheiden, das Sie schlicht nicht sehen können – eine Fehlermeldung, die bestätigen würde, welche Endpunkte existieren, wäre eine Möglichkeit, die Oberfläche zu kartieren.

Warum ein Endpunkt auf dieser Oberfläche möglicherweise nicht verfügbar istein Endpunkt, der nicht hier istWir lehnen ihn abregistration, subscribed_appses würde Ihr Konto beschädigenkein WorkaroundMeta lehnt ihn abnicht auf einer Koexistenz-Nummerconversational_automation, callsMetas eigene AntwortEr existiert nichtvier Pfade aus API-MirrorsMeta antwortet mit Code 2500den echten Pfad verwendenEine vierte Gruppe steht schlicht noch nicht auf unserer Liste – siehe unten.
Vier Gründe, und nur einer davon liegt bei uns.

Absichtlich abgelehnt

Diese sind bei jeder Methode blockiert, noch bevor irgendetwas weitergeleitet wird:

PfadWarum
register, deregister, request_code, verify_codeEine Koexistenz-Nummer darf niemals bei der Cloud API registriert werden. Genau dadurch schlägt bei einem Konto jeder Sendeversuch mit dem Fehler 133010 fehl, und das lässt sich von Ihrer Seite aus nicht rückgängig machen.
subscribed_appsAlle Methoden, einschließlich GET. Ein DELETE an dieser Stelle würde unsere Webhooks von Ihrem eigenen WhatsApp-Konto abmelden und Ihre eigene Integration unbemerkt lahmlegen; wir bieten auch den Lesezugriff nicht an, anstatt einen Pfad offenzulassen, bei dem ein einziges Versehen genau das bewirkt.
marketing_messagesDer Marketingversand läuft über die Kampagnen-Werkzeuge des Dashboards, welche die Senderate pro Konto durchsetzen.
/{template-id}/unpauseMeta identifiziert die Vorlage anhand einer bloßen ID ohne Konto im Pfad, sodass wir nicht nachweisen können, dass die Vorlage Ihnen gehört, bevor wir die Aktion ausführen. Heben Sie die Pausierung über das Dashboard auf.
messages bei jeder Methode außer POSTDer Sendepfad enthält die Ratenbegrenzung und die Handhabung von Kontosperrungen. Nur POST wird weitergeleitet.

Nicht verfügbar auf einer Koexistenz-Nummer

Metas eigene Antworten, überprüft an einem Live-Konto am 10. August 2026:

PfadMetas Antwort
/{phone-number-id}/conversational_automationcode 100 – „Tried accessing nonexisting field“
/{phone-number-id}/callscode 100 – „Tried accessing nonexisting field“
/{phone-number-id}/groupscode 131000 bei einem 500

Dies sind Einschränkungen von Meta für Nummern, die in Koexistenz mit der WhatsApp-Business-App laufen, nicht unsere – wir leiten die Anfrage weiter und genau das kommt zurück. Meta erweitert die Verfügbarkeit von Zeit zu Zeit; wenn Ihnen also einer dieser Punkte wichtig ist, lohnt sich ein erneuter Test, anstatt dieser Tabelle dauerhaft zu vertrauen.

Pfade, die nirgendwo existieren

Jeder dieser Pfade taucht in API-Referenzen von Drittanbietern auf und ist kein Endpunkt von Meta. Alle vier geben code 2500 zurück, „Unknown path components“:

Was Sie möglicherweise gelesen habenWas Sie stattdessen verwenden sollten
POST /{phone-number-id}/mark_message_as_readPOST /{phone-number-id}/messages mit einem status: "read"-Body – siehe Eine Nachricht als gelesen markieren
GET /{phone-number-id}/message_statusZustellungsstatus gehen über Ihren Webhook ein; siehe Auswählen, was Sie empfangen
/{phone-number-id}/whatsapp_calling_settings/{phone-number-id}/settings
/{phone-number-id}/conversational_componentsNichts – der am nächsten liegende reale Pfad ist conversational_automation, der auf einer Koexistenz-Nummer nicht verfügbar ist

Bei Meta vorhanden, nicht auf unserer Liste

GET /{waba-id}/phone_numbers funktioniert bei Meta und wird hier weder blockiert noch weitergeleitet, sodass er mit code 100 antwortet. Es ist einer der ersten Endpunkte, die ein Cloud API-Client aufruft, daher ist er erwähnenswert: Ihr Schlüssel ist bereits an genau eine Telefonnummer gebunden, und deren ID ist diejenige, die Sie in jeden Pfad auf dieser Seite einsetzen. Sie können sie auf dem Tab „Overview“ des Schlüssels im Dashboard ablesen.

Reine Node-Abfragen

GET /{v}/{waba-id}?fields=… und GET /{v}/{phone-number-id}?fields=… funktionieren bei Meta, aber nicht hier. Ein Pfad mit nur einem Segment auf dieser Oberfläche ist eine Medien-ID – genau das bedeutet GET /{v}/{media-id} –, daher wird eine WABA-ID an dieser Stelle als Medium gesucht und schlägt fehl.

Der Fehler ist verwirrend, wenn Sie nicht damit rechnen: Es wird zuerst view_messages geprüft, sodass ein Schlüssel ohne diese Berechtigung einen 403 erhält, der eine Berechtigung nennt, die überhaupt nichts mit der eigentlichen Anfrage zu tun hat. Verwenden Sie stattdessen die Edge-Formen – /{waba-id}/message_templates, /{phone-number-id}/settings und den Rest von Das Konto verwalten.

Webhooks im Meta-Format

Der Webhook-Tab des Dashboards öffnet sich mit einem Payload-Format. WizMessage (v1) ist die Payload, die die andere Seite dokumentiert; sie wird von einem Schlüssel verwendet, bis Sie dies ändern.

Der Webhooks-Tab mit dem auf WizMessage eingestellten Payload-Format, der die Kontrollkästchen für v1-Ereignisse zeigt

Wählen Sie Meta Graph, und Ihr Endpunkt empfängt nicht mehr unsere {version, event, timestamp, data}-Payload, sondern den Umschlag, den Meta uns gesendet hat, wortgetreu weitergeleitet — eine Zustellung pro Änderung.

{
	"object": "whatsapp_business_account",
	"entry": [
		{
			"id": "102290129340398",
			"time": 1770000123,
			"changes": [
				{
					"value": {
						"messaging_product": "whatsapp",
						"metadata": {
							"display_phone_number": "15550783881",
							"phone_number_id": "106540352242922"
						},
						"contacts": [{ "profile": { "name": "Priya Sharma" }, "wa_id": "919876543210" }],
						"messages": [
							{
								"from": "919876543210",
								"id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAEhgg…",
								"timestamp": "1770000123",
								"type": "text",
								"text": { "body": "Has it shipped yet?" }
							}
						]
					},
					"field": "messages"
				}
			]
		}
	]
}

Wenn Sie bereits einen Webhook-Handler für die Cloud API haben, ist dies genau die Struktur, für die er geschrieben wurde.

Das Wechseln des Formats ändert auch, was der Tab von Ihnen abfragt: Die Ereignis-Kontrollkästchen werden durch Metas eigene Feldnamen ersetzt und ein Verify-Token erscheint.

Der Webhooks-Tab im Meta-Graph-Format, der das Verify-Token und die neun abonnierbaren Meta-Feldnamen zeigt

Bevor Sie einen speichern können

Drei Dinge sind erforderlich, und das Dashboard teilt Ihnen mit, was fehlt:

Was vorhanden sein muss, bevor ein Meta-Graph-Webhook gespeichert werden kannWebhook-Secretdient als Schlüssel für die SignaturVerify-Tokenbelegt, dass die URL Ihnen gehörtEine erreichbare URLwird vor dem Speichern aufgerufenGespeichertZustellungen beginnenEine URL, die noch nicht antwortet, kann nicht gespeichert werden. Zuerst bereitstellen, dann konfigurieren.
Alle drei werden beim Klick auf Speichern geprüft, und zwar in dieser Reihenfolge.
  • Ein Webhook-Secret. Es ist das Einzige, das als Schlüssel für X-Hub-Signature-256 dient; ohne dieses wäre eine Zustellung unsigniert und nicht verifizierbar. Erstellen Sie eines im Webhooks-Tab des Schlüssels.
  • Ein Verify-Token. Eine beliebige Zeichenfolge Ihrer Wahl; Ihr Endpunkt muss diese ebenfalls kennen.
  • Eine URL, die bereits antwortet. Siehe unten.

Der Verifizierungs-Handshake

Beim Speichern rufen wir Ihre URL genau so auf, wie Meta es tun würde:

GET https://your-server.example/webhooks
	?hub.mode=subscribe
	&hub.verify_token=<the token you set>
	&hub.challenge=482910337

Ihr Endpunkt muss prüfen, ob hub.verify_token mit dem übereinstimmt, was Sie konfiguriert haben, und dann mit 200 antworten, wobei hub.challenge der gesamte Antwort-Body ist — kein JSON-Wrapper, keine Anführungszeichen, nichts sonst. Die Challenge ist eine 9-stellige Zahl, sodass ein Handler, der vor der Rückgabe ein parseInt ausführt, sie unverändert zurücksendet.

Wenn die Challenge nicht exakt zurückgegeben wird, wird das Speichern verweigert und nichts gespeichert. Dies verhindert, dass jemand unsere Zustellungs-Warteschlange auf eine URL leitet, die er nicht kontrolliert.

// express
app.get('/webhooks', (req, res) => {
	if (req.query['hub.mode'] === 'subscribe' && req.query['hub.verify_token'] === VERIFY_TOKEN) {
		return res.status(200).send(req.query['hub.challenge'])
	}
	res.sendStatus(403)
})

Die Signatur verifizieren

Jede Zustellung enthält X-Hub-Signature-256, berechnet auf dieselbe Weise wie bei Meta: HMAC-SHA256 des rohen Request-Bodys, geschlüsselt mit Ihrem Webhook-Secret, hexadezimal, mit vorangestelltem sha256=.

HeaderWert
X-Hub-Signature-256sha256= + HMAC-SHA256 des rohen Bodys, geschlüsselt mit Ihrem Webhook-Secret, hexadezimal in Kleinbuchstaben.
X-Webhook-Eventmeta.<field> — welches Feld diese Zustellung überträgt.
X-Webhook-IdEindeutige ID für diesen Zustellungsversuch. Zur Deduplizierung verwenden.
User-Agentfacebookplatform/1.0 (+http://developers.facebook.com)

Hinweis: Dies ist nicht dieselbe Ableitung wie beim WizMessage-Format. Jenes signiert timestamp + "." + rawBody und sendet den Zeitstempel in einem eigenen Header; dieses signiert den Body allein, ganz ohne Zeitstempel. Wenn Sie beide Formate auf einem Server betreiben, halten Sie die beiden Verifizierer getrennt — ein gemeinsamer Handler schlägt bei dem Format fehl, für das er nicht geschrieben wurde.

Signieren Sie die Rohbytes genau so, wie sie empfangen wurden. Das Parsen des JSON und das erneute Serialisieren ändert die Reihenfolge der Schlüssel und die Abstände, sodass die Signatur niemals übereinstimmen wird.

const crypto = require('node:crypto')

// express: app.post('/webhooks', express.raw({ type: 'application/json' }), ...)
function verify(req) {
	const provided = req.get('X-Hub-Signature-256') || ''
	if (!provided.startsWith('sha256=')) return false

	const expected = crypto
		.createHmac('sha256', WEBHOOK_SECRET)
		.update(req.body) // the raw Buffer, not a parsed object
		.digest('hex')

	// Constant-time compare — a plain === leaks timing information.
	const a = Buffer.from(expected, 'hex')
	const b = Buffer.from(provided.slice('sha256='.length), 'hex')
	return a.length === b.length && crypto.timingSafeEqual(a, b)
}

Auswählen, was Sie empfangen

Beim WizMessage-Format haken Sie Ereignisse an. Bei diesem hier wählen Sie Metas Feldnamen aus, passend zu dem, was Sie im App Dashboard von Meta selbst abonnieren würden.

FeldWas ankommt
messagesEingehende Nachrichten und Zustellungsstatus. Lesen Sie den Hinweis unten.
message_statusZustellungsstatus als eigenes Feld.
smb_message_echoesNachrichten, die das Unternehmen über die WhatsApp Business App auf seinem Telefon gesendet hat.
smb_app_state_syncAuf diesem Telefon vorgenommene Adressbuch-Änderungen.
user_id_updateDie WhatsApp-Identität eines Kontakts hat sich geändert.
message_template_status_updateEine Vorlage wurde genehmigt, abgelehnt oder pausiert.
message_template_quality_updateDie Qualitätsbewertung einer Vorlage hat sich verändert.
account_updateDas WhatsApp-Konto wurde verbunden, getrennt, eingeschränkt oder entfernt.
historyVergangene Konversationen während der anfänglichen Synchronisierung. Große Payloads — aktivieren Sie dies nur, wenn Sie sie wirklich benötigen.

Neue Graph-Webhooks beginnen mit dem alleinigen Abonnement von messages. Das Abwählen aller Felder schaltet Zustellungen ab, ohne die Konfiguration zu löschen.

Hinweis: messages überträgt bereits Zustellungsstatus. Meta sendet beides unter "field": "messages" — eingehende Nachrichten in einem messages-Array, Zustellberichte in einem statuses-Array auf demselben Value-Objekt. Daher reicht das Standardabonnement völlig aus, um die wamid zuzuordnen, die Sie beim Senden zurückerhalten haben. message_status ist ein zusätzliches Feld und nicht dasjenige, das Sie für das einfache Status-Tracking benötigen. Lesen Sie value.statuses aus, bevor Sie annehmen, dass Ihnen ein Abonnement fehlt.

Drei Unterschiede zum WizMessage-Format

Lesenswert, wenn Sie eine bestehende Integration umstellen, da jede davon stillschweigend verändert, was bei Ihnen ankommt.

Drei Verhaltensweisen, die sich zwischen den beiden Webhook-Formaten unterscheidenKeine Chatbot-Schrankein jedem Fall zugestelltv1 benötigt Bot-Modus = WebhookGraph ignoriert diese EinstellungSie erhalten „sent“und Kampagnenstatusv1 filtert beides herausGraph leitet alles weiterKein synthetisches „sent“stattdessen Metas eigene Ereignissesmb_message_echoesund StatuswerteErwarten Sie beim Graph-Format mehr Datenverkehr, als dasselbe Konto unter v1 erzeugt hat.
Alle drei führen dazu, dass das Graph-Format mehr liefert, nicht weniger.
  • Die Zustellung ist nicht an das Chatbot-System gekoppelt. Beim WizMessage-Format erreichen eingehende Nachrichten Ihren Endpunkt nur, wenn das Chatbot-System des Kontos auf Webhook eingestellt ist. Das Graph-Format ignoriert diese Einstellung vollständig — eine URL zu konfigurieren und ein Feld zu abonnieren, ist bereits das gesamte Opt-in.
  • Sie erhalten status: "sent" und Kampagnenstatus. Das WizMessage-Format verwirft beides ganz bewusst. Hier erhalten Sie das, was Meta gesendet hat, was bei einem Konto mit Massenkampagnen zu spürbar mehr Status-Datenverkehr führt.
  • Es gibt kein künstliches message.sent. Das WizMessage-Format erzeugt ein solches für Nachrichten, die über die API, das Dashboard oder das Telefon gesendet werden. Meta deckt denselben Bereich mit smb_message_echoes und dem Status sent ab, daher wird hier nichts hinzuerfunden.

Zustellung, Wiederholungsversuche und Deaktivierung

Identisch mit dem WizMessage-Format — es gilt dieselbe Tabelle. Kurz gesagt: Wir warten 10 Sekunden, folgen niemals Weiterleitungen, versuchen 5xx/408/429/Timeouts fünfmal mit Backoff erneut, wiederholen andere 4xx niemals und behandeln 410 Gone als „diesen Webhook abschalten“.

Zustellungen erfolgen nach dem At-least-once-Prinzip (mindestens einmal). Deduplizieren Sie anhand von X-Webhook-Id und antworten Sie zügig mit 2xx.

Ausprobieren ohne Code zu schreiben

Der Dialog Test API des Schlüssels verfügt über ein Steuerelement API Format. Stellen Sie es auf Meta Graph, wird die Endpunktauswahl durch das tatsächliche Ziel für Ihr Konto ersetzt — POST /v26.0/{your phone number id}/messages — mit einem vorausgefüllten Body im Meta-Format.

Der Dialog „Test API“ im Modus „Meta Graph“, der den schreibgeschützten Messages-Endpunkt und einen Request-Body im Meta-Format zeigt

„Simulate Only“ gibt die Anfrage als Echo zurück, ohne Meta zu kontaktieren; der Wechsel zu „Send Real Message“ sendet sie ab und zeigt Ihnen Metas tatsächliche Antwort samt Fehler-Envelope und allem.

Der Dialog zielt auf POST /{phone-number-id}/messages ab und auf nichts anderes, daher sind die Endpunkte zur Kontoverwaltung darüber nicht erreichbar — probieren Sie diese mit curl oder Ihrem eigenen Client aus.

Get code enthält dasselbe Steuerelement, sodass das generierte Snippet auf die von Ihnen gewählte Oberfläche abzielt, in jeder der acht Sprachen. Lassen Sie „Require signature“ bei einem Schlüssel deaktiviert, den Sie hier verwenden möchten — wenn die Option aktiviert ist, signiert das generierte Graph-Snippet die Anfrage ebenfalls, was das Einzige ist, was ein unveränderter Cloud API-Client nicht tun kann.