API-Schlüssel und Client-ID

Mit einem API-Schlüssel können Ihre eigene Software und Tools wie Zapier, n8n, Make und das WordPress-Plugin WhatsApp-Nachrichten von den Nummern Ihres Arbeitsbereichs senden. Ihr eigener Code sendet den Schlüssel in einem Header Authorization: Bearer; Integrationen fragen nach zwei Werten von der Seite API-Schlüssel: der Client-ID Ihres Arbeitsbereichs und einem seiner Schlüssel. Auf derselben Seite finden Sie das Secret, mit dem wir unsere Webhooks signieren.

Wer darf das: nur Inhaber – jeder Inhaber des Arbeitsbereichs, nicht nur sein Ersteller. Inhaber sehen, erstellen, kopieren und löschen alle Schlüssel des Arbeitsbereichs, egal wer sie erstellt hat. Bearbeiter und Analysten sehen API-Schlüssel weder in der Seitenleiste noch auf der Seite Einstellungen, und ein Link dorthin öffnet für sie Profil (siehe Rollen und Berechtigungen). Schlüssel funktionieren in jedem Plan, auch in der kostenlosen Testphase; was Sie damit senden, verbraucht die Nachrichten des Arbeitsbereichs.

Öffnen Sie in der Seitenleiste unter Integrationen den Punkt API-Schlüssel oder rufen Sie Einstellungen → API-Schlüssel auf.

Jeder Schlüssel zeigt seinen Namen, wann er erstellt wurde (Erstellt am), die letzten vier Zeichen des Schlüssels (zum Beispiel •••• 7f3a), Schlüssel kopieren und Löschen. Der neueste Schlüssel steht oben.

API-Schlüssel erstellen#

1. Auf Schlüssel erstellen klicken

   Klicken Sie unter Einstellungen → API-Schlüssel oben rechts auf der Karte auf Schlüssel erstellen.

2. Namen vergeben (optional)

   Geben Sie unter Name (optional) die App ein, die ihn nutzen wird, zum Beispiel n8n oder Website (bis zu 50 Zeichen). Bleibt das Feld leer, erhält er einen Namen wie „API Key 3“, wie der Hinweis unter dem Feld sagt.

3. Erstellen

   Klicken Sie auf Schlüssel erstellen.

   

4. Schlüssel kopieren

   Ihr neuer API-Schlüssel zeigt den vollständigen Schlüssel: „Kopieren Sie ihn jetzt – den vollständigen Schlüssel sehen Sie nicht noch einmal. Später kopiert „Schlüssel kopieren“ ihn, ohne ihn anzuzeigen.“ Klicken Sie auf Kopieren („Schlüssel kopiert.“), fügen Sie den Schlüssel in Ihre App oder Integration ein und klicken Sie dann auf Fertig.

   

• Bis zu 10 Schlüssel pro Arbeitsbereich. Bei 10 ist Schlüssel erstellen ausgegraut, und wenn Sie mit der Maus darauf zeigen, erscheint „Sie können bis zu 10 API-Schlüssel haben. Löschen Sie einen, um einen neuen zu erstellen.“
• Schlüssel laufen nicht ab, und sie lassen sich weder umbenennen noch abschalten: Ein Schlüssel funktioniert, bis er gelöscht wird.
• Ein Schlüssel pro App. Benennen Sie jeden Schlüssel nach der App, die ihn nutzt, damit Sie einen ersetzen oder löschen können, ohne die anderen lahmzulegen.
• Welcher Arbeitsbereich: Ein Schlüssel gehört zu dem Arbeitsbereich, der beim Erstellen ausgewählt war, und jede Anfrage damit wirkt auf diesen Arbeitsbereich: seine Nummern, Nachrichten und seinen Plan. Um aus einem anderen Arbeitsbereich zu senden, wechseln Sie zu ihm und erstellen Sie dort einen Schlüssel.

Was Sie in Ihrer App eintragen#

Wohin sie gehören:

• Ihr eigener Code: in einem Header Authorization: Bearer YOUR_API_KEY bei jeder Anfrage (empfohlen). Der Schlüssel benennt seinen Arbeitsbereich, deshalb kann client_id entfallen; wenn Sie sie senden, muss es weiterhin die dieses Arbeitsbereichs sein. Siehe Schlüssel im Header senden und Nachricht senden für eine erste Nachricht in cURL, Python, Node.js und PHP.
• Zapier: Client-ID und API-Schlüssel, wenn Sie Ihr Konto verbinden.
• n8n: Client ID, API Key und WhatsApp Client ID der WbizTool-Zugangsdaten (Credential).
• Make, Pabbly Connect und andere Tools: der Body einer HTTP-Anfrage.
• WordPress: WbizTool → Settings, unter API Configuration.

Google Sheets und Shopify werden im Dashboard eingerichtet und brauchen keinen Schlüssel.

Schlüssel im Header senden#

Jeder /api/v1/-Endpoint nimmt den Schlüssel in einem Authorization-Header an, so wie es die kommende API v2 tun wird:

Authorization: Bearer YOUR_API_KEY

• client_id ist optional mit dem Header: Der Schlüssel bestimmt den Arbeitsbereich. Wenn Sie zusätzlich client_id senden, muss es wie bisher die Client-ID dieses Arbeitsbereichs sein.
• Senden Sie den Schlüssel nur an einer Stelle. Lassen Sie mit dem Header api_key im Body weg oder senden Sie denselben Schlüssel. Wenn sie sich unterscheiden, wird der Schlüssel aus dem Header verwendet, sofern er gültig ist; steht im Header etwas anderes (etwa das Token eines anderen Tools), wird der api_key aus dem Body verwendet.
• Schlüssel im Body funktionieren weiterhin (client_id und api_key als JSON- oder Formularfelder), für Apps und Integrationen, die sie so senden, ändert sich also nichts. Der Header ist besser, weil Request-Bodys häufiger als Header in Logs, Proxys und den Verläufen von Formular-Buildern landen.
• Formularfelder, Multipart-Uploads und JSON-Bodys funktionieren alle mit dem Header.

curl -X POST https://wbiztool.com/api/v1/send_msg/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"whatsapp_client": 101, "phone": "919876543210", "msg": "Hello from WbizTool"}'

Schlüssel testen#

Rufen Sie Zugangsdaten prüfen (POST /api/v1/me/) mit Ihrem Schlüssel und, wenn Sie möchten, einem whatsapp_client auf. "status": 1 mit "message": "Okay" bedeutet, dass sie zusammenpassen. Der Aufruf sendet nichts und verbraucht keine Nachrichten, prüft aber nicht, ob Sie noch Nachrichten übrig haben oder ob die Nummer verbunden ist.

curl -X POST https://wbiztool.com/api/v1/me/ -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" -d '{"whatsapp_client": 101}'

Ein funktionierender Schlüssel antwortet mit {"status": 1, "message": "Okay", "name": "…"}.

Schlüssel erneut kopieren#

Klicken Sie neben dem Schlüssel auf Schlüssel kopieren. Der vollständige Schlüssel landet in Ihrer Zwischenablage, ohne auf der Seite angezeigt zu werden; Sie sehen zum Beispiel „„Zapier“ kopiert.“, und die Schaltfläche zeigt kurz Kopiert ✓. Sie brauchen also keinen neuen Schlüssel, nur weil Sie den alten verloren haben.

Um herauszufinden, welchen Schlüssel eine App nutzt, vergleichen Sie die letzten vier Zeichen ihres Schlüssels mit der Liste.

Schlüssel löschen#

1. Auf Löschen klicken

   Klicken Sie neben dem Schlüssel auf Löschen.

2. Bestätigen

   Der Dialog „„…“ löschen?“ warnt: „Alles, was diesen Schlüssel nutzt, funktioniert sofort nicht mehr: Zaps in Zapier, n8n- und Make-Szenarien, das WordPress-Plugin und Ihre eigenen API-Aufrufe. Geben Sie ihnen vorher einen anderen Schlüssel. Dies kann nicht rückgängig gemacht werden.“ Klicken Sie auf Schlüssel löschen. Sie sehen „„…“ gelöscht.“

Ab dann erhalten Anfragen mit diesem Schlüssel Auth Error: invalid api key. Was er vorher angestoßen hat, bleibt: Nachrichten, die damit in die Warteschlange kamen, werden trotzdem gesendet (brechen Sie sie bei Bedarf unter Berichte ab), und Erinnerungen, die damit erstellt wurden, laufen weiter. Auch ein damit eingerichteter Zapier-Trigger Incoming WhatsApp Message empfängt weiter Nachrichten, weil sein Webhook schon auf der Nummer liegt: Schalten Sie den Zap in Zapier aus, um ihn zu stoppen.

