Ihre Software mit WhatsApp verbinden

Über die API-Verwaltung versendet ein anderes System — Ihre Abrechnungssoftware, Ihr Onlineshop, Ihr eigenes Backend — WhatsApp-Nachrichten über WizMessage. Sie stellen ihm hier einen API-Schlüssel aus, legen fest, welche genehmigte WhatsApp-Vorlage es senden darf, und richten es auf einen Webhook aus, damit Antworten zurückkommen. Dieser Leitfaden führt durch den gesamten Weg und dokumentiert anschließend die REST-API, die Ihre Entwickler aufrufen werden.

Das Dashboard

Wo Ihre API-Schlüssel liegen

Jeder von Ihnen ausgestellte Schlüssel erscheint hier unter „API Keys“. Jede Zeile zeigt den Status des Schlüssels, sein öffentliches Präfix (der einzige Teil des Schlüssels, der nach dem Erstellen überhaupt noch einmal angezeigt wird) und wie viele Aufrufe er heute getätigt hat. „Manage“ öffnet den Schlüssel; der Schalter pausiert ihn, ohne ihn zu löschen.

1. ▶ Wo Ihre API-Schlüssel liegen
2. ▶ Ein Schlüssel, der noch nicht fertig ist

Ein Schlüssel, der noch nicht fertig ist

Ein Schlüssel ohne zugeordnete Vorlage trägt das Kennzeichen „Needs setup“. Er kann sich authentifizieren, aber keine Vorlagennachricht senden, solange Sie ihm keine zuordnen — eine halb konfigurierte Integration ist so auf einen Blick erkennbar, statt später beim Senden zu scheitern.

Geführte Einrichtung

Schritt 1 — Was möchten Sie verbinden?

„Connect your software“ öffnet einen Assistenten mit vier Schritten. Benennen Sie den Schlüssel zunächst nach dem System, das ihn verwenden wird, und wählen Sie die passende Vorgabe. Die Vorgaben schlagen lediglich sinnvolle Feldnamen vor — die Abrechnungsvorgabe schlägt invoice_number, amount, due_date und customer_name vor — sie schränken nicht ein, was Sie zuordnen können.

1. ▶ Schritt 1 — Was möchten Sie verbinden?
2. ▶ Schritt 2 — Nachricht auswählen
3. ▶ Schritt 3 — Wohin sollen Antworten gehen?
4. ▶ Schritt 4 — Live gehen

Schritt 2 — Nachricht auswählen

Wählen Sie eine Ihrer genehmigten WhatsApp-Vorlagen. Vorlagen liegen bei Meta, nicht hier — diese Liste wird live aus Ihrem verbundenen WhatsApp-Konto abgerufen, und nur GENEHMIGTE Vorlagen lassen sich senden. Dieser Schritt ist optional: Überspringen Sie ihn, wenn der Schlüssel ausschließlich reinen Text sendet, und ordnen Sie später eine Vorlage zu.

Schritt 3 — Wohin sollen Antworten gehen?

Wenn jemand auf Ihre Nachricht antwortet oder eine Zustellmeldung eintrifft, senden wir sie per POST an eine URL, die Sie kontrollieren. Lassen Sie dies aus, wenn Ihr System ausschließlich sendet. Sie können die URL später im Tab „Webhooks“ des Schlüssels ergänzen — nichts davon ist endgültig.

Schritt 4 — Live gehen

Erst der Klick auf „Next“ im vorherigen Schritt erstellt den Schlüssel tatsächlich — dieser Bildschirm ist die Bestätigung. Kopieren Sie jetzt alle drei Werte: Der API-Schlüssel, das API-Secret und das Webhook-Signaturgeheimnis werden genau einmal angezeigt und lassen sich danach nicht wiederherstellen. Verlieren Sie das Secret, müssen Sie es rotieren — und damit jedes System aktualisieren, das es verwendet hat.

Einen Schlüssel verwalten

Übersicht

