Conectar WhatsApp vía Meta (Cloud API)

Objetivo

Conecta un número de WhatsApp Business a Helios directamente a través de la Meta WhatsApp Cloud API, sin un intermediario como Twilio. Creas y configuras una app en Meta for Developers, pegas las credenciales en Helios y Helios se encarga de las partes que históricamente causaban fallas silenciosas (la suscripción de la WhatsApp Business Account, el verify token y la webhook URL).

Meta Cloud API es el proveedor recomendado: pagas las tarifas propias de Meta sin markup de intermediario, mantienes control directo de tu app y accedes primero a las nuevas funciones de la WhatsApp API.

Acceso

Sidebar -> WhatsApp

Ruta: /app/{tenant}/whatsapp

La guía de configuración de Meta está integrada en el flujo de conexión: haz clic en Connect New Number, elige Meta Cloud API y la guía paso a paso (junto con la Webhook URL y el Verify Token que necesitarás) aparece en la parte superior del formulario.

Roles

• Ver la página de WhatsApp y las conversaciones: owner, admin, agent (la cuenta debe estar activa).
• Conectar, editar o eliminar un número (el flujo de esta guía): solo owner o admin.
• Message Templates: owner o admin, y solo para conexiones Meta.
• Un onboarding más rápido de un clic (Connect with WhatsApp) se está habilitando de forma gradual. Si no lo ves, esta guía manual funciona para todos — contacta a soporte para confirmar disponibilidad.

Requisitos previos

Antes de comenzar, asegúrate de tener:

• Un plan que incluya WhatsApp y capacidad de números disponible. Sin esto, la acción de conectar devuelve un aviso de upgrade.
• Una cuenta de Meta for Developers (gratuita — puedes usar tu cuenta de Facebook).
• Una cuenta de Meta Business (se crea automáticamente al crear la app, o reutiliza una existente). La verificación de negocio es opcional para empezar.
• Un número de teléfono para WhatsApp Business que no esté registrado en WhatsApp personal. Registrarlo aquí lo desvincula de la app de consumo.
• Un método de pago válido (tarjeta de crédito o débito) para asociar a la WhatsApp Business Account (WABA). El costo es mínimo (~$0.005–$0.02 USD por conversación), pero Meta lo exige para números con IA.
• Un agente activo y con el canal WhatsApp habilitado (un número solo puede quedar Active cuando se elige un agente asignable).

Sobre las "1,000 conversaciones de servicio gratis al mes" de Meta: ese plan gratuito existe, pero no aplica a números con IA. Sin un método de pago configurado, Meta descarta silenciosamente cada mensaje entrante — sin error en el dashboard de Meta, sin rechazo en Helios. Ver Paso 8.

---

Lo que Helios automatiza por ti

Varios pasos de configuración que antes hacían fallar silenciosamente a los tenants nuevos 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_...) y se guarda antes de que lo pegues en Meta, de modo que el GET de verificación de Meta pasa mientras aún completas el formulario.
• Suscripción app-WABA a nivel de WABA se registra contra la Graph API de Meta (POST /{waba_id}/subscribed_apps) para que tu app realmente reciba webhooks. Este es el paso que casi todas las guías olvidan.
• Auto-detección del Business Account ID: si solo proporcionas el Phone Number ID + Access Token, Helios consulta Meta y completa el Business Account ID por ti.
• Tras un Test Connection / Connect Number exitoso, Helios limpia cualquier marca de "unhealthy" que quedara de un token anterior.