Schlüssel ersetzen#

Ersetzen Sie einen Schlüssel, wenn er offengelegt worden sein könnte, wenn jemand geht, der ihn kopieren konnte, oder von Zeit zu Zeit. Eine Schaltfläche zum Rotieren gibt es nicht: Erstellen Sie zuerst den neuen Schlüssel, damit zwischendurch nichts stillsteht.

1. Neuen Schlüssel erstellen

   Erstellen Sie einen Schlüssel und kopieren Sie ihn. Bei 10 Schlüsseln löschen Sie zuerst einen, den Sie nicht mehr verwenden.

2. Ihre Apps aktualisieren

   Fügen Sie den neuen Schlüssel in jede App und Integration ein, die den alten genutzt hat, und prüfen Sie jede davon, zum Beispiel mit Zugangsdaten prüfen.

3. Alten Schlüssel löschen

   Löschen Sie ihn. Er funktioniert sofort nicht mehr.

4. Auf Missbrauch prüfen (nach einem Leck)

   Suchen Sie unter Berichte nach Nachrichten, die Sie nicht gesendet haben, und brechen Sie alle noch wartenden ab. Löschen Sie unter Erinnerungen Erinnerungen, die Sie nicht erstellt haben, denn sie laufen weiter. Entfernen Sie unter WhatsApp-Nummern Nummern, die Sie nicht hinzugefügt haben. Mit dem Unibox-Add-on suchen Sie unter Posteingangsnummern nach einem Zapier-Badge oder einem Webhook, den Sie nicht kennen.

Schlüssel sicher aufbewahren#

Ein Schlüssel hat keine eigenen Berechtigungen: Wer einen hat, kann in Ihrem Arbeitsbereich alles tun, was die API kann, unabhängig von seiner Rolle. Dazu gehört, Nachrichten von jeder seiner Nummern zu senden (mit seinen Nachrichten), seinen Nachrichtenverlauf zu lesen, wartende Nachrichten abzubrechen, Erinnerungen und Mediendateien zu verwalten, Nummern zu prüfen und neue zu verbinden.

• Bewahren Sie Schlüssel auf Ihrem Server auf, in einer Umgebungsvariablen oder im Zugangsdatenspeicher Ihrer Integration. Legen Sie nie einen in das JavaScript einer Website, eine mobile App, eine geteilte Tabelle oder Code, den Sie veröffentlichen.
• Senden Sie Schlüssel nicht per E-Mail oder Chat. Fügen Sie sie direkt in die App ein, die sie braucht.
• Nutzen Sie einen Schlüssel pro App und löschen Sie Schlüssel, die Sie nicht mehr verwenden.
• Ersetzen Sie Schlüssel von Zeit zu Zeit und sofort, wenn einer offengelegt worden sein könnte.

Die Client-ID allein ist kein Geheimnis, aber behandeln Sie jeden Schlüssel wie ein Passwort.

API-v2-Schlüssel#

API v2 hat eigene Schlüssel, die Sie in der Karte API-v2-Schlüssel auf demselben Tab erstellen. Sie sind sicherer als die Schlüssel oben:

• Nur einmal angezeigt. Der vollständige Schlüssel (wbz_live_…) wird nur beim Erstellen angezeigt; WbizTool speichert nur einen Fingerabdruck. Wenn Sie ihn verlieren, widerrufen Sie ihn und erstellen Sie einen neuen.
• Nur, was er braucht. Haken Sie an, was der Schlüssel darf (Nachrichten senden, Nachrichten lesen, Erinnerungen, Nummern, Medien, Nummernprüfungen), beschränken Sie ihn auf einige Ihrer Nummern und geben Sie ihm bei Bedarf ein Ablaufdatum.
• Testschlüssel. Ein Testschlüssel (wbz_test_…) prüft jeden Request wie ein Live-Schlüssel, sendet aber nichts – zum Entwickeln und Ausprobieren einer Integration.
• Zuletzt verwendet. Bei jedem Schlüssel steht, wann und von wo er zuletzt verwendet wurde. Widerrufen sperrt ihn sofort, ebenso die Webhook-Endpunkte, die damit eingerichtet wurden.

