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 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.
v26allein wird abgelehnt. Die Minor-Nummer ist nicht optional.v26.0ist in Ordnung,v26ist 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.
| Header | Wert |
|---|---|
Authorization | Bearer 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 190mit401abgelehnt. 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:
| Header | Wert |
|---|---|
X-Subscription-Warning | Subscription 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"
}
}
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-Warningist die einzige Vorwarnung, die es gibt — protokollieren Sie sie, sonst erfahren Sie erst durch einen403-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:
toakzeptiert 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.164und lehnt alles andere ab, während diese Schnittstelle Ihren Wert direkt an Meta weiterleitet. Die einzige Ausnahme istPOST /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.
Fehler, die wir auslösen
code | HTTP | Wann |
|---|---|---|
190 | 401 | Fehlender, 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. |
10 | 403 | Dem Schlüssel fehlt die Berechtigung, die dieser Aufruf benötigt (siehe Berechtigungen), oder das Abonnement des Kontos ist abgelaufen und über die Kulanzfrist hinaus. |
4 | 429 | Das Minuten- oder Tageskontingent des Schlüssels ist aufgebraucht. |
100 | 400 | Fehlerhafte Anfrage, eine ID im Pfad, die nicht Ihnen gehört, oder ein Endpunkt, den diese Schnittstelle nicht bereitstellt. |
2 | 500 | Auf unserer Seite ist ein Fehler aufgetreten. Versuchen Sie es erneut. |
Hinweis: Zwei verschiedene Dinge geben
190zurü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
typein diesem Beispiel —GraphMethodException, nichtOAuthException. Meta verwendet mehrere Ausnahmetypen und wir normalisieren sie nicht. Werten Sieerror.codeaus, was eine Zahl und stabil ist; behandeln Sietypeals 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.
| Methode | Pfad | Funktion |
|---|---|---|
POST | /{version}/{phone-number-id}/media | Eine Datei hochladen. Multipart, gibt {"id": "…"} zurück. |
GET | /{version}/{media-id} | Metas Metadatenobjekt für die Datei. |
GET | /{version}/{media-id}/download | Die Bytes. |
DELETE | /{version}/{media-id} | Löschen, gibt {"success": true} zurück. |
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:
| Aufruf | Berechtigung |
|---|---|
POST /{v}/{pnid}/messages mit "type": "template" | send_template |
dasselbe, type von image, video, audio, document oder sticker | send_media |
| dasselbe, alles andere — text, interactive, reaction, location, contacts und Als-gelesen-Markieren | send_text |
POST /{v}/{pnid}/media — Upload | send_media |
DELETE /{v}/{media-id} | send_media |
GET /{v}/{media-id} und /download | view_messages |
Kontoverwaltung — siehe Konto verwalten:
| Aufruf | Berechtigung |
|---|---|
GET /{v}/{waba-id}/message_templates | view_templates |
POST und DELETE /{v}/{waba-id}/message_templates | manage_templates |
GET /{v}/{waba-id}/template_analytics | view_analytics |
GET auf Unternehmensprofil, QR-Codes, Commerce-Einstellungen, Blockierliste, Telefoneinstellungen und Flows | view_templates |
POST auf dieselben sechs | manage_profile |
DELETE /{v}/{pnid}/message_qrdls/{code} und DELETE /{v}/{pnid}/block_users | manage_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, dasssend_mediadas 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ötzlich403zurückgeben, ist dies der Grund dafür.
Hinweis:
view_templatesregelt 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ötzlich403mit einer Meldung über Vorlagen zurück, was kein hilfreicher Hinweis ist.
Hinweis: Drei Chips gelten ausschließlich für Meta Graph.
manage_templates,manage_profileundview_analyticsregeln 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.
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
POSTgesendet. Ein an einDELETEangehä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_tokenundappsecret_proof. Diese beiden werden entfernt, da Meta ein Query-String-Token gegenüber demAuthorization-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.nextverweist auf Meta, nicht auf uns. Antworten werden exakt so zurückgegeben, wie Meta sie gesendet hat; einnext-Link in einer paginierten Antwort ist daher einegraph.facebook.com-URL — und Ihr API-Schlüssel authentifiziert Sie dort nicht. Paginieren Sie, indem Siepaging.cursors.afterentnehmen 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
| Methode | Berechtigung | Rückgabe |
|---|---|---|
GET | view_templates | Metas { data, paging } |
POST | manage_templates | Metas Erstellungsantwort |
DELETE | manage_templates | Metas Löschantwort |
GET akzeptiert limit (1–100, Standardwert 25) und after für Cursor-Paginierung.
Hinweis:
GETakzeptiert nurlimitundafter. Metas sonstige Filter an diesem Edge —name,status,fields,language,category,name_or_content— werden stillschweigend verworfen, nicht abgelehnt. Eine Anfrage nach?status=APPROVEDgibt einen200-Status zurück, der jede Vorlage enthält, genehmigt oder nicht. Filtern Sie auf Ihrer Seite, oder verwenden Sieafter, 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 dieswhatsapp_calling_settings— dieser Pfad existiert bei Meta nicht und gibt hiercode 2500zurü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.
Absichtlich abgelehnt
Diese sind bei jeder Methode blockiert, noch bevor irgendetwas weitergeleitet wird:
| Pfad | Warum |
|---|---|
register, deregister, request_code, verify_code | Eine 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_apps | Alle 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_messages | Der Marketingversand läuft über die Kampagnen-Werkzeuge des Dashboards, welche die Senderate pro Konto durchsetzen. |
/{template-id}/unpause | Meta 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 POST | Der 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:
| Pfad | Metas Antwort |
|---|---|
/{phone-number-id}/conversational_automation | code 100 – „Tried accessing nonexisting field“ |
/{phone-number-id}/calls | code 100 – „Tried accessing nonexisting field“ |
/{phone-number-id}/groups | code 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 haben | Was Sie stattdessen verwenden sollten |
|---|---|
POST /{phone-number-id}/mark_message_as_read | POST /{phone-number-id}/messages mit einem status: "read"-Body – siehe Eine Nachricht als gelesen markieren |
GET /{phone-number-id}/message_status | Zustellungsstatus 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_components | Nichts – 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.

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.

