Conectar WhatsApp vía Meta (Cloud API)

Objetivo

Guiar paso a paso la configuración de Meta WhatsApp Cloud API para conectar un número de WhatsApp Business directamente a Helios, sin intermediarios como Twilio.

Ventajas sobre Twilio

• Menor costo: sin markup de intermediario, solo tarifas de Meta.
• Control directo: gestionas tu propia app en Meta for Developers.
• Actualizaciones inmediatas: acceso a las últimas funciones de WhatsApp API.

Sobre las "1,000 conversaciones gratis al mes" de Meta: ese plan gratuito existe, pero NO aplica a números con IA. Meta clasifica las integraciones de IA como uso pagado, así que incluso el trafico de prueba se cobra. Sin un metodo de pago configurado, Meta descarta silenciosamente cada mensaje entrante — ver Paso 8.

Requisitos previos

Antes de comenzar, asegurate de tener:

• Cuenta de Meta for Developers (gratuita, puedes usar tu cuenta de Facebook).
• Cuenta de Meta Business (se crea automáticamente al crear la app, o puedes usar una existente).
• Número de teléfono para WhatsApp Business (no puede estar registrado en WhatsApp personal; si lo esta, debes desvincularlo primero).
• Un metodo de pago válido (tarjeta de crédito o debito) para asociar a la WABA. El costo es mínimo (~$0.005-$0.02 USD por conversación), pero Meta lo exige para números con IA.
• Acceso de admin u owner al portal Helios.
• Un agente creado en Helios con el canal WhatsApp habilitado.

---

Lo que Helios automatiza por ti

Tres pasos de configuración que historicamente hacian fallar silenciosamente a tenants nuevos ahora los maneja Helios cuando haces clic en Connect Number:

Helios hace esto por ti — no necesitas hacerlo en Meta:

• Webhook URL se genera a partir de tu dominio de producción (no la construyes a mano).
• Verify Token se genera como string aleatorio seguro (hv_...).
• Suscripción app-WABA se registra contra Graph API de Meta (POST /{waba_id}/subscribed_apps) para que tu app realmente reciba webhooks. Este es el paso que casi todas las respuestas de StackOverflow olvidan.
• Auto-detección de WABA ID: si solo proporcionas el Phone Number ID + Access Token, Helios consulta Meta y completa el Business Account ID por ti.

Aun así necesitas hacer los Pasos 1-7 en Meta tu mismo (crear la app, agregar el teléfono, generar el token, configurar la URL/Token del webhook en el dashboard de Meta). El concepto de los dos niveles de suscripción se explica en el Paso 7.

---

Parte 1: Configuración en Meta

Paso 1 — Crear tu cuenta de Meta Business y de developer

1. Ve a Meta Business Suite y crea una cuenta Business (omite si ya tienes una).
2. Ve a Meta for Developers e inicia sesión con la misma cuenta de Facebook que es duena del Business.

Paso 2 — Crear app en Meta for Developers

1. En Meta for Developers, haz clic en Mis apps (My Apps) → Crear app (Create App).
2. Selecciona el tipo Empresa (Business).
3. Completa la información:
   • Nombre de la app: nombre descriptivo (ej. "Mi Empresa WhatsApp Bot").
   • Email de contacto: tu email de empresa.
   • Portfolio empresarial: selecciona tu portfolio existente.
4. Haz clic en Crear app.

Paso 3 — Agregar el producto WhatsApp y un número de teléfono

1. Después de crear la app, llegaras al dashboard.
2. En el menu lateral, abre Use Cases y elige "Connect with customers through WhatsApp" → haz clic en Customize.
3. Selecciona o crea una Cuenta de WhatsApp Business (WABA):
   • Si ya tienes una: seleccionala.
   • Si no: puedes crearla aquí mismo, o previamente en Meta Business Suite → Más herramientas → Administrador de WhatsApp.
