ServiceDesk an WhatsApp Business anbinden
Schritt-für-Schritt-Anleitung, um eine WhatsApp-Business-Nummer über die offizielle Meta Cloud API an ServiceDesk anzubinden — eingehende Nachrichten werden Tickets, Antworten gehen von dort raus.
Teil des Servicedesk-Plugins
Dieses Modul ist kein Standard-Feature von flowagents. Es wird über das Servicedesk-Plugin bereitgestellt und muss von einem Admin im Marketplace aktiviert werden.
Diese Anleitung führt dich durch die einmalige Einrichtung, damit ServiceDesk eingehende WhatsApp-Nachrichten an deine Geschäftsnummer automatisch als Tickets übernimmt und Antworten von dort verschickt — analog zu deiner E-Mail-Mailbox, nur eben über WhatsApp.
Kostet das pro Nachricht? Für Support praktisch nein. Seit Metas Per-Message-Modell (Juli 2025) sind Service-Nachrichten kostenlos: Sobald ein Kunde dir schreibt, öffnet sich ein 24-Stunden-Fenster, in dem alle deine Antworten gratis sind. Jede neue Kundennachricht setzt das Fenster zurück. Geld kostet nur proaktives Marketing außerhalb dieses Fensters — was im Support nicht vorkommt. Es gibt keinen externen Dienstleister und keinen Aufpreis pro Antwort.
Die WhatsApp-Anbindung läuft über die offizielle Meta Cloud API, nicht über die normale WhatsApp- oder WhatsApp-Business-App. Du brauchst dafür eine dedizierte Telefonnummer, die nicht parallel in der WhatsApp-App auf einem Handy aktiv ist — sonst kollidieren die beiden.
Wer macht was?
- Du (als Tenant) richtest die Meta-Seite ein: Business-Verifizierung, Telefonnummer, WhatsApp Business Account, Zugangs-Token. Es ist deine Marke, deine Nummer, deine Kundenbeziehung.
- flowagents stellt die Integration bereit. Du trägst am Ende nur die von Meta erzeugten IDs und Tokens in die ServiceDesk-Einstellungen ein.
Voraussetzungen
- Admin-Zugriff auf ein Meta Business Portfolio (business.facebook.com) — oder du legst eins an
- Eine dedizierte Telefonnummer, die SMS oder Anrufe empfangen kann (für die einmalige Verifizierung) und nicht in der WhatsApp-App genutzt wird. Eine virtuelle Nummer ist erlaubt.
- Ein Geschäftsnachweis für die Business-Verifizierung (Handelsregisterauszug, Gewerbeanmeldung o.ä.)
- Rechne mit 3–7 Werktagen Gesamtdauer — fast alles davon ist Wartezeit auf Metas Verifizierung, nicht Arbeit.
Die in-App-Sektion Einstellungen → ServiceDesk → WhatsApp-Kanäle rollt mit dem WhatsApp-Feature aus. Die Meta-seitigen Schritte 1–7 kannst du aber schon jetzt vorbereiten — sie sind unabhängig von flowagents und der zeitfressende Teil.
Schritt 1 — Business-Verifizierung abschließen
- Öffne business.facebook.com und melde dich an (oder erstelle ein Business Portfolio)
- Einstellungen → Unternehmensinfo: alle Felder ausfüllen (Rechtsname, Adresse, Website)
- Sicherheitscenter → Verifizierung starten: Geschäftsnachweis hochladen
- Auf Metas Freigabe warten (typisch 1–3 Werktage)
Schritt 2 — WhatsApp Business Account (WABA) anlegen
- Im Business Portfolio: Konten → WhatsApp-Konten → Hinzufügen
- Einen WhatsApp Business Account erstellen (das ist der Container für deine Nummer)
- Anzeigename setzen (der Name, den Kunden im Chat sehen, z.B.
Greenality) — Meta prüft ihn
Schritt 3 — Telefonnummer hinzufügen und verifizieren
- Im WABA: Telefonnummer hinzufügen
- Deine dedizierte Nummer eintragen, Verifizierungscode per SMS/Anruf bestätigen
- Notiere dir später die Phone Number ID (nicht die Nummer selbst — die ID, eine lange Zahl)
Falls die Nummer schon mal in der normalen WhatsApp-App registriert war, musst du sie dort zuerst löschen/deregistrieren, bevor Meta sie für die Cloud API akzeptiert.
Schritt 4 — Meta-App erstellen und WhatsApp hinzufügen
- Öffne developers.facebook.com → My Apps → Create App
- App-Typ Business wählen, mit deinem Business Portfolio verknüpfen
- Im App-Dashboard: Add Product → WhatsApp → Set up
- Den WABA aus Schritt 2 auswählen
- Im WhatsApp-Bereich findest du jetzt Phone Number ID und WhatsApp Business Account ID (WABA-ID) — beide notieren
Schritt 5 — Permanenten Zugangs-Token erzeugen
Der im Dashboard angezeigte Token ist nur 24 Stunden gültig. Für den Dauerbetrieb brauchst du einen System-User-Token:
- Business-Einstellungen → Nutzer → System-Nutzer → Hinzufügen
- Einen eigenen System-Nutzer mit Rolle Admin anlegen (z.B.
flowagents-servicedesk) — nicht einen bestehenden (z.B. Conversions-API-)System-Nutzer mitbenutzen - Assets zuweisen — zwei Assets, jeweils mit Vollzugriff / Uneingeschränkte Kontrolle:
- Apps → deine App aus Schritt 4
- WhatsApp-Konten → den WABA aus Schritt 2
- Ohne zugewiesene App lässt sich kein app-gebundener Token mit WhatsApp-Rechten erzeugen.
- Token generieren klicken, die App auswählen, Ablauf: „Nie", diese Berechtigungen setzen:
whatsapp_business_messagingwhatsapp_business_management
- Den Token sofort kopieren — er wird nur einmal angezeigt. Dieser Token läuft nicht ab.
Token verifizieren (empfohlen): Prüfe den Token im Meta Access Token Debugger — er sollte Gültig: Wahr, Ablauf: Niemals und die beiden whatsapp_business_*-Scopes anzeigen.
Schritt 6 — App Secret holen
- Im App-Dashboard: App-Einstellungen → Basis
- App Secret anzeigen und kopieren (brauchen wir, um die Echtheit der eingehenden Webhooks zu prüfen)
Schritt 7 — Webhook bei Meta eintragen
- In flowagents: Einstellungen → ServiceDesk → WhatsApp-Kanäle → Kanal hinzufügen öffnen — dort steht die Webhook-URL und du legst einen frei wählbaren Verify-Token fest (eine beliebige Zeichenkette)
- Zurück im Meta App-Dashboard: WhatsApp → Configuration → Webhook → Edit
- Callback-URL: die Webhook-URL aus flowagents einfügen
- Verify-Token: denselben Token wie in flowagents eintragen
- Verify and Save — Meta ruft die URL einmal auf; bei Erfolg erscheint ein grünes Häkchen
- Unter Webhook fields das Feld
messagesabonnieren (deckt eingehende Nachrichten und Zustellstatus ab)
Schritt 8 — Re-Engagement-Template registrieren (optional, für Antworten nach 24 h)
Willst du einen Kunden auch nach Ablauf des 24-Stunden-Fensters noch erreichen, brauchst du ein einmal genehmigtes Template:
- Im WABA: Nachrichtenvorlagen → Vorlage erstellen
- Kategorie Utility (Dienstprogramm) wählen — vorgangsbezogen, damit Meta es nicht als Marketing einstuft
- Inhalt (per du, Greenality-Ton) — die Platzhalter
{{1}}(Vorname) und{{2}}(Ticket-Nummer) füllt flowagents automatisch. Beispiel-Body:Hallo
{{1}}, zu deiner Anfrage{{2}}bei Greenality haben wir eine Rückmeldung für dich. Antworte einfach kurz auf diese Nachricht, dann helfen wir dir direkt weiter. - Auf Genehmigung warten (Minuten bis Stunden), dann Vorlagen-Name und Sprache notieren
Schritt 9 — Verbindung in flowagents eintragen
In Einstellungen → ServiceDesk → WhatsApp-Kanäle trägst du die in den Schritten gesammelten Werte ein:
| Feld | Quelle |
|---|---|
| Phone Number ID | Schritt 3 / 4 |
| WhatsApp Business Account ID | Schritt 4 |
| Permanenter Zugangs-Token | Schritt 5 |
| App Secret | Schritt 6 |
| Verify-Token | Schritt 7 (selbst gewählt) |
| Re-Engagement-Vorlagenname + Sprache | Schritt 8 (falls genutzt) |
Dann „Testen & Speichern": flowagents prüft Token + Telefonnummer-ID gegen die Graph API und speichert erst bei Erfolg. Der Kanal zeigt dann 🟢 „Verbindung getestet".
Token sauber einfügen: Beim Kopieren aus einer Notiz hängt oft ein unsichtbarer Zeilenumbruch am Ende. Meta meldet dann „Cannot parse access token". flowagents schneidet Leerzeichen/Umbrüche zwar ab — füge den Token trotzdem ohne Leerzeile davor/danach ein.
Testnummer vs. Produktivnummer: Metas kostenlose Testnummer kann nur an registrierte Test-Empfänger (max. 5, im API-Setup unter „An" hinterlegt) senden — eingehend dürfen alle schreiben. Für echten Betrieb brauchst du eine eigene, verifizierte Produktivnummer; die darf (im 24-h-Fenster) an jeden senden.
Verifikation
Schick aus einem beliebigen Handy eine WhatsApp an deine Geschäftsnummer. Innerhalb von Sekunden erscheint sie als neues Ticket in ServiceDesk. Antworte aus ServiceDesk — die Antwort landet als WhatsApp beim Absender. Schick eine Sprachnachricht: sie wird als abspielbare Audio plus automatisches Transkript im Ticket angezeigt.
Troubleshooting
| Problem | Lösung |
|---|---|
| Webhook „Verify and Save" schlägt fehl | Verify-Token in Meta und flowagents stimmen nicht exakt überein, oder die Webhook-URL ist falsch eingefügt. Beide 1:1 vergleichen. |
| Nachrichten kommen nicht an | Im Meta-Dashboard prüfen, ob das Feld messages abonniert ist. Ohne Abo schickt Meta nichts. |
Token expired / Antworten schlagen nach 24 h Token-Alter fehl | Du hast den temporären Dashboard-Token statt des System-User-Tokens (Schritt 5) eingetragen. |
„Testen & Speichern" meldet Cannot parse access token | Token unvollständig oder mit Leerzeichen/Umbruch kopiert. Frisch + sauber neu einfügen; im Token Debugger prüfen, ob er gültig ist. |
| Reply bleibt auf „Wird gesendet…" bzw. wird rot „Fehlgeschlagen" | Bei der Testnummer: Empfänger ist nicht in der Test-Empfängerliste (max. 5). Empfänger im Meta-API-Setup ergänzen — oder auf eine Produktivnummer umstellen. Der Fehlergrund steht als Tooltip am Häkchen. |
| Antwort schlägt fehl mit „außerhalb des 24-Stunden-Fensters" | Der Kunde hat seit über 24 h nicht geschrieben — freier Text ist gesperrt. Nutze den Button „Kunde erneut kontaktieren" (Re-Engagement-Template, Schritt 8). |
| Nummer wird bei Schritt 3 abgelehnt | Die Nummer ist noch in der WhatsApp-App registriert → dort zuerst deregistrieren. |
Was ist mit einem „Login per Knopfdruck"?
Diese Anleitung nutzt die direkte Anbindung mit eigener Meta-App, weil sie sofort funktioniert und keine zusätzliche Freigabe auf unserer Seite braucht. Ein vereinfachter Verbindungs-Flow („mit Meta verbinden"-Button, Embedded Signup) ist für eine spätere Version geplant — für die direkte Anbindung aber nicht nötig.