Aun así, los Pasos 1–7 en Meta los haces tú (crear la app, registrar el teléfono, generar el token y configurar la webhook URL/Token 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 o abrir tu cuenta de Meta Business

1. Ve a Meta Business Suite e inicia sesión con tu cuenta personal de Facebook.
2. Si aún no tienes una cuenta de Meta Business, haz clic en Create account y completa el nombre de tu negocio, tu nombre y un email de contacto. La verificación de negocio es opcional para empezar — puedes lanzar sin ella.

Paso 2 — Crear una app de developer y agregar WhatsApp

1. Ve a Meta for Developers → My Apps → Create App.
2. Elige el tipo Business y ponle el nombre que quieras (solo tú lo ves).
3. Asóciala con tu cuenta de Meta Business y haz clic en Create App.
4. Desde el dashboard de la app, busca la tarjeta del producto WhatsApp y haz clic en Set Up. Acepta los términos de WhatsApp Business.

Paso 3 — Registrar tu número de WhatsApp

1. En el sidebar de tu app: Use Cases → "Connect with customers through WhatsApp" → Customize → Production setup.
2. Selecciona o crea una WhatsApp Business Account (WABA). Puedes crearla aquí mismo, o previamente en Meta Business Suite → WhatsApp Manager.
3. 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, completa el nombre verificado del negocio, la categoría y la zona horaria, y verifícalo con el código SMS o de llamada.

Advertencia: El número que registras queda desvinculado de WhatsApp personal y solo funciona vía la API. Usa un número de negocio dedicado, o prepárate para perder ese número en tu WhatsApp normal. Si está actualmente en WhatsApp, desinstala la app y espera unos minutos antes de registrarlo aquí.

Paso 4 — Generar un token permanente (System User Token)

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

1. Ve a Meta Business Suite → Settings → Users → System Users.
2. Haz clic en Add para crear un usuario con rol Admin.
3. Selecciona el System User → Add Assets:
   • Apps → elige tu app de WhatsApp → activa Manage app → Guarda.
   • WhatsApp Accounts → agrega además la WhatsApp Business Account y otorga Full Control → Guarda. Sin esto, Helios falla con missing_permissions cuando enlaza la app a tu WABA.
4. Haz clic en Generate new token, selecciona tu app y marca los permisos:
   • whatsapp_business_management
   • whatsapp_business_messaging
5. Haz clic en Generate token y cópialo de inmediato — Meta lo muestra solo una vez. No expira.

Paso 5 — Obtener el App Secret

1. En el menú lateral de tu app, ve a Settings → Basic.
2. Busca App Secret, haz clic en Show e 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 opcional, pero muy recomendado.

---

Parte 2: Pegar credenciales en Helios

Paso 6 — Conectar el número en Helios

1. En Helios, abre 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. Si tiene éxito verás "Verified: <nombre de tu negocio>" (con el quality rating cuando Meta lo devuelve). Si Display Name está vacío, Helios lo completa con el nombre verificado.
5. Marca Active para que el número quede listo para recibir mensajes.
6. Haz clic en Connect Number. En este punto Helios llama a la Graph API de Meta para enlazar tu app con la WABA — el hueco silencioso de webhook que rompía muchas integraciones en el pasado.

Nota: La Webhook URL y el Webhook Verify Token que pegarás en Meta en el Paso 7 aparecen en la parte superior de este mismo formulario. El verify token (hv_...) se genera y guarda apenas se abre el formulario, así que la verificación de Meta funciona mientras aún estás aquí. Usa Regenerate solo si necesitas un token nuevo.

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 "Active WhatsApp numbers must have an assigned agent".

Editar una conexión Meta existente

• Las credenciales encriptadas (Access Token y App Secret) muestran un indicador "Saved" — los valores reales nunca se muestran.
• Mantenlas, o haz clic en Replace with new token / Replace with new secret para ingresar nuevos valores.
• Test Connection funciona con las credenciales almacenadas — no necesitas reingresarlas.
• El control de acceso por teléfono (listas de permitidos/bloqueados) está disponible solo en modo edit.

---

Parte 3: Configurar el webhook en Meta

Paso 7 — Registrar la URL del webhook

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 tú (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. De vuelta en Meta for Developers, en tu app: Use Cases → "Connect with customers through WhatsApp" → Customize → Production setup.
2. Busca la tarjeta Configure Webhooks y haz clic en Configure (o Edit si ya estaba configurado).
3. Completa los campos:
   • Callback URL: pega la Webhook URL que muestra Helios (ej. https://heliosvisionai.com/api/whatsapp/webhook).
   • Verify Token: pega el Webhook Verify Token de Helios (hv_...).
4. Haz clic en Verify and Save. Meta envía un GET a tu URL para confirmar que el token coincide.
5. Meta normalmente suscribe el campo messages por ti como parte de este paso. Para confirmarlo (5 segundos), abre WhatsApp → Configuration → Webhook fields, busca la fila de messages y verifica que diga Subscribed (verde). Mientras estás ahí, 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 públicamente (no localhost) y que el token coincida exactamente con el generado por Helios.

---

Parte 4: Método de pago y publicación de la app

Saltarse cualquiera de estos dos últimos pasos produce el mismo síntoma: cero mensajes entrantes, sin error en ningún lado.

Paso 8 — Agregar método de pago (obligatorio para números con IA)

El plan gratuito de Meta de 1,000 conversaciones de servicio al mes no cubre los números con IA. Sin método de pago, Meta descarta silenciosamente cada mensaje entrante — sin error en el dashboard de Meta, sin rechazo en Helios, solo silencio.

1. Ve a Use Cases → "Connect with customers through WhatsApp" → Customize → Production setup.
2. Busca la tarjeta "Add payment to send business-initiated messages" (la frase también cubre el tráfico iniciado por IA).
3. Haz clic en Add payment method, ingresa tu tarjeta y guarda.

Realidad de costos: ~$0.005–$0.02 USD por conversación de servicio según el país. Unos centavos te alcanzan para pruebas extensas.

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

Las apps en modo Development nunca entregan webhooks de producción reales — ni siquiera para admins ni testers de la app. Meta retiene cada mensaje entrante de su lado y tu webhook no recibe nada.

1. En el dashboard de tu app, busca "Check that all requirements are met, then publish your app".
2. Completa los requisitos básicos que Meta lista:
   • Privacy Policy URL — obligatoria.
   • Terms of Service URL — obligatoria.
   • Data Deletion URL — obligatoria.
   • App Icon (PNG 1024x1024).
   • Category: "Business and Pages".
   • Business use description (un párrafo corto sobre tu caso de uso).
3. Cuando los requisitos estén completos, Meta habilita el botón Publish. Haz clic en Publish.

No requiere App Review: 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.

¿Qué URLs uso para Privacy / Terms / Data Deletion?

• Ideal: tus propias páginas legales si ya las publicas (ej. https://tuempresa.com/privacy). 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:
  • https://heliosvisionai.com/privacy/{your-slug}
  • https://heliosvisionai.com/terms/{your-slug}
  • https://heliosvisionai.com/data-deletion/{your-slug}

Obtén las URLs exactas (con copiar en un clic) y edita el nombre de tu negocio, datos de contacto y dirección en Helios bajo Settings → Legal & Compliance. La misma página te permite sobreescribir cualquiera de las tres con tu propio enlace externo.

Por qué URLs por tenant y no el /privacy de la plataforma: bajo GDPR/CCPA tú 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 — no a la plataforma subyacente. La página a nivel de plataforma describe a Helios y no pasará una revisión de tenant.

Paso 10 — Haz clic en Connect Number

Ya elegiste el agente y activaste Active en la parte superior del formulario, así que lo único que falta es hacer clic en Connect Number. Helios suscribe automáticamente esta app a tu WhatsApp Business Account para que los mensajes entrantes lleguen al webhook — no haces esto en Meta. Envía un WhatsApp de prueba desde otro teléfono y tu agente debería 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 de procesamiento.

---

Fallas silenciosas comunes (sin error, sin mensaje)

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

---

Códigos de error de conexión

Cuando Helios no logra conectar o enlazar tu número, el modal muestra un mensaje accionable. Internamente estos mapean a códigos tipados (meta_bind:<code>):

---

Token temporal vs permanente

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

---

Costos de Meta Cloud API

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

Consulta los precios actualizados de Meta para tu región.

---

Buenas prácticas

• Usa un número de negocio dedicado que estés dispuesto a desvincular de WhatsApp de consumo.
• Usa siempre un System User Token para producción — nunca dejes el token temporal de ~24 horas.
• Agrega el App Secret para que las firmas de los webhooks se verifiquen (HMAC-SHA256).
• Ejecuta Test Connection antes de guardar; un resultado verde "Verified" confirma el token y el Phone Number ID antes de que Helios intente el bind de la WABA.
• Agrega el método de pago y publica la app antes de esperar tráfico real — ambos fallan en silencio cuando faltan.

---

Errores comunes

---

Resumen rápido (checklist)

• Paso 1: Cuenta de Meta Business
• Paso 2: Crear app (tipo Business) y agregar el producto WhatsApp
• Paso 3: Registrar tu número de WhatsApp bajo una WABA
• Paso 4: System User Token permanente con whatsapp_business_management + whatsapp_business_messaging (Full Control sobre la WhatsApp Account, Manage app sobre la App)
• Paso 5: Copiar el App Secret desde Settings → Basic
• Paso 6: En Helios, pegar credenciales → Test Connection → Connect Number (Helios auto-enlaza la WABA)
• Paso 7: En Meta, pegar la Webhook URL + Verify Token → Verify and Save → confirmar que messages esté Subscribed
• Paso 8: Agregar un método de pago (obligatorio para números con IA)
• Paso 9: Publicar la app (Development → Live)
• Paso 10: Enviar un WhatsApp de prueba desde otro teléfono y confirmar que el agente responde

---

Relacionado

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