> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ouraicalling.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp Embedded Signup (Meta Tech Provider)

> Richte deine Meta-App ein und verbinde WhatsApp unter Einstellungen → Kanäle → WhatsApp

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.

<Note>
  Embedded Signup v2 läuft am **15. Oktober 2026** aus. Verwende ausschließlich v4-Konfigurationen.
</Note>

## Architektur

| Ebene                      | Stack                                                                     |
| -------------------------- | ------------------------------------------------------------------------- |
| Onboarding                 | Meta Embedded Signup (Facebook Login for Business)                        |
| Text                       | Meta Cloud API                                                            |
| Sprache                    | WhatsApp-Voice-Connector der Plattform                                    |
| Nummern aus dem Marktplatz | Marktplatz-E.164 + Meta-OTP (SMS-Erfassungshilfe)                         |
| Abrechnung (Meta)          | Kunde hinterlegt eine Zahlungsmethode im WhatsApp Manager (Tech Provider) |

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](https://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

```bash theme={null}
META_EMBEDDED_SIGNUP_ENABLED=true
META_APP_ID=...
NEXT_PUBLIC_META_APP_ID=...          # identisch mit META_APP_ID
META_APP_SECRET=...
META_EMBEDDED_SIGNUP_CONFIG_ID=...
NEXT_PUBLIC_META_EMBEDDED_SIGNUP_CONFIG_ID=...
META_GRAPH_API_VERSION=v25.0
META_WEBHOOK_VERIFY_TOKEN=...
```

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

| Nummerntyp                   | Meta-OTP                        | Unser Helfer                                                      |
| ---------------------------- | ------------------------------- | ----------------------------------------------------------------- |
| Marktplatz mit SMS           | SMS an die Nummer               | OTP-Session fängt die SMS ab und zeigt den Code in der Oberfläche |
| Reine Voice-Marktplatznummer | Sprachanruf                     | Für den MVP SMS-fähige Nummern bevorzugen                         |
| Kundeneigene SIM             | SMS/Anruf an das eigene Telefon | Nutzer gibt das OTP im Meta-Popup ein                             |

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

* [WhatsApp (Text + Sprache)](/channels/whatsapp)
* [Messaging-Kanäle](/channels/messaging)
* [WhatsApp Voice](/telephony/whatsapp-voice)
* Meta: [Embedded Signup](https://developers.facebook.com/docs/whatsapp/embedded-signup/) · [Tech Provider onboarding](https://developers.facebook.com/docs/whatsapp/embedded-signup/onboarding-customers-as-a-tech-provider)