API-Schlüssel
Aktualisiert am
Wo: Einstellungen > Integrationen > API-Schlüssel
Wozu es dient:
„Geben Sie einem externen Programm einen eigenen Schlüssel zum Senden über SyBox — das WhatsApp-Token verlässt nie den Server, und ein kompromittierter Schlüssel kann separat widerrufen werden.“ Ihr ERP-System, Ihre Kasse oder Ihr Desktop-Programm nutzt einen SyBox-Schlüssel und benötigt zu keinem Zeitpunkt Ihre echten WhatsApp-Zugangsdaten.
Was ein Programm mit einem Schlüssel tun kann (in der öffentlichen Entwicklerdokumentation beschrieben):
- WhatsApp-Nachrichten über Ihre verbundene Rufnummer senden. Dabei wird dasselbe Anfrageformat wie bei Metas WhatsApp Cloud API verwendet – ein Programm, das bereits dafür geschrieben wurde, benötigt lediglich eine neue Adresse und einen SyBox-Schlüssel. Text, Vorlagen, Bilder, Dokumente und interaktive Nachrichten werden voll unterstützt. Antworten und Fehlermeldungen werden exakt so zurückgegeben, wie Meta sie ausgibt.
- Einen Fall aus Ihrem eigenen System anlegen, beispielsweise eine im ERP erfasste Reklamation. Der Kunde muss dafür bereits in SyBox existieren.
- SMS von einem Telefon in den Posteingang importieren.
- Ihre Automatisierungen aus einem anderen System starten (ein Schlüssel vom Typ „Automatisierung starten“).
- Ihre Kontakte aus einem anderen System suchen, lesen und ändern (ein Schlüssel vom Typ „Kontakte lesen und aktualisieren“).
Wer Zugriff hat: Der Hauptadministrator sowie Teammitglieder mit der Berechtigung „Kanäle verwalten“.
Der Schalter „API-Gateway“:
Oben auf der Seite mit den API-Schlüsseln befindet sich der Schalter „API-Gateway“. Er ist standardmäßig ausgeschaltet. Solange er inaktiv ist, funktioniert kein Schlüssel und es können keine neuen Schlüssel erstellt werden. Bei einem Versuch erscheint: „Das API-Gateway ist deaktiviert. Aktivieren Sie es mit dem Schalter oben auf dieser Seite, bevor Sie Schlüssel erstellen.“ Der Schalter wird direkt beim Anklicken gespeichert.
- Gehen Sie zu Einstellungen > Integrationen > API-Schlüssel.
- Aktivieren Sie den Schalter „API-Gateway“.
- Klicken Sie auf „Neuer Schlüssel“.
- Wählen Sie den „Schlüsseltyp“:
- „Über WhatsApp senden“: Das Programm sendet Nachrichten an Ihre Kunden.
- „Fall anlegen“: Das Programm öffnet Vorgänge in SyBox. Es kann keine Nachrichten senden.
- „SMS von einem Telefon importieren“: Ein Smartphone leitet seine SMS-Nachrichten in den Posteingang weiter.
- „Automatisierung starten“: Das Programm startet die Automatisierungen, bei denen unter „Startet, wenn“ die Option „Ein anderes Programm ruft SyBox auf“ gewählt ist (POST /v1/automation mit „phone“ des Kunden sowie optional „event“ und „data“). Es kann keine Nachrichten senden. Siehe Einstellungen > KI und Automatisierung > Automatisierungen.
- „Kontakte lesen und aktualisieren“: Das Programm sucht Kontakte, liest einen Kontakt aus und ändert dessen Namen, E-Mail-Adresse, Kontaktfelder und Labels (POST /v1/contacts/search, /get, /update und /labels). Es kann keine Nachrichten senden. Der Schlüssel handelt im Namen der Person, die ihn erstellt hat: Er sieht nur die Kontakte, die diese Person sehen darf, funktioniert nur, wenn diese Person die Kontaktliste öffnen und Nummern sehen darf, und kann Kontakte nur ändern, wenn diese Person sie bearbeiten darf. Wird diese Person deaktiviert, funktioniert der Schlüssel nicht mehr.
- Tragen Sie den „Geräte- oder Programmname“ ein, z. B. „Büro-PC“ oder „Buchhaltung“. Vergeben Sie für jedes Gerät und Programm einen eigenen Schlüssel.
- Legen Sie für einen Schlüssel vom Typ „Über WhatsApp senden“ außerdem Folgendes fest:
- „Sendet von“: Die WhatsApp-Nummer, über die dieser Schlüssel Nachrichten versendet (Pflichtfeld).
- „Freitextnachrichten erlauben“: Ein oder Aus.
- „Genehmigte Vorlagen erlauben“: Ein oder Aus. Mindestens eine dieser beiden Optionen muss aktiv sein, andernfalls erscheint: „Erlauben Sie mindestens Freitext oder Vorlagen — andernfalls kann der Schlüssel nichts senden.“
- „Senden von Medien erlauben“: Ein oder Aus.
- „Vorlagen“ (optional): Vorlagennamen, durch Kommas getrennt. Leer lassen, um alle Vorlagen zu erlauben.
- „Erlaubte Empfängerländer“ (optional): Ländercodes mit zwei Buchstaben, z. B. DE,AT,CH. Leer lassen, um alle Länder zuzulassen.
- „Senden erlaubt von“ ... „Zu“: Das Zeitfenster, in dem der Schlüssel senden darf. Lassen Sie beide Werte gleich, wenn es keine zeitliche Einschränkung geben soll. Die Zeiten beziehen sich auf die Ortszeit des Arbeitsbereichs.
- „Tägliches Nachrichtenlimit (0 = unbegrenzt)“.
- Aktivieren Sie bei Schlüsseln vom Typ „SMS von einem Telefon importieren“ die Option „Nur Kontakte und Kunden“. Ist sie aktiv, verbleiben SMS von unbekannten Nummern auf dem Telefon und erreichen den Posteingang nicht. Deaktivieren Sie dies nur, wenn das Telefon ausschließlich geschäftlich genutzt wird.
- Klicken Sie auf Speichern.
- Ein Fenster zeigt die „Basis-URL“ und den „API-Schlüssel“ an. Kopieren Sie diese jetzt. „Kopieren Sie diesen Schlüssel jetzt — er wird nur einmal angezeigt.“ Tragen Sie die Daten in den Einstellungen Ihres Programms ein.
Was die Kachel des Schlüssels anzeigt:
- Den Namen des Schlüssels und die Absendernummer (bzw. das Typ-Badge bei Schlüsseln, die nicht senden).
- Die letzten Zeichen des Schlüssels, damit Sie die Schlüssel unterscheiden können.
- „zuletzt verwendet“ mit Datum und Uhrzeit oder „nie“.
- Alle aktiven Beschränkungen: „Nur Freitext“, „Nur Vorlagen“, „keine Medien“, „Vorlagen“, erlaubte Länder, Sendezeiten sowie das Tageslimit im Format Heute gesendet / Limit / Tag. Ein SMS-Schlüssel, der alle Nummern akzeptiert, zeigt „Jede Nummer“.
- Klicken Sie auf der Kachel des Schlüssels auf Bearbeiten. Sie können Name, Nummer und Beschränkungen anpassen. Der Schlüsseltyp kann nach der Erstellung nicht mehr geändert werden, und der Schlüssel selbst wird nie wieder angezeigt.
- Klicken Sie auf Aktivieren / Deaktivieren, um einen Schlüssel vorübergehend zu sperren.
- Klicken Sie auf Löschen und bestätigen Sie: „Diesen API-Schlüssel löschen? Jedes Programm, das ihn noch verwendet, funktioniert sofort nicht mehr.“
Ich habe meinen API-Schlüssel verloren. Kann ich ihn noch einmal ansehen?
Nein. Er wird nur ein einziges Mal angezeigt. Erstellen Sie einen neuen Schlüssel, tragen Sie ihn in Ihr Programm ein und löschen Sie danach den alten Schlüssel.
Ich vermute, dass ein Schlüssel offengelegt wurde. Was soll ich tun?
Löschen oder deaktivieren Sie diesen Schlüssel unverzüglich. Nur dieser einzelne Schlüssel verliert seine Gültigkeit. Ihre WhatsApp-Nummer und Ihre übrigen Schlüssel sind davon nicht betroffen.
Die Auswahlliste „Sendet von“ ist leer.
Die Liste enthält nur WhatsApp-Nummern, die verbunden und aktiviert sind. Verbinden Sie zuerst eine Nummer unter Einstellungen > Nachrichten > Kanäle.
Mein Programm erhält beim Senden eine Fehlermeldung.
Prüfen Sie, ob der Schalter „API-Gateway“ eingeschaltet und der Schlüssel aktiv ist. Kontrollieren Sie auch die Limits des Schlüssels: Freitext vs. Vorlagen, Medien, erlaubte Vorlagen, erlaubte Länder, Sendezeiten und das Tageslimit. Zudem gelten weiterhin die Vorgaben von WhatsApp – so ist Freitext beispielsweise nur innerhalb von 24 Stunden nach der letzten Nachricht des Kunden möglich.
Kann ein Schlüssel vom Typ „Fall anlegen“ auch Nachrichten senden?
Nein, das ist bewusst so geregelt. Ein Schlüssel zum Anlegen von Fällen kann keine Nachrichten senden, und ein Sendeschlüssel kann keine Fälle anlegen. Verwenden Sie für jeden Zweck einen eigenen Schlüssel.
Ich habe noch einen alten Schlüssel vom Typ „Von einem Programm empfangen“. Funktioniert dieser noch?
Ja, bestehende Schlüssel dieses Typs funktionieren weiterhin. Neue Schlüssel dieses Typs können jedoch nicht mehr erstellt werden. Verwenden Sie für solche Aufgaben künftig „Fall anlegen“.