Skip to main content
Das WhatsApp-Onboarding im Produkt läuft über Meta Embedded Signup v4 (Tech Provider). Nutzer klicken auf Mit Meta verbinden, durchlaufen das Meta-Popup (Login, WABA, Telefonverifizierung), und wir schließen das Onboarding serverseitig ab (Token-Austausch, Webhooks, Telefonregistrierung). Das manuelle Einfügen von Zugangsdaten bleibt weiterhin als Fallback verfügbar. Die Runtime bleibt dabei gleich: Cloud API für Text, WhatsApp-Voice-Connector der Plattform für Anrufe.
Embedded Signup v2 läuft am 15. Oktober 2026 aus. Verwende ausschließlich v4-Konfigurationen.

​
Architektur

Die SMS-Helfer der Plattform sind nur für SMS/MMS – nicht für WhatsApp. SIP-Trunk-Voice auf einer Marktplatznummer läuft unabhängig von der WhatsApp Cloud API und von SMS-Webhooks.

​
Voraussetzungen (Plattform)

  1. Meta-Business-Portfolio mit Business Verification und 2FA
  2. Neue Meta-App vom Typ Business (keine bestehende App wiederverwenden)
  3. Produkte: WhatsApp, Facebook Login for Business, Webhooks
  4. App Review Advanced Access: whatsapp_business_management, whatsapp_business_messaging
  5. Tech Provider / Access Verification (erhöht das wöchentliche Onboarding-Limit von 10 auf 200)

​
Checkliste für das Meta-App-Dashboard

​
1. App erstellen

  1. Gehe zu developers.facebook.com → Create App → wähle den Typ Business
  2. Verwende kein „WhatsApp” im App-Namen (Meta-Markenregeln)
  3. Verknüpfe dein verifiziertes Business-Portfolio

​
2. Facebook Login for Business

  1. Öffne Facebook Login for Business → Settings → Client OAuth Settings
  2. Aktiviere: Client OAuth Login, Web OAuth Login, HTTPS erzwingen, Embedded Browser OAuth Login, Strict Mode, Login mit dem JavaScript SDK
  3. Allowed Domains und Valid OAuth Redirect URIs: deine Produktions- und Preview-Domains (nur HTTPS), z. B. https://app.famulor.io

​
3. Embedded-Signup-Konfiguration

  1. Facebook Login for Business → Configurations → Create from template
  2. Wähle WhatsApp Embedded Signup Configuration With 60 Expiration Token
  3. Kopiere die Configuration ID → META_EMBEDDED_SIGNUP_CONFIG_ID / NEXT_PUBLIC_META_EMBEDDED_SIGNUP_CONFIG_ID

​
4. App-Webhooks (Plattform-Callback)

  1. WhatsApp → Configuration → Webhook
  2. Callback-URL: https://app.famulor.io/api/webhooks/meta/whatsapp-platform
  3. Verify Token: derselbe Wert wie META_WEBHOOK_VERIFY_TOKEN
  4. Abonniere mindestens: account_update, messages, calls, message_template_status_update
Nach dem Embedded Signup setzen wir zusätzlich einen Webhook-Override pro WABA auf /api/webhooks/messaging/whatsapp/{connectorId}, damit das Multi-Tenant-Routing zu den übrigen Messaging-Kanälen passt. Felder, die keinen Override unterstützen (z. B. manche Konto-/Template-Events), bleiben auf dem Plattform-Callback.

​
5. Umgebungsvariablen

Für Messaging/Voice (Operator) außerdem erforderlich: Verschlüsselungsschlüssel für Zugangsdaten, die Basis-App-URL der Plattform (öffentlicher Origin für Webhooks), Voice-Zugangsdaten der Plattform, KI-Zugangsdaten der Plattform sowie Cron-Auth für den Template-Sync.

​
6. App Review und Live-Modus

  • Solange die App im Development-Modus ist, können nur Admins/Developer/Tester das Embedded Signup abschließen
  • Reiche App Review für die WhatsApp-Berechtigungen ein und wechsle danach in den Live-Modus
  • Abonniere account_update, bevor du echte Kunden onboardest

​
Produkt-UX (Workspace)

Einstellungen → Kanäle → WhatsApp
  1. Wähle einen Assistenten
  2. Wähle optional eine Marktplatznummer aus (SMS-fähig ist für Meta OTP vorzuziehen)
  3. Ist eine Marktplatznummer ausgewählt, leiten wir ihren SMS-Webhook vorübergehend auf unseren OTP-Erfassungsendpunkt um (Telefon-/SIP-Voice bleibt unverändert) und zeigen Metas OTP in der Oberfläche an
  4. Klicke auf Mit Meta verbinden → schließe das Popup ab
  5. Server: Code tauschen → Business-Token → WABA abonnieren → Webhook-Override → Telefonnummer registrieren → Connector erstellen (onboarding_source=embedded_signup)
  6. Weise den Kunden darauf hin, vor Nachrichten mit hohem Volumen eine Zahlungsmethode im WhatsApp Manager zu hinterlegen

​
Marktplatznummern + OTP

Der Kauf einer Nummer unter Einstellungen → Nummern aktiviert WhatsApp nie automatisch.

​
Öffentliche API

  • GET /api/whatsapp/embedded-signup/config – öffentliche App-/Config-IDs + Enabled-Flag
  • POST /api/whatsapp/embedded-signup – Onboarding abschließen (code, waba_id, phone_number_id, assistant_id, …)
  • POST/GET/DELETE /api/whatsapp/otp-session – Lebenszyklus der Marktplatz-OTP-Erfassung
  • MCP: complete_whatsapp_embedded_signup

​
Verwandte Themen