Admin-Einrichtung für Quick Connect

Damit deine Nutzer Quick Connect verwenden können, hinterlegt eine Org-Admin einmalig deine Meta-App-Zugangsdaten. Danach kann jeder Nutzer in der Organisation seine eigene WhatsApp-Business-Rufnummer aus dem Apps-Menü heraus anbinden, ohne dass du Tokens, Webhooks oder Telefonnummern-IDs anfassen musst.

Wer braucht diese Seite?

Diese Seite richtet sich an Org-Admins (die Rolle Admin in plemeo.ai). Normale Nutzer sehen die WhatsApp-Embedded-Signup-Konfigurationskarte nicht.

Was du einrichten wirst

Du brauchst vier Werte aus einer Meta Developer App, in der WhatsApp Embedded Signup aktiviert ist:

Feld in plemeo.ai	Was es ist	Woher es stammt
Meta App ID	Numerische ID deiner Meta Developer App	Meta App Dashboard → ganz oben
Meta App Secret	Das Client-Secret der App. Wird verschlüsselt gespeichert und nie an den Browser zurückgegeben.	Meta App Dashboard → App-Einstellungen → Allgemein
Embedded Signup Config ID	Numerische ID deiner WhatsApp-Embedded-Signup-Konfiguration	Meta App Dashboard → WhatsApp → Embedded Signup → Konfigurationen
Webhook Verify Token	Eine geheime Zeichenkette, die du auch in Metas Webhook-Konfiguration einträgst. plemeo.ai prüft damit eingehende Webhook-Aufrufe.	Frei wählbar – nimm einen starken Zufallswert.

Schritt 1 – Meta App mit WhatsApp-Produkt anlegen

1. Logge dich im Meta Developer Portal ein.
2. Wähle eine bestehende App oder lege eine neue App vom Typ Business an.
3. Klicke in der App links auf Produkt hinzufügen und füge WhatsApp hinzu.

Ist dein Unternehmen noch nicht verifiziert, hole das unter App-Einstellungen → Unternehmensverifizierung nach, bevor du live gehst. Für Tests kannst du Metas Testnummer nutzen; im Produktivbetrieb brauchst du immer ein verifiziertes Unternehmen und eine registrierte Rufnummer.

Hinweis

Das plemeo.ai-Backend spricht die Meta Graph API v21.0. Stelle sicher, dass die App auf dieser Version arbeitet (das WhatsApp-Produkt regelt das automatisch).

Schritt 2 – Embedded-Signup-Konfiguration anlegen

1. Öffne in deiner Meta App WhatsApp → Embedded Signup.
2. Klicke Konfiguration anlegen.
3. Wähle den Integrationstyp passend zu deinem Geschäftsmodell (die meisten plemeo.ai-Kunden wollen Tech Provider mit Cloud API).
4. Aktiviere Coexistence, damit Nutzer mit bereits vorhandener WhatsApp Business App auf dem Handy onboarden können, ohne ihre Daten zu verlieren.
5. Speichern und die Configuration ID kopieren, die Meta dir anzeigt.

Schritt 3 – Webhook konfigurieren

Über den Webhook liefert Meta eingehende Nachrichten und Status-Updates an plemeo.ai aus.

1. Gehe in deiner Meta App zu WhatsApp → Konfiguration → Callback URL.

2. Setze die Callback URL auf deine plemeo.ai-Webhook-URL. In Produktion:

   https://<dein-plemeoai-host>/webhook

   Ersetze <dein-plemeoai-host> durch den öffentlichen Hostname deiner plemeo.ai-Instanz (z. B. tenant.plemeo.ai für die SaaS Lite-Version oder deine Custom-Domain bei OnPrem). Der Webhook-Handler ist unter /webhook auf demselben Host wie die API erreichbar.

3. Setze das Verify token auf einen starken Zufallswert. Diesen Wert merken – du fügst ihn im nächsten Schritt unverändert in plemeo.ai ein.

4. Abonniere mindestens das Feld messages. Bei Coexistence zusätzlich history, smb_app_state_sync und smb_message_echoes.

Achtung

Der Verify Token muss auf beiden Seiten byte-identisch sein. Keine versehentlichen Leerzeichen oder Anführungszeichen.

Schritt 4 – Zugangsdaten in plemeo.ai hinterlegen

1. Melde dich in plemeo.ai als Admin an und öffne die Einstellungen.

2. Scrolle zu WhatsApp Embedded Signup Configuration und klicke Show WhatsApp Embedded Signup Configuration.

