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

# Embedded Signup de WhatsApp (Meta Tech Provider)

> Configura tu app de Meta y conecta WhatsApp desde Configuración → Canales → WhatsApp

La incorporación de WhatsApp en el producto usa **Meta Embedded Signup v4** (Tech Provider). El usuario hace clic en **Conectar con Meta**, completa la ventana emergente de Meta (inicio de sesión, WABA, verificación telefónica) y nosotros completamos la incorporación en el servidor (intercambio de token, webhooks, registro del número).

Pegar las credenciales manualmente sigue disponible como alternativa. El runtime no cambia: Cloud API para texto, conector de voz de WhatsApp de la plataforma para llamadas.

<Note>
  Embedded Signup v2 quedará obsoleto el **15 de octubre de 2026**. Usa solo configuraciones v4.
</Note>

## Arquitectura

| Capa                   | Stack                                                                   |
| ---------------------- | ----------------------------------------------------------------------- |
| Incorporación          | Meta Embedded Signup (Facebook Login for Business)                      |
| Texto                  | Meta Cloud API                                                          |
| Voz                    | Conector de voz de WhatsApp de la plataforma                            |
| Números de marketplace | Marketplace E.164 + Meta OTP (asistente de captura de SMS)              |
| Facturación (Meta)     | El cliente agrega un método de pago en WhatsApp Manager (Tech Provider) |

Los asistentes de SMS de la plataforma son **solo SMS/MMS**, no WhatsApp. La voz por Troncal SIP en un número de marketplace es independiente de la API de WhatsApp Cloud y de los webhooks de SMS.

## Requisitos previos (plataforma)

1. Portafolio de Meta Business con **Business Verification** y **2FA**
2. Una nueva app de Meta de tipo **Business** (no reutilices una app antigua)
3. Productos: **WhatsApp**, **Facebook Login for Business**, **Webhooks**
4. Acceso avanzado de App Review: `whatsapp_business_management`, `whatsapp_business_messaging`
5. Tech Provider / Access Verification (eleva el límite semanal de incorporaciones de 10 → 200)

## Lista de verificación del panel de tu app de Meta

### 1. Crea la app

1. Ve a [developers.facebook.com](https://developers.facebook.com) → **Create App** → elige el tipo **Business**
2. **No** incluyas "WhatsApp" en el nombre de la app (normas de marca de Meta)
3. Vincula tu portafolio de Meta Business verificado

### 2. Facebook Login for Business

1. Abre **Facebook Login for Business → Settings → Client OAuth settings**
2. Habilita: Client OAuth login, Web OAuth login, Enforce HTTPS, Embedded Browser OAuth Login, Strict Mode, Login with the JavaScript SDK
3. **Allowed domains** y **Valid OAuth redirect URIs**: tu dominio de producción y los dominios de preview (solo HTTPS), p. ej. `https://app.famulor.io`

### 3. Configuración de Embedded Signup

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

### 4. Webhooks de la app (callback de la plataforma)

1. **WhatsApp → Configuration → Webhook**
2. Callback URL: `https://app.famulor.io/api/webhooks/meta/whatsapp-platform`
3. Verify token: el mismo valor que `META_WEBHOOK_VERIFY_TOKEN`
4. Suscríbete al menos a: `account_update`, `messages`, `calls`, `message_template_status_update`

Después del Embedded Signup, también configuramos una **anulación de webhook por WABA** hacia\
`/api/webhooks/messaging/whatsapp/{connectorId}` para que el enrutamiento multi-tenant coincida con el del resto de canales de mensajería. Los campos que no admiten anulación (por ejemplo, algunos eventos de cuenta o de plantilla) se quedan en el callback de la plataforma.

### 5. Variables de entorno

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

También se necesita para mensajería/voz (operador): la clave de cifrado de credenciales, la **URL base de la app** de la plataforma (origen público usado para los webhooks), las credenciales de voz de la plataforma, las credenciales de IA de la plataforma y la autenticación cron para la sincronización de plantillas.

### 6. App Review y modo Live

* Mientras la app esté en modo Development, solo admins/developers/testers pueden completar el Embedded Signup
* Envía la app a App Review para los permisos de WhatsApp y luego cambia a modo Live
* Suscríbete a `account_update` antes de incorporar clientes reales

## UX del producto (espacio de trabajo)

**Configuración → Canales → WhatsApp**

1. Elige un asistente
2. Opcionalmente, selecciona un número de marketplace (se prefieren los que admiten SMS para el OTP de Meta)
3. Si eliges un número de marketplace, apuntamos temporalmente su webhook de **SMS** a nuestro endpoint de captura de OTP (la voz por teléfono/SIP no cambia) y mostramos el OTP de Meta en la interfaz
4. Haz clic en **Conectar con Meta** → completa la ventana emergente
5. Servidor: intercambia el código → token de negocio → suscribe la WABA → anulación de webhook → registra el número → crea el conector (`onboarding_source=embedded_signup`)
6. Indica al cliente que agregue un **método de pago** en WhatsApp Manager antes de enviar mensajes a gran volumen

## Números de marketplace + OTP

| Tipo de número         | Meta OTP              | Nuestro asistente                                                  |
| ---------------------- | --------------------- | ------------------------------------------------------------------ |
| Marketplace con SMS    | SMS al número         | La sesión de OTP captura el SMS y muestra el código en la interfaz |
| Marketplace solo voz   | Llamada de voz        | Se prefieren números con SMS para el MVP                           |
| SIM propia del cliente | SMS/voz a su teléfono | El usuario ingresa el OTP en la ventana emergente de Meta          |

Comprar un número en **Configuración → Números** nunca activa WhatsApp automáticamente.

## API pública

* `GET /api/whatsapp/embedded-signup/config`: IDs públicos de app/config + flag de habilitado
* `POST /api/whatsapp/embedded-signup`: completa la incorporación (`code`, `waba_id`, `phone_number_id`, `assistant_id`, …)
* `POST/GET/DELETE /api/whatsapp/otp-session`: ciclo de vida de la captura de OTP del marketplace
* MCP: `complete_whatsapp_embedded_signup`

## Relacionado

* [WhatsApp (texto + voz)](/channels/whatsapp)
* [Canales de mensajería](/channels/messaging)
* [Voz de WhatsApp](/telephony/whatsapp-voice)
* Meta: [Embedded Signup](https://developers.facebook.com/docs/whatsapp/embedded-signup/) · [Incorporación como Tech Provider](https://developers.facebook.com/docs/whatsapp/embedded-signup/onboarding-customers-as-a-tech-provider)