Skip to main content
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.
Embedded Signup v2 is deprecated on October 15, 2026. Use v4 configurations only.

​
Architecture

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 → 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

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

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