Cómo funciona WhatsApp Embedded Signup para plataformas SaaS

Si tu producto SaaS permite que cada cliente conecte su propio número de WhatsApp, necesitas más que un botón de “conectar”.

WhatsApp no es solo una credencial de API. Una conexión real incluye un Meta Business Portfolio, una cuenta de WhatsApp Business, un número, permisos, estado de revisión, estado de pago, webhooks y una forma clara de saber qué cliente de tu producto es dueño de ese número.

Embedded Signup es el flujo hospedado por Meta para que el cliente entregue esa conexión. Kapso lo convierte en una primitiva de producto: un enlace de conexión para cada cliente.

La versión corta

Para una plataforma SaaS, Embedded Signup es el flujo de “conectar WhatsApp” que tu cliente completa dentro de una ventana controlada por Meta.

El cliente inicia sesión con Facebook o credenciales de Meta Business, elige o crea los activos del negocio, acepta los términos requeridos, otorga permisos y conecta un número de WhatsApp. Cuando el flujo termina, tu plataforma recibe identificadores como el ID de la cuenta de WhatsApp Business y el ID del número.

Tu producto debería tratar esto como un ciclo de vida:

1. Crear o identificar al cliente y generar un enlace de conexión para él.
2. Dejar que el cliente complete el flujo de Meta.
3. Detectar la conexión con redirects, webhooks o ambos.
4. Guardar el phone_number_id conectado y usarlo para mensajes, webhooks, workflows e inbox.

Qué controla Meta

Meta controla la interfaz de Embedded Signup y las validaciones de plataforma.

Eso incluye:

• Autenticación con Facebook o Meta.
• Selección o creación del Business Portfolio.
• Selección o creación de la cuenta de WhatsApp Business.
• Verificación o emparejamiento del número.
• Aceptación de términos.
• Permisos otorgados a la app.
• Revisión del display name, verificación del negocio, revisión del WABA, pagos y restricciones de cuenta.

Tu app puede iniciar el flujo y completar la conexión, pero no puede saltarse los requisitos de Meta. Si el negocio tiene información legal incompleta, un WABA en revisión, problemas de pago o un número bloqueado, la conexión puede fallar o quedar pendiente.

Qué debe modelar tu producto

Tu producto controla la relación con el cliente y el modelo de datos alrededor de la conexión.

Como mínimo, guarda:

El error común es guardar solo el número final. En producción, casi todos los problemas de soporte viven en el estado intermedio: qué negocio completó el flujo, qué número eligió, si Meta devolvió al usuario a la app, si llegó el webhook y si el WABA sigue en revisión.

Dedicated vs coexistencia con WhatsApp Business App

Hay dos modos frecuentes.

Dedicated Cloud API es API-first. El número queda en la WhatsApp Business Platform y está pensado para escala. Para plataformas, la configuración predeterminada de Kapso es una conexión dedicated con provisión de número, sin impedir que el equipo elija coexistencia cuando la Business App debe seguir activa.

La coexistencia con WhatsApp Business App permite que el cliente siga usando la app en su teléfono mientras Kapso también recibe eventos por API. Es útil para negocios pequeños que necesitan operación humana en la app y automatización en paralelo.

La coexistencia es conveniente, pero tiene más casos límite. El cliente debe ver el flujo de QR, conexiones antiguas con otros proveedores pueden bloquear el onboarding y a veces hay que limpiar estado residual dentro de Meta. Si tu producto necesita automatización estable y alto volumen, usa dedicated. Si vendes a negocios pequeños que viven en WhatsApp Business App, coexistencia puede ser la mejor experiencia.

Cómo lo implementa Kapso

En Kapso, creas un cliente, generas un enlace de conexión y se lo entregas a ese cliente. El cliente completa el flujo de Meta. Kapso finaliza la conexión y tu producto recibe los identificadores que necesita.

Cuando usas enlaces hospedados por Kapso, tu producto consume APIs y webhooks de Kapso en vez de pedirle al cliente tokens de acceso de Meta directamente.

curl -X POST https://api.kapso.ai/platform/v1/customers/{customer_id}/setup_links \
  -H "X-API-Key: $KAPSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "setup_link": {
      "success_redirect_url": "https://app.example.com/whatsapp/success",
      "failure_redirect_url": "https://app.example.com/whatsapp/failed",
      "allowed_connection_types": ["dedicated"],
      "provision_phone_number": true
    }
  }'

El enlace puede configurar:

• URLs de éxito y error.
• Idioma, incluyendo español, inglés y portugués.
• Tipos de conexión permitidos.
• Provisión de número.
• Colores del onboarding hospedado.
• Reconexión de un número existente.

Los enlaces expiran después de 30 días. Al crear un enlace nuevo, el enlace activo anterior se revoca para ese cliente.

Si el cliente estaba usando un enlace antiguo cuando generas uno nuevo, tu producto debería tratar el anterior como inválido. Muestra siempre el enlace más reciente y deja claro en soporte cuál intento de conexión sigue activo.

Cómo detectar que terminó

Usa redirects y webhooks cuando puedas.

Los redirects sirven para la UX. Permiten mostrar “conectado”, “pendiente” o “intenta de nuevo” cuando el cliente vuelve desde Meta.

Los webhooks sirven como verdad de backend. Un webhook de proyecto como whatsapp.phone_number.created permite guardar el phone_number_id, reconciliar estado y continuar el aprovisionamiento.

El redirect puede perderse si el cliente cierra la ventana. El webhook puede llegar después de que la pantalla cambió. Juntos hacen que el flujo sea más robusto.

Checklist antes de publicar el flujo

Antes de mostrar este flujo a tus clientes, tu producto debería poder responder:

• ¿Qué cliente es dueño de esta conexión?
• ¿Qué tipo de conexión ofrecimos?
• ¿El cliente terminó el flujo de Meta o lo abandonó?
• ¿Qué phone_number_id quedó conectado?
• ¿Qué WABA se usa para gestionar plantillas?
• ¿El número está pendiente de revisión?
• ¿Qué webhook confirmó la conexión?
• ¿Cómo se reconecta si Meta revoca credenciales?
• ¿Qué datos de soporte mostramos cuando Meta bloquea el flujo?

La mejor experiencia de “conectar WhatsApp” parece simple porque el producto ya hizo el trabajo de modelar el estado.

Dónde entra Kapso

Kapso es útil cuando el onboarding de WhatsApp es parte de tu producto, no una integración aislada.

Con Kapso Platform puedes mapear tenants a clientes de Kapso, generar enlaces de conexión, detectar conexiones completadas, enviar desde el número del cliente, suscribirte a webhooks, usar Workflows y llevar conversaciones a un inbox cuando una persona debe tomar control.

Embedded Signup conecta los activos de WhatsApp. Tu producto todavía necesita una capa operativa alrededor de esos activos. Kapso da esa capa.