Die Schlüssel oben funktionieren nur mit API v1, API-v2-Schlüssel nur mit v2. Siehe Von v1 zu v2 wechseln.

Webhook-Signaturen#

WbizTool signiert jeden Webhook, den es Ihnen sendet, damit Ihr Endpoint prüfen kann, dass eine Anfrage wirklich von uns stammt und unterwegs nicht verändert wurde: den Nachrichtenstatus-Webhook (gesendet, fehlgeschlagen, storniert, abgelaufen), die Ereignisse zur Nummernverbindung und die Posteingangs-Webhooks. Die Bodys bleiben wie bisher; zwei Header kommen hinzu:

Die Signatur deckt genau die Bytes ab, die wir senden: Formularfelder so, wie sie ankommen, den ganzen Multipart-Body, wenn ein QR-Code-Bild angehängt ist, und das JSON der Posteingangs-Webhooks. Empfänger, die die Header ignorieren, funktionieren weiter.

Signatur-Secret abrufen#

Unter Einstellungen → API-Schlüssel zeigt die Karte Webhook-Signatur-Secret unter Ihren Schlüsseln die letzten vier Zeichen des Secrets, etwa •••• b70d. Jeder Arbeitsbereich hat ein Secret für alle seine Webhooks; es wird mit dem ersten Webhook erstellt, den wir Ihnen senden.

1. Klicken Sie auf Neues Secret anzeigen

   Klicken Sie auf Neues Secret anzeigen (oder auf Secret erstellen, wenn der Arbeitsbereich noch keins hat). Der Dialog „Signatur-Secret ersetzen?“ warnt, dass das aktuelle Secret sofort nicht mehr funktioniert. Klicken Sie auf Neues Secret erzeugen.

2. Kopieren Sie es

   Ihr Webhook-Signatur-Secret zeigt das vollständige Secret ein einziges Mal. Klicken Sie auf Kopieren und speichern Sie es dort, wo Ihr Webhook-Empfänger es lesen kann, etwa in einer Umgebungsvariablen. Sie sehen es nicht noch einmal: Wenn Sie es verlieren, erzeugen Sie ein neues.

Nur Inhaber sehen die Karte. Ein neues Secret ersetzt das alte sofort, aktualisieren Sie Ihre Empfänger also direkt danach; Webhooks, die in der Zwischenzeit gesendet werden, bestehen Ihre Prüfung nicht.

Webhook prüfen#

Berechnen Sie die Signatur aus dem unveränderten Body (bevor Ihr Framework ihn parst), vergleichen Sie sie in konstanter Zeit mit dem Header und lehnen Sie Zeitstempel ab, die älter als 5 Minuten sind, damit eine alte Anfrage nicht wiederholt werden kann:

import hashlib, hmac, time

def verify(secret: str, body: bytes, headers) -> bool:
    ts, sig = headers["WbizTool-Timestamp"], headers["WbizTool-Signature"]
    mac = "v1=" + hmac.new(secret.encode(), ts.encode() + b"." + body, hashlib.sha256).hexdigest()
    return abs(time.time() - int(ts)) < 300 and hmac.compare_digest(mac, sig)

const crypto = require("crypto");

function verify(secret, rawBody, headers) {
  const ts = headers["wbiztool-timestamp"], sig = String(headers["wbiztool-signature"]);
  const mac = "v1=" + crypto.createHmac("sha256", secret).update(ts + ".").update(rawBody).digest("hex");
  return Math.abs(Date.now() / 1000 - Number(ts)) < 300 && sig.length === mac.length &&
    crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(mac));
}

Antworten Sie mit 2xx, wenn die Prüfung besteht, und mit 401, wenn sie fehlschlägt. Posteingangs-Webhooks mit eigenem Secret der Nummer enthalten weiterhin zusätzlich X-Wbiztool-Signature; WbizTool-Signature ist auf jedem Webhook dasselbe Verfahren.

Fehlerbehebung#

Verwandte Themen#

• Erste Schritte mit der API
• Überblick über API v2
• Zugangsdaten prüfen (API)
• Nachricht senden (API)
• Apps & Integrationen
• Arbeitsbereich-Einstellungen, Teammitglieder und Rollen
• WhatsApp-Nummer verbinden