Beim Öffnen eines Schlüssels landen Sie auf dem Tab „Overview“: was er darf, wie stark er genutzt wird und welche Endpunkte er aufrufen kann. Die Nutzungszahlen stammen aus dem Anfrageprotokoll und spiegeln daher echten Traffic wider.

1. ▶ Übersicht

Ein Schlüssel, der noch eingerichtet werden muss

Ein Schlüssel ohne zugeordnete Vorlage öffnet stattdessen den Tab „Setup“ — derselbe Assistent, direkt eingebettet. Beachten Sie, dass sich die Tabs vom vorherigen Screenshot unterscheiden: Solange ein Schlüssel nicht mindestens eine Vorlage hat, werden „Templates“ und „Webhooks“ nicht angeboten, weil es für sie noch nichts zu tun gibt.

1. ▶ Ein Schlüssel, der noch eingerichtet werden muss

Vorlagen

Im Tab „Templates“ steht jede Karte für eine Vorlage, die dieser Schlüssel senden darf. Der Fließtext ist die bei Meta genehmigte Nachricht, und die Chips darunter sind die Variablennamen, die Ihr System liefern wird. „Try it“ sendet einen Test, „Get code“ erzeugt eine fertige Anfrage in acht Programmiersprachen.

1. ▶ Vorlagen
2. ▶ Die Variablen richtig lesen — der eine Punkt, bei dem Sie innehalten sollten

Die Variablen richtig lesen — der eine Punkt, bei dem Sie innehalten sollten

Sehen Sie sich die Karte payment_failed_alert an. Ihre Nachricht enthält {{1}}, dann {{3}}, dann {{2}} — die Platzhalter stehen im Text NICHT in numerischer Reihenfolge. Die Chips darunter sind numerisch sortiert: customer_name füllt {{1}}, renewal_date füllt {{2}}, plan_name füllt {{3}}. Ordnen Sie Ihre Werte immer der NUMMER zu, niemals der Reihenfolge, in der die Platzhalter zufällig im Satz auftauchen. Genau hier passieren die meisten Fehler — besonders bei übersetzten Vorlagen, in denen die Wortstellung die Platzhalter verschiebt.

Die drei Schaltflächen auf jeder Vorlage

„Try it“ — einen Test senden, ohne Code zu schreiben

Die Papierflieger-Schaltfläche öffnet diese Vorlage vorbelegt mit Beispielwerten, einem je Variablenname. Das ist der schnellste Weg, eine Zuordnung zu prüfen, bevor Ihre Entwickler sie anfassen. Beachten Sie den Schalter: „Simulate Only“ ist die Voreinstellung, und nichts verlässt das Haus — der Server spiegelt Ihre Nutzlast einfach zurück. Stellen Sie ihn auf „Send Real Message“, geht eine echte WhatsApp-Nachricht an die Nummer im Feld — und wird berechnet.

1. ▶ „Try it“ — einen Test senden, ohne Code zu schreiben
2. ▶ Was eine simulierte Sendung zurückgibt
3. ▶ „Get code“ — die fertig geschriebene Anfrage
4. ▶ Die Sprache wechseln
5. ▶ „Edit“ — ändern, was Ihr System sendet
6. ▶ Test API — dasselbe Werkzeug, jeder Endpunkt
7. ▶ Webhooks — Antworten zurückerhalten

Was eine simulierte Sendung zurückgibt

Ein Klick auf „Send Request“ im Modus „Simulate Only“ liefert die Anfrage so zurück, wie die Plattform sie empfangen hat — mit HTTP-Status und Laufzeit. Verstehen Sie das als Formprüfung, nicht als Generalprobe: Es bestätigt, dass Ihr JSON geparst und der Schlüssel akzeptiert wurde, aber es prüft Ihre Variablennamen NICHT gegen die Zuordnung und kontaktiert Meta nie. Eine Nutzlast, die sauber simuliert, kann im Ernstfall trotzdem abgelehnt werden. Um die Zuordnung selbst zu belegen, schalten Sie „Send Real Message“ ein und senden an Ihr eigenes Telefon.

„Get code“ — die fertig geschriebene Anfrage

Die Schaltfläche mit den spitzen Klammern erzeugt eine funktionierende Anfrage für genau diese Vorlage in acht Sprachen: cURL, JavaScript, Node.js, Python, PHP, Ruby, Go und C#. Geben Sie sie an die Person weiter, die die Integration schreibt. Die Variablen erscheinen als {{placeholders}}, benannt nach Ihrer Zuordnung, und die Zugangsdaten bleiben als YOUR_API_KEY / YOUR_API_SECRET stehen — dieser Dialog gibt Ihren echten Schlüssel nie aus, das Snippet lässt sich also gefahrlos in ein Ticket einfügen.

Die Sprache wechseln

Klicken Sie oben auf eine beliebige Sprache, und das Snippet wird dafür neu geschrieben — derselbe Aufruf, dieselben Header, der HTTP-Client dieser Sprache. Jedes wird beim ersten Klick erzeugt, ein kurzer Spinner beim ersten Wechsel ist also normal. „Copy“ übernimmt das Snippet so, wie es dasteht: Es ist vollständig, inklusive Imports, und wenn dieser Schlüssel Signaturen verlangt, ist der Signaturschritt bereits enthalten.

„Edit“ — ändern, was Ihr System sendet

Der Stift öffnet die Zuordnung selbst. Die Handy-Vorschau oben ist die echte Nachricht mit Ihren aktuellen Namen eingesetzt, Sie sehen also, was der Kunde lesen wird. Darunter lässt sich jede erkannte Variable umbenennen, umsortieren, als Pflichtfeld markieren oder mit einem Typ versehen — ein Datum, ein Geldbetrag, ein Bild. Eine Variable umzubenennen benennt sie auch in Ihrer API-Nutzlast um, ein System, das den alten Namen bereits sendet, beginnt also zu scheitern: Ändern Sie beides gemeinsam.

Test API — dasselbe Werkzeug, jeder Endpunkt

„Test API“ oben im Tab ist „Try it“ ohne die Vorlagenbindung: Wählen Sie einen der drei Sende-Endpunkte, wechseln Sie die Vorlage über das zweite Auswahlfeld und bearbeiten Sie den Rumpf frei. Nutzen Sie es, um die rohen Aufrufe /messages/text oder /messages/template zu prüfen, die keine eigene Karte haben, weil sie an keine Zuordnung gebunden sind. Beachten Sie, dass die Variablen dieser Vorlage noch body_1, body_2, body_3 heißen — so sieht eine nicht zugeordnete Vorlage aus, und genau dafür gibt es „Edit“.

Antworten

Webhooks — Antworten zurückerhalten

Senden ist nur die halbe Integration. Richten Sie einen Webhook auf Ihren eigenen HTTPS-Endpunkt, und WizMessage sendet eingehende Nachrichten und Zustellaktualisierungen per POST dorthin. Das Signaturgeheimnis wird bei der Erzeugung einmalig angezeigt; prüfen Sie es bei jeder Zustellung, damit Sie sicher sein können, dass der Aufruf wirklich von uns stammt.

Welche Ereignisse Sie erhalten

Wählen Sie aus, welche Ereignisse dieser Endpunkt erhalten soll. Jedes kommt als eigener POST an.

Hinweis: message.received und eingehende message.reaction werden nur zugestellt, wenn das Chatbot-System des Kontos auf Webhook steht. Steht es auf etwas anderes, gehen eingehende Nachrichten stattdessen an den Bot und Ihr Endpunkt wird nie aufgerufen — der Webhooks-Tab warnt Sie in diesem Fall. Reaktionen, die das Unternehmen selbst sendet (direction: "outbound"), sind von dieser Einstellung nicht betroffen.

Hinweis: Reaktionen, die das Unternehmen von seinem eigenen Telefon sendet, kamen früher als message.sent mit dem Body "[Unsupported message type]" an. Sie kommen jetzt als message.reaction mit direction: "outbound" an. Haken Sie das neue Ereignis an, falls Sie sich darauf verlassen haben.

Zustellungen erfolgen mindestens einmal (at-least-once). Entfernen Sie Duplikate anhand von event zusammen mit data.message_id statt allein anhand des Headers X-Webhook-Id, und antworten Sie zügig mit 2xx.

REST-API-Referenz

Alles bisher Beschriebene konfiguriert den Schlüssel. Das Folgende ist das, was Ihre Entwickler tatsächlich aufrufen. Die Basis-URL lautet https://wizmessage.com/api/v1/external. Jeder Endpunkt erfordert die untenstehenden Authentifizierungs-Header und unterliegt den Ratenbegrenzungen des Schlüssels.

Authentifizierung

Senden Sie Ihren API-Schlüssel bei jeder Anfrage. Ist für den Schlüssel „Require signature“ aktiviert, müssen Sie die Anfrage zusätzlich signieren — und ein Schlüssel mit dieser Einstellung weist jeden unsignierten Aufruf rundweg ab.

Hinweis: Signaturen werden nur erzwungen, wenn für den Schlüssel require_signature aktiviert ist. Ist das nicht der Fall, genügt der API-Schlüssel allein zum Senden von Nachrichten — genau deshalb ist der Schlüssel ein Geheimnis und keine Kennung. Behandeln Sie ihn wie ein Passwort: Er wird einmal angezeigt, und wer ihn besitzt, kann Ihre Kunden anschreiben.

const crypto = require('node:crypto')

const body = JSON.stringify({ to: '+919876543210', message: 'Hello' })
const timestamp = Math.floor(Date.now() / 1000).toString()

const secretHash = crypto.createHash('sha256').update(API_SECRET).digest('hex')
const signature = crypto.createHmac('sha256', secretHash)
	.update(timestamp + '.' + body)
	.digest('hex')

await fetch('https://wizmessage.com/api/v1/external/messages/text', {
	method: 'POST',
	headers: {
		'Content-Type': 'application/json',
		'X-API-Key': API_KEY,
		'X-Timestamp': timestamp,
		'X-API-Signature': signature,
	},
	body,
})

Endpunkte

Eine zugeordnete Vorlage senden

Dies ist die Nutzlast, die zum Tab „Templates“ gehört. Sie senden Variablen über den NAMEN — die Namen, die als Chips auf der Vorlagenkarte stehen — und die Plattform setzt Metas Komponenten für Sie zusammen. Genau darum geht es beim Zuordnen einer Vorlage: Ihre Abrechnungssoftware muss nichts über Metas Komponentenformat wissen.

POST /api/v1/external/messages/template/send

{
	"to": "+919876543210",
	"template_name": "payment_failed_alert",
	"language": "en",
	"variables": {
		"customer_name": "Priya Sharma",
		"renewal_date": "12 Aug 2026",
		"plan_name": "Wiz Pro"
	},
	"reference": "invoice-2026-0817"
}

Hinweis: Die Variablennamen müssen exakt mit der Zuordnung übereinstimmen — ein unbekannter Name wird ignoriert, ein fehlender Pflichtname mit einem 400 abgelehnt. reference gehört Ihnen: Der Wert wird über Webhooks zurückgespiegelt, sodass Sie eine Zustellmeldung einem Datensatz in Ihrem eigenen System zuordnen können.

Ratenbegrenzungen

Jeder Schlüssel hat eigene Grenzwerte, die im Tab „Overview“ sichtbar sind — standardmäßig 60 Anfragen/Minute und 1.000 Nachrichten/Tag. Die Antworten enthalten das verbleibende Kontingent; drosseln Sie also, wenn es zur Neige geht, statt blind weiterzuprobieren, bis nichts mehr geht.

Dateien über die API senden

Innerhalb eines offenen 24-Stunden-Fensters kann Ihre Software eine Datei direkt senden — ohne Vorlage, ohne Freigabe. Ein Endpunkt deckt Dokumente, Bilder, Video und Audio ab.

Was Sie senden können

Der im Request genannte Typ bestimmt die Grenzen. Größeres oder ein nicht gelistetes Format wird abgewiesen, bevor es WhatsApp erreicht.

POST /api/v1/external/messages/media

{
	"to": "+919876543210",
	"type": "document",
	"link": "https://example.com/invoice-2026-0817.pdf",
	"filename": "Invoice 2026-0817.pdf",
	"caption": "Your invoice for August",
	"reference": "invoice-2026-0817"
}

Einmal hochladen, oft senden

Wenn Sie dieselbe Datei wiederholt senden — Preisliste, Katalog, AGB-PDF — laden Sie sie einmal hoch und behalten Sie die ID. Sie bleibt 30 Tage gültig und erspart WhatsApp das erneute Abrufen Ihrer URL bei jeder Nachricht.

POST /api/v1/external/messages/media

{
	"to": "+919876543210",
	"type": "image",
	"media_id": "1234567890",
	"caption": "This month’s catalogue"
}

Wann ein Versand abgelehnt wird

• Außerhalb des 24-Stunden-Fensters. Freie Medien brauchen eine offene Konversation. Senden Sie stattdessen eine freigegebene Vorlage — siehe den Leitfaden zum gemeinsamen Posteingang.
• Dem Schlüssel fehlt send_media. Prüfen Sie die Berechtigungs-Chips im Overview-Tab.
• Bildunterschrift bei Audio. WhatsApp zeigt keine an, daher wird sie abgelehnt statt still verworfen.
• Dateiname bei etwas anderem als einem Dokument. Nur Dokumente zeigen einen Namen.
• Weder media_id noch link. Genau eines ist erforderlich.

Hinweis: Sie können all das ohne Code ausprobieren. Öffnen Sie den Schlüssel, drücken Sie Test API und wählen Sie POST /messages/media aus der Endpunktliste — der Body ist vorbelegt, und „Get code“ schreibt denselben Request in acht Sprachen.

Reaktionen

Eine Reaktion ist das Emoji, das jemand auf eine einzelne Nachricht tippt — 👍 auf eine Bestellbestätigung, ❤️ auf ein Foto. Sie ist keine eigene Nachricht: sie verweist auf eine. Ihre Software kann Reaktionen mitlesen, sobald sie passieren, und selbst welche senden.

Ein Ereignis, drei Ursprünge

Eine Reaktion kann von Ihrem Kunden kommen, davon, dass der Inhaber sie auf dem Telefon der Business-App antippt, oder von Ihrer eigenen Software über die API. Alle drei kommen über dasselbe Ereignis message.reaction an, sodass ein einziger Handler jeden Fall abdeckt — direction und source sagen Ihnen, welchen Sie vor sich haben.

Wie ein Reaktions-Webhook aussieht

Hier fügt ein Kunde 👍 zu einer Nachricht hinzu, die Sie ihm gesendet haben.

{
	"version": 1,
	"event": "message.reaction",
	"timestamp": "2026-08-01T09:14:22.031Z",
	"data": {
		"message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSQjkz…",
		"direction": "inbound",
		"from": "+919876543210",
		"to": "+911122334455",
		"reaction": {
			"message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgUQ0Uz…",
			"emoji": "👍",
			"action": "added"
		},
		"contact": {
			"name": "Priya Sharma",
			"wa_id": "919876543210"
		}
	}
}

In diesem Payload stehen zwei message_ids, und sie bedeuten nicht dasselbe. Das ist das eine Feld, das ein zweites Lesen verdient.

Hinweis: data.from ist normalerweise die Telefonnummer des Kunden, aber WhatsApp sendet nicht immer eine. Wenn nicht, erhalten Sie stattdessen dessen WhatsApp-Benutzer-ID — behandeln Sie from also als Kennung, nicht als etwas, das Sie immer anrufen können.

Eine Reaktion hinzufügen und entfernen