4. Dentro de Customize, ve a Production setup. Aquí vive todo lo que antes encontrabas bajo "API Setup" / "Configuration": las tarjetas Register your WhatsApp phone number, Configure Webhooks y Add payment to send business-initiated messages están todas aquí.
5. En la tarjeta Register your WhatsApp phone number, Meta te asigna un número de prueba gratuito que puedes usar de inmediato. Para usar tu propio número de producción, haz clic en Add phone number, ingresa tu número de empresa y verificalo con el código SMS o llamada.

Nota: El número que agregues no puede estar registrado en WhatsApp personal. Si lo esta, elimina WhatsApp del teléfono y espera unos minutos antes de agregarlo aquí.

Paso 4 — Crear token permanente (System User Token)

El token temporal que aparece en Production setup expira en ~24 horas. Para producción necesitas un System User Token:

1. Ve a Meta Business Suite.
2. Haz clic en Configuración (Settings) → Usuarios del sistema (System Users).
3. Haz clic en Agregar para crear un nuevo usuario del sistema:
   • Nombre: solo letras minusculas y guiones bajos (ej. helios_whatsapp).
   • Rol: Admin.
4. Una vez creado, selecciona el System User y haz clic en Asignar activos (Add Assets):
   • Apps → elige tu app de WhatsApp → activa Manage app (y Control total / Full Control si aparece) → Guarda.
   • Cuentas de WhatsApp → ADEMAS agrega la WhatsApp Business Account como activo y otorga Control total (Full Control) → Guarda. Sin esto, el paso de conexion en Helios fallara con missing_permissions cuando intente enlazar la app a tu WABA via Graph API.
5. Haz clic en Generar identificador (Generate Token) en ese usuario.
6. Selecciona tu app de WhatsApp y marca los permisos:
   • whatsapp_business_management
   • whatsapp_business_messaging
7. Haz clic en Generar token y copialo. Es permanente, pero solo se muestra una vez.

Paso 5 — Obtener el App Secret

1. En el menu lateral de tu app en Meta, ve a Configuración (Settings) → Básica (Basic).
2. Busca Clave secreta de la aplicación (App Secret), haz clic en Mostrar, ingresa tu contraseña de Facebook.
3. Copia el App Secret.

El App Secret permite a Helios verificar que los webhooks realmente provienen de Meta (firma HMAC-SHA256). Es altamente recomendado configurarlo.

---

Parte 2: Pegar credenciales en Helios

Paso 6 — Conectar número en Helios

1. En Helios, ve a WhatsApp en el sidebar.
2. Haz clic en Connect New Number → selecciona Meta Cloud API.
3. Completa los campos:

4. Haz clic en Test Connection para verificar (devuelve el nombre verificado de tu cuenta y el quality rating).
5. Marca Active si quieres que el número quede listo para recibir mensajes.
6. Haz clic en Connect Number. En este punto Helios llama a Graph API de Meta para enlazar tu app con la WABA — el hueco silencioso de webhook que rompia muchas integraciones en el pasado.

Nota: Si al hacer clic en "Connect Number" parece que no pasa nada, revisa la zona del botón — puede haber un error de validación oculto como Display Name faltante o Assigned Agent sin asignar.

Editar conexion Meta existente

• Las credenciales encriptadas (Access Token y App Secret) muestran un indicador "Saved" — los valores reales no se exponen por seguridad.
• Puedes mantenerlas o reemplazarlas con nuevos valores.
• Test Connection funciona con las credenciales almacenadas, no necesitas reingresarlas.

---

Parte 3: Configurar webhook en Meta

Paso 7 — Registrar URL del webhook

Aquí es donde Meta tiene dos niveles de suscripción separados, y confundirlos le cuesta días de debugging a mucha gente:

1. Suscripción a campos a nivel de app (la haces tu — Paso 7).
2. Suscripción app-WABA a nivel de WABA (la hace Helios por ti — ver "Lo que Helios automatiza por ti").

Ambas deben estar activas para que lleguen webhooks. Ahora configura la suscripción a campos:

