Skip to main content
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.
Embedded Signup v2 quedará obsoleto el 15 de octubre de 2026. Usa solo configuraciones v4.

​
Arquitectura

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

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

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