Bevor Sie einen speichern können
Drei Dinge sind erforderlich, und das Dashboard teilt Ihnen mit, was fehlt:
- Ein Webhook-Secret. Es ist das Einzige, das als Schlüssel für
X-Hub-Signature-256dient; 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=.
| Header | Wert |
|---|---|
X-Hub-Signature-256 | sha256= + HMAC-SHA256 des rohen Bodys, geschlüsselt mit Ihrem Webhook-Secret, hexadezimal in Kleinbuchstaben. |
X-Webhook-Event | meta.<field> — welches Feld diese Zustellung überträgt. |
X-Webhook-Id | Eindeutige ID für diesen Zustellungsversuch. Zur Deduplizierung verwenden. |
User-Agent | facebookplatform/1.0 (+http://developers.facebook.com) |
Hinweis: Dies ist nicht dieselbe Ableitung wie beim WizMessage-Format. Jenes signiert
timestamp + "." + rawBodyund 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.
| Feld | Was ankommt |
|---|---|
messages | Eingehende Nachrichten und Zustellungsstatus. Lesen Sie den Hinweis unten. |
message_status | Zustellungsstatus als eigenes Feld. |
smb_message_echoes | Nachrichten, die das Unternehmen über die WhatsApp Business App auf seinem Telefon gesendet hat. |
smb_app_state_sync | Auf diesem Telefon vorgenommene Adressbuch-Änderungen. |
user_id_update | Die WhatsApp-Identität eines Kontakts hat sich geändert. |
message_template_status_update | Eine Vorlage wurde genehmigt, abgelehnt oder pausiert. |
message_template_quality_update | Die Qualitätsbewertung einer Vorlage hat sich verändert. |
account_update | Das WhatsApp-Konto wurde verbunden, getrennt, eingeschränkt oder entfernt. |
history | Vergangene 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 einemmessages-Array, Zustellberichte in einemstatuses-Array auf demselben Value-Objekt. Daher reicht das Standardabonnement völlig aus, um diewamidzuzuordnen, die Sie beim Senden zurückerhalten haben.message_statusist ein zusätzliches Feld und nicht dasjenige, das Sie für das einfache Status-Tracking benötigen. Lesen Sievalue.statusesaus, 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.
- 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 mitsmb_message_echoesund dem Statussentab, 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.

„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.