> ## 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)

> Set up your Meta app and connect WhatsApp inside Settings → Channels → WhatsApp

WhatsApp onboarding in the product uses **Meta Embedded Signup v4** (Tech Provider). Users click **Connect with Meta**, complete Meta's popup (login, WABA, phone verification), and we finish server-side onboarding (token exchange, webhooks, phone register).

Manual credential paste remains available as a fallback. Runtime stays the same: Cloud API for text, platform WhatsApp voice connector for calls.

<Note>
  Embedded Signup v2 is deprecated on **October 15, 2026**. Use v4 configurations only.
</Note>

## Architecture

| Layer                    | Stack                                                              |
| ------------------------ | ------------------------------------------------------------------ |
| Onboarding               | Meta Embedded Signup (Facebook Login for Business)                 |
| Text                     | Meta Cloud API                                                     |
| Voice                    | Platform WhatsApp voice connector                                  |
| Numbers from marketplace | Marketplace E.164 + Meta OTP (SMS capture helper)                  |
| Billing (Meta)           | Customer adds a payment method in WhatsApp Manager (Tech Provider) |

Platform SMS helpers are **SMS/MMS only** — not WhatsApp. SIP trunk voice on a marketplace number is independent of WhatsApp Cloud API and of SMS webhooks.

## Prerequisites (platform)

1. Meta Business portfolio with **Business Verification** and **2FA**
2. New **Business**-type Meta app (do not reuse an old app)
3. Products: **WhatsApp**, **Facebook Login for Business**, **Webhooks**
4. App Review advanced access: `whatsapp_business_management`, `whatsapp_business_messaging`
5. Tech Provider / Access Verification (raises weekly onboard limit 10 → 200)

## Meta App Dashboard checklist

### 1. Create the app

1. Go to [developers.facebook.com](https://developers.facebook.com) → **Create App** → type **Business**
2. Do **not** put "WhatsApp" in the app name (Meta trademark rules)
3. Attach your verified Business portfolio

### 2. Facebook Login for Business

1. Open **Facebook Login for Business → Settings → Client OAuth settings**
2. Enable: Client OAuth login, Web OAuth login, Enforce HTTPS, Embedded Browser OAuth Login, Strict Mode, Login with the JavaScript SDK
3. **Allowed domains** and **Valid OAuth redirect URIs**: your production domain and preview domains (HTTPS only), e.g. `https://app.famulor.io`

### 3. Embedded Signup configuration

1. **Facebook Login for Business → Configurations → Create from template**
2. Choose **WhatsApp Embedded Signup Configuration With 60 Expiration Token**
3. Copy the **Configuration ID** → `META_EMBEDDED_SIGNUP_CONFIG_ID` / `NEXT_PUBLIC_META_EMBEDDED_SIGNUP_CONFIG_ID`

### 4. App webhooks (platform callback)

1. **WhatsApp → Configuration → Webhook**
2. Callback URL: `https://app.famulor.io/api/webhooks/meta/whatsapp-platform`
3. Verify token: same value as `META_WEBHOOK_VERIFY_TOKEN`
4. Subscribe at least: `account_update`, `messages`, `calls`, `message_template_status_update`

After Embedded Signup we also set a **per-WABA webhook override** to\
`/api/webhooks/messaging/whatsapp/{connectorId}` so multi-tenant routing matches the rest of the messaging channels. Fields that do not support override (e.g. some account/template events) stay on the platform callback.

### 5. Environment variables

```bash theme={null}
META_EMBEDDED_SIGNUP_ENABLED=true
META_APP_ID=...
NEXT_PUBLIC_META_APP_ID=...          # same as 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=...
```

Also required for messaging/voice (operator): credential encryption key, platform **base app URL** (public origin used for webhooks), platform voice credentials, platform AI credentials, and cron auth for template sync.

### 6. App Review and Live mode

* While the app is in Development, only admins/developers/testers can complete Embedded Signup
* Submit App Review for the WhatsApp permissions, then switch to Live
* Subscribe to `account_update` before onboarding real customers

## Product UX (workspace)

**Settings → Channels → WhatsApp**

1. Pick an assistant
2. Optionally select a marketplace number (SMS-capable preferred for Meta OTP)
3. If a marketplace number is selected, we temporarily point its **SMS** webhook at our OTP capture endpoint (phone/SIP voice unchanged) and show Meta's OTP in the UI
4. Click **Connect with Meta** → complete the popup
5. Server: exchange code → business token → subscribe WABA → webhook override → register phone → create connector (`onboarding_source=embedded_signup`)
6. Instruct the customer to add a **payment method** in WhatsApp Manager before high-volume messaging

## Marketplace numbers + OTP

| Number type            | Meta OTP                 | Our helper                                 |
| ---------------------- | ------------------------ | ------------------------------------------ |
| Marketplace with SMS   | SMS to the number        | OTP session captures SMS, shows code in UI |
| Marketplace voice-only | Voice call               | Prefer SMS-capable numbers for MVP         |
| Customer-owned SIM     | SMS/voice to their phone | User enters OTP in Meta popup              |

Buying a number in **Settings → Numbers** never auto-enables WhatsApp.

## Public API

* `GET /api/whatsapp/embedded-signup/config` — public app/config IDs + enabled flag
* `POST /api/whatsapp/embedded-signup` — complete onboarding (`code`, `waba_id`, `phone_number_id`, `assistant_id`, …)
* `POST/GET/DELETE /api/whatsapp/otp-session` — marketplace OTP capture lifecycle
* MCP: `complete_whatsapp_embedded_signup`

## Related

* [WhatsApp (Text + Voice)](/channels/whatsapp)
* [Messaging channels](/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)