3. Trage die vier Felder ein:

   • Meta App ID – die numerische App-ID.
   • Meta App Secret – einfügen. plemeo.ai speichert es verschlüsselt; bei späteren Aufrufen zeigt das Feld einen grünen Set-Chip und bleibt leer. Erst wieder eintippen, wenn du den Secret rotieren willst.
   • Embedded Signup Config ID – die Configuration ID aus Schritt 2.
   • Webhook Verify Token – derselbe Zufallswert, den du in Metas Callback-URL-Konfiguration verwendet hast.

4. Klicke Test Connection, um die Zugangsdaten zu prüfen (plemeo.ai ruft Meta auf und bestätigt, dass die App ID auf eine echte App auflöst).

5. Klicke Save.

Tipp

Test Connection prüft App ID + Secret bei Meta. Die Embedded Signup Config ID wird hier nicht geprüft – die wird erst validiert, wenn ein Nutzer Quick Connect tatsächlich startet.

Was Nutzer danach sehen

Sobald Schritt 4 gespeichert ist, sehen alle Nutzer der Org den Quick Connect-Tab mit dem aktiven Button Connect with WhatsApp. Sie können ihre eigene(n) Nummer(n) ohne weitere Admin-Aktion verbinden.

Wenn ein Nutzer meldet, dass er „WhatsApp Embedded Signup ist noch nicht konfiguriert. Bitte wende dich an deinen Administrator." sieht, prüfe:

• alle vier Felder sind gespeichert (der Set-Chip ist beim Meta App Secret sichtbar).
• die Embedded Signup Config ID stimmt mit der in deiner Meta App überein.
• der Nutzer hat die Apps-Modal nach dem Speichern neu geladen.

Zugangsdaten rotieren

So rotierst du das Meta App Secret oder wechselst die Embedded-Signup-Konfiguration:

1. Öffne erneut die WhatsApp-Embedded-Signup-Konfigurationskarte.
2. Aktualisiere die Felder und klicke Save. Das alte Secret wird im Backend überschrieben.
3. Bestehende Nutzerverbindungen werden durch die Rotation des App Secrets nicht ungültig – Meta-Access-Tokens bleiben gültig, bis sie ablaufen oder du sie trennst. Neue Verbindungen ab diesem Zeitpunkt nutzen die neuen Zugangsdaten.

Webhook-Felder – Referenz

Das plemeo.ai-Backend kann die folgenden Webhook-Felder verarbeiten. Abonniere, was dein Anwendungsfall braucht:

Feld	Wann abonnieren	Verwendet für
messages	Immer	Eingehende Text-/Media-/Template-Nachrichten, Status-Updates (sent, delivered, read), Fehler
history	Nur bei Coexistence	Spiegelung des Chatverlaufs aus der WhatsApp Business App
smb_app_state_sync	Nur bei Coexistence	Spiegelung der Kontaktliste aus der WhatsApp Business App
smb_message_echoes	Nur bei Coexistence	Spiegelung von Nachrichten, die ein Nutzer aus der WhatsApp Business App sendet
account_update	Empfohlen	Disconnect-/Reconnect-/Offboarding-Ereignisse am WABA
message_template_status_update	Empfohlen	Genehmigung/Ablehnung von Templates

Vollständige Schemas siehe Metas Doku:

• Onboarding WhatsApp Business app users (Coexistence)
• WhatsApp Cloud API – Webhook-Referenz

Fehlerbehebung

Symptom	Wahrscheinliche Ursache	Lösung
Test Connection liefert "Invalid App ID"	Falsche App ID oder gelöschte App	App ID erneut aus dem Meta App Dashboard kopieren.
Test Connection liefert "Invalid OAuth access token"	App Secret falsch oder bei Meta rotiert	In der Meta App App-Einstellungen → Allgemein öffnen, neben App Secret auf Anzeigen klicken und den aktuellen Wert in plemeo.ai einfügen.
Nutzer sehen „Facebook SDK not loaded"	Metas connect.facebook.net ist blockiert (z. B. strikter Adblocker, Firmen-Proxy oder CSP).	connect.facebook.net zulassen und neu laden. Bei CSP-Problemen auf einer eigenen Domain den plemeo.ai-Integrator kontaktieren.
Webhook feuert nach Quick-Connect-Signup nicht	Metas Callback URL oder Verify Token ist falsch	Callback URL muss auf https://<dein-plemeoai-host>/webhook zeigen; Verify Token in Meta und plemeo.ai müssen byte-identisch sein.
Eingehende Nachrichten erscheinen nicht trotz konfiguriertem Webhook	Im Webhook-Abo fehlt das Feld messages	In der Webhook-Konfiguration bei Meta bei der WhatsApp Business Account Topic auf Verwalten klicken und messages aktivieren.

Wie geht es weiter?

• Verweise deine Nutzer auf Quick Connect – mehr Doku brauchen die meisten nicht.
• Wenn du zusätzlich den manuellen / Fallback-Pfad anbieten willst, siehe Erweiterte Einrichtung.