1. Regresa a Meta for Developers, en tu app.
2. En el menu lateral, abre Use Cases → "Connect with customers through WhatsApp" → Customize → Production setup.
3. Busca la tarjeta Configure Webhooks y haz clic en Configure (o Edit si ya estaba configurado).
4. Completa los campos:
   • URL de devolución de llamada: pega la Webhook URL que muestra Helios (ej. https://heliosvisionai.com/api/whatsapp/webhook).
   • Identificador de verificación: pega el Webhook Verify Token de Helios (hv_...).
5. Haz clic en Verificar y guardar. Meta envía un GET a tu URL para confirmar que el token coincide.
6. Meta normalmente suscribe el campo messages por ti automáticamente como parte del mismo paso. Si quieres confirmarlo (5 segundos), abre WhatsApp → Configuration → Webhook fields (la página antigua que expone los toggles a nivel de campo), busca la fila de messages y verifica que diga Subscribed (verde). Si dice Unsubscribed, haz clic en Subscribe. Mientras estas ahi, también puedes suscribir message_status para recibir confirmaciones de entrega / lectura.

Si falla la verificación: confirma que la URL sea HTTPS, que el dominio sea accesible publicamente (no localhost) y que el token coincida exactamente con el generado por Helios.

---

Parte 4: Metodo de pago y publicación de la app

Estos dos últimos pasos estuvieron sin documentar demasiado tiempo. Saltarse cualquiera de los dos produce el mismo sintoma exacto: cero mensajes entrantes, sin error en el dashboard.

Paso 8 — Agregar metodo de pago (obligatorio para números con IA)

El plan gratuito de "1,000 conversaciones al mes" de Meta excluye explicitamente a los números con IA. Sin metodo de pago, Meta descarta silenciosamente cada mensaje entrante — no hay error en el dashboard de Meta, no hay rechazo en Helios, solo silencio.

1. Ve a Use Cases → "Connect with customers through WhatsApp" → Customize → Production setup.
2. Busca la tarjeta "Anadir un metodo de pago para enviar mensajes iniciados por la empresa" (la frase también cubre el trafico iniciado por IA).
3. Haz clic en Anadir metodo de pago e ingresa tu tarjeta.
4. Guarda.

Realidad de costos: ~$0.005-$0.02 USD por conversación según el pais. Unos centavos te alcanzan para hacer pruebas extensas.

Paso 9 — Publicar la app (App Mode → Live)

Las apps en modo Desarrollo nunca entregan webhooks de producción reales — ni siquiera para los admins ni testers de la app. El dashboard de Meta lo menciona, pero es fácil pasarlo por alto.

1. En el sidebar izquierdo de tu app, haz clic en Dashboard (Panel).
2. Busca el panel "Comprueba que se cumplen todos los requisitos y publica tu app".
3. Completa los requisitos básicos (Meta los lista):
   • URL de Política de Privacidad — obligatoria.
   • URL de Terminos de Servicio — obligatoria.
   • URL de Eliminación de Datos — obligatoria.
   • Icono de la App (PNG 1024x1024).
   • Categoría: "Negocios y páginas".
   • Descripción del uso empresarial (un párrafo corto sobre tu caso de uso).
4. Cuando los requisitos esten completos, la página te redirige a Publicar, con el botón ahora habilitado. Haz clic en Publicar.

Que URLs pego en Privacidad / Terminos / Eliminación de Datos?

• Ideal: usa tus propias páginas legales si ya las publicas (ej. https://tuempresa.com/privacidad). Identifican a tu negocio como responsable del tratamiento, que es exactamente lo que Meta quiere ver.
• Alternativa: Helios genera páginas legales por tenant listas para usar en:
  • https://heliosvisionai.com/privacy/{tu-slug}
  • https://heliosvisionai.com/terms/{tu-slug}
  • https://heliosvisionai.com/data-deletion/{tu-slug}

Puedes obtener las URLs exactas (con botón de copiar en un clic) y editar el nombre de tu negocio, datos de contacto, dirección y clausulas opcionales específicas de tu industria en Helios bajo Settings → Legal & Compliance. La misma página te permite sobreescribir cualquiera de las tres URLs con tu propio enlace externo (Helios redirige a Meta con 302).

Por que URLs por tenant y no el /privacy de la plataforma: bajo GDPR/CCPA tu eres el responsable del tratamiento de los datos de tus clientes; Helios es solo el encargado del tratamiento. La revisión de Meta espera que las URLs describan a tu negocio — nombre, contacto, declaraciones sobre datos sensibles — no a la plataforma subyacente. Las URLs por tenant hacen exactamente eso; el https://heliosvisionai.com/privacy de la plataforma describe a Helios y no pasara una revisión de tenant.

Trampa de UX: si haces clic en Publicar del sidebar antes de completar los campos básicos, verás un botón deshabilitado sin un proximo paso claro. La ruta que de verdad funciona es Dashboard → Comprobar requisitos → completar campos → te redirige a Publicar.

No requiere App Review formal: WhatsApp Business Messaging no necesita revisión formal de la app. El modo Live se activa al instante en cuanto los campos básicos están completos.

Paso 10 — Haz clic en Connect Number

Ya elegiste el agente y activaste Active en la parte superior de este formulario, así que lo único que falta es hacer clic en Connect Number abajo. Helios suscribira automáticamente esta app a tu WhatsApp Business Account para que los mensajes entrantes lleguen al webhook — NO necesitas hacer esto en Meta. Envía un WhatsApp de prueba desde otro teléfono y tu agente deberia responder en pocos segundos.

Si el mensaje llega a Helios pero no genera respuesta, revisa:

• Que el agente asignado tenga el canal WhatsApp habilitado.
• Que el agente tenga un system prompt configurado.
• Los logs del servidor para errores en el procesamiento.

---

Fallas silenciosas comunes (sin error, sin mensaje)

Estos tres son los sospechosos de siempre cuando "todo se ve bien pero no llega nada". Helios resuelve el tercero por ti, pero los dos primeros siguen siendo tu responsabilidad:

---

Códigos de error de conexion

Cuando Helios no logra conectar o enlazar tu número, el modal muestra uno de estos códigos (devueltos por la server action como meta_bind:<codigo>):

---

Token Temporal vs Permanente

Para producción, siempre usa un System User Token. Si usas el temporal, tu integración dejara de funcionar cuando expire.

---

Costos de Meta Cloud API

Meta cobra por conversación (ventana de 24 horas), no por mensaje individual:

Consulta precios actualizados de Meta para tu region.

---

Otros errores comunes

---

Resumen rápido (checklist)

• Paso 1: Cuenta de Meta Business + Meta for Developers
• Paso 2: Crear app en Meta for Developers (tipo Business)
• Paso 3: Agregar producto WhatsApp, vincular WABA, agregar número
• Paso 4: System User Token permanente con whatsapp_business_management + whatsapp_business_messaging (Control Total sobre App Y Cuenta de WhatsApp)
• Paso 5: Copiar App Secret desde Settings → Basic
• Paso 6: En Helios, pegar credenciales → Test Connection → Connect Number (Helios auto-enlaza la WABA)
• Paso 7: En Meta (Use Cases → Connect with customers through WhatsApp → Customize → Production setup → Configure Webhooks), pegar Webhook URL + Verify Token → Verificar y Guardar → confirmar que messages este Subscribed en WhatsApp → Configuration → Webhook fields
• Paso 8: Agregar metodo de pago (obligatorio para números con IA)
• Paso 9: Publicar la app (Dashboard → Comprobar requisitos → Publicar)
• Paso 10: Hacer clic en Connect Number en Helios (Helios auto-suscribe la app a tu WABA), luego enviar un WhatsApp de prueba desde otro teléfono y confirmar que el agente responde

---

Relacionados

• whatsapp — Manual general de WhatsApp (gestionar conversaciones, chat, notificaciones)
• twilio-setup — Configuración alternativa con Twilio
• integrations — Integraciones generales