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.

REST-API-Referenz

Alles bisher Beschriebene konfiguriert den Schlüssel. Das Folgende ist das, was Ihre Entwickler tatsächlich aufrufen. Die Basis-URL lautet /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://your-host/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.