Das Entfernen einer Reaktion ist ein eigenes Ereignis, mit leerem emoji und action: "removed".

{
	"event": "message.reaction",
	"data": {
		"message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSN0U3…",
		"direction": "inbound",
		"reaction": {
			"message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgUQ0Uz…",
			"emoji": "",
			"action": "removed"
		}
	}
}

Jedes Antippen ist eine eigene WhatsApp-Nachricht mit eigener ID. Mit 👍 reagieren, es auf ❤️ ändern und dann ganz entfernen ergibt drei Ereignisse, von denen keines die anderen in Ihrem Speicher ersetzt. Schlüsseln Sie auf data.reaction.message_id und behalten Sie das jeweils neueste — das ist die aktuelle Reaktion der Nachricht.

Eine Reaktion aus Ihrer Software senden

Derselbe Endpunkt fügt hinzu und entfernt. Was davon geschieht, hängt allein davon ab, ob Sie ein Emoji senden.

POST /api/v1/external/messages/reaction

{
	"to": "+919876543210",
	"message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgUQ0Uz…",
	"emoji": "👍",
	"reference": "invoice-2026-0817"
}

Die message_id ist hier WhatsApps ID — die whatsapp_message_id aus einer Sendeantwort oder die data.reaction.message_id aus einem Webhook. Es ist nie eine unserer UUIDs. Reaktionen nutzen die Berechtigung send_text, jeder Schlüssel, der dem Kunden schreiben darf, kann also reagieren.

Hinweis: Eine Reaktion erzeugt nie message.delivered oder message.read. WhatsApp sendet diese für eine Reaktion nicht — das einzig mögliche Folgeereignis ist message.failed, wenn die Reaktion abgelehnt wird. Ein Abruf über GET /messages/:uuid funktioniert wie bei jedem anderen Versand.

Wann eine Reaktion abgelehnt wird

Manche Ablehnungen passieren hier, bevor irgendetwas WhatsApp erreicht. Diese geben Ihrem API-Aufruf einen Fehler zurück und erzeugen überhaupt keinen Webhook — es gibt nichts zu melden, weil nichts gesendet wurde.

• Dem Schlüssel fehlt send_text. 403. Reaktionen nutzen diese Berechtigung mit; es gibt keine eigene zu vergeben.
• to ist nicht E.164. 422. Dasselbe +…-Format wie bei jedem anderen Endpunkt.
• message_id fehlt oder ist leer. 422. Bis zu 255 Zeichen.
• emoji fehlt. 422. Zum Entfernen einer Reaktion senden Sie "emoji": "" — senden Sie das Feld leer, lassen Sie es nicht weg. Bis zu 16 Zeichen.

Die übrigen passieren bei WhatsApp, nachdem wir den Aufruf angenommen haben. Sie erhalten zuerst ein 200 und einen message.reaction-Webhook, dann ein message.failed mit dem Fehler 131009, sobald WhatsApp die Reaktion ablehnt.

• Die Nachricht ist älter als 30 Tage. WhatsApps Grenze für Reaktionen, nicht unsere — wir prüfen das Alter nicht.
• Die Nachricht gehört nicht zu dieser Konversation. Eine wamid aus einem anderen Chat oder versehentlich eine unserer UUIDs.
• Die Nachricht wurde gelöscht oder ist selbst eine Reaktion. Auf eine Reaktion kann man nicht reagieren.

Hinweis: Schlägt der Versand direkt fehl, statt später abgelehnt zu werden, erhalten Sie ein 500 und ein message.failed, dessen data.message_id unsere UUID ist, keine wamid — es gibt keine WhatsApp-ID zu melden, weil WhatsApp sie nie angenommen hat.

Hinweis: Wie bei jedem anderen Endpunkt können Sie das ohne Code ausprobieren. Öffnen Sie den Schlüssel, drücken Sie Test API und wählen Sie POST /messages/reaction — reagieren Sie auf eine Nachricht auf Ihrem eigenen Telefon und sehen Sie den Webhook eintreffen.