## Descripción general

Dashboard Apps incrusta una aplicación web externa en Conversa Labs. Con las **superficies nativas**
habilitadas, una persona autorizada instala cada app en la **conversación** o en la **barra lateral** de la
cuenta, controla quién puede verla y migra desde la integración heredada sin interrumpir apps existentes.

La función viene desactivada por defecto. Mientras esté desactivada, los Dashboard Apps existentes
siguen en la experiencia heredada; las pantallas y API de instalaciones nativas no están disponibles.

## Requisitos previos

- Rol **Administrador** en la cuenta o rol personalizado con permiso `integration_manage`.
- Feature `dashboard_apps_native_surfaces` habilitada en la cuenta exclusivamente por Super Admin.
- URL de la app accesible desde el navegador de todos los agentes. Usa HTTPS en producción.
- Permiso para incrustar la URL: CSP `frame-ancestors` debe permitir el origen exacto de Conversa Labs y
  no debe existir un encabezado `X-Frame-Options` incompatible.

## Paso a paso

1. Abre **Configuración → Integraciones → Dashboard Apps** y selecciona **Añadir una nueva aplicación**.
2. Indica un nombre reconocible y la URL HTTP(S) exacta. Query string y fragmento se conservan;
   úsalos solo para parámetros estáticos no sensibles como tenant, idioma o ruta.
3. En el mismo asistente, elige dónde debe aparecer la app:
   - **Conversación** muestra la app con el contexto de la conversación seleccionada.
   - **Barra lateral** la muestra a nivel de cuenta. Elige una categoría nativa — Atención,
     Contactos y CRM, Aplicaciones, Comercial, Productividad, Automatización, Crecimiento o Análisis y
     Configuración —, selecciona un icono y revisa la vista previa del elemento directo antes de guardar.
4. Elige el modo de compatibilidad:
   - **Heredado** mantiene el comportamiento anterior de mensajes del iframe durante la migración.
   - **V2** usa el puente versionado del SDK y exige un origen distinto.
   - **Dual** admite temporalmente heredado y V2 durante una migración controlada.
5. En **Datos e identidad**, revisa qué puede recibir cada instalación V2/dual. El valor completo
   incluye correo del usuario actual, identidad firmada y, en conversación, correo y teléfono del
   contacto. Desactiva solo lo que la app no necesite; nunca se conceden tokens de sesión/API. Las apps
   nativas nuevas preseleccionan V2 y muestran estas concesiones antes de crear. Heredado/dual muestra
   la advertencia sobre su contexto heredado más amplio.
6. Guarda. La app y las superficies elegidas se crean juntas, activas y visibles inicialmente para
   toda la cuenta.
7. En la tarjeta, edita cada superficie para activar o desactivar y cambiar categoría, icono, posición legible,
   capacidades o audiencia. Las posiciones usan **Primera** y **Después de...**, sin números manuales.
   Usa **Añadir ubicación** cuando quieras incluir después otro lugar.
8. En **Audiencia**, **Todos** la ofrece a los miembros elegibles. **Seleccionada** restringe por
   roles de administrador/agente, equipos y usuarios; coincidir con cualquier criterio concede acceso.
9. En la barra lateral, la app se convierte en un elemento directo de la categoría elegida. El grupo
   **Aplicaciones** queda inmediatamente debajo de **Contactos y CRM** y solo aparece cuando tiene al
   menos una app visible. La posición se normaliza por categoría; en conversación, entre pestañas.
10. Selecciona **Probar** en la ubicación configurada. La vista previa usa URL, query string, hash,
    sandbox y bridge reales. En **V2** el resultado confirma el handshake. En **Heredado** la
    validación es visual y el diálogo lo indica. En **Dual** el diálogo lista cada bridge por separado
    — fíjate en ese desglose: la atención sigue por el lane heredado aunque V2 falle, así que el
    estado general puede aparecer listo mientras la migración está bloqueada.
11. Prueba también con un administrador y un agente normal antes de ampliar la audiencia.

## Configuración y opciones

- Una app puede tener como máximo una instalación por superficie.
- La instalación expone `surface`, `compatibility_mode`, `enabled`, `position`, `sidebar_category`,
  `sidebar_icon`, `capabilities` y `audience`. Categoría e icono solo existen para la barra lateral,
  usan listas cerradas y se eligen mediante el selector visual.
- Las capacidades básicas de cuenta, usuario actual, permisos, apariencia e instalación son obligatorias.
  Conversación, contacto y mensajes existen solo en la superficie de conversación. Correo/teléfono e
  `identity:assertion` son concesiones explícitas configurables por instalación.
- La audiencia es un límite de acceso, no solo un filtro visual. Quien queda fuera no recibe la
  instalación por la interfaz ni por la API.
- Administradores y roles personalizados con `integration_manage` gestionan instalaciones y ven la
  audiencia completa. La lista de gestión puede incluir filas `visible: false` porque están desactivadas
  o fuera de la audiencia del gestor, pero nunca se montan en conversación, barra lateral ni enlace
  directo. Los demás agentes reciben solo instalaciones activas que coinciden con su rol, equipo o identidad.
- El reordenamiento es optimista: si otro administrador cambió primero, recarga la lista.

## Casos de uso

- Mostrar contexto del CRM o de pedidos junto a una conversación.
- Colocar un panel operativo de toda la cuenta en la barra lateral.
- Integrar CRM y ERP con conversaciones de correo, WhatsApp, SMS y otros inboxes mediante el mismo
  contexto omnicanal; la app recibe IDs/contexto permitidos, nunca credenciales del proveedor del canal.
- Liberar una app interna para un equipo antes de habilitarla para todos.
- Migrar una app heredada con **Dual**, validarla y después elegir **V2**.

## Consejos, límites y buenas prácticas

- Usa HTTPS y un origen separado. V2 rechaza el mismo origen porque el aislamiento forma parte del
  límite de confianza.
- Nunca pongas tokens de API, contraseñas ni datos personales en la URL. Query string y fragmento son
  útiles para parámetros estáticos, pero pueden aparecer en historial y logs del servidor de la app.
  El host conserva los parámetros y, en V2/dual, añade solo nombres `cl_*` para origen, IDs, superficie,
  protocolo e idioma. Todo nombre `cl_*` está reservado: el host elimina los valores estáticos de ese
  espacio y vuelve a escribir solo los parámetros de lanzamiento permitidos.
- La creación nativa exige exactamente un marco HTTP(S). Al habilitar la feature, Super Admin prepara
  apps heredadas con un marco e informa solo definiciones realmente incompatibles.
- Concede la audiencia mínima y revisa periódicamente equipos y usuarios.
- Trata los datos del SDK como contexto de solo lectura. Realiza cambios de negocio mediante un backend
  autenticado y la API REST, donde se aplican autorización y auditoría.
- Cuando un backend propio o n8n deba verificar quién abrió la app, usa la identidad firmada de dos
  minutos y la introspección pública. Prueba cuenta/usuario/instalación, pero no autoriza REST/MCP.
- La app puede solicitar altura y apertura de enlaces; el puente V2 no es un proxy general de API.
- HTTP puede servir en desarrollo local, pero los navegadores bloquean contenido mixto si Conversa Labs
  usa HTTPS. La advertencia HTTP no elimina esa protección.

## Solución de problemas

- **No aparecen ajustes nativos**: confirma la feature de la cuenta. La integración heredada sigue
  disponible mientras la flag esté desactivada.
- **La función no se puede habilitar**: solo Super Admin puede activarla. El operador prepara las apps
  compatibles; corrige los ID informados para que cada app tenga exactamente un marco HTTP(S).
- **El marco queda vacío o rechaza la conexión**: usa **Probar** para reproducir la configuración
  real; luego revisa CSP `frame-ancestors` y `X-Frame-Options`;
  permite el origen exacto de Conversa Labs. `X-Frame-Options: SAMEORIGIN` bloquea cualquier panel en un
  origen distinto, incluido localhost; Heredado elimina el requisito del SDK, pero no evita esta
  política del navegador.
- **HTTP funciona localmente, pero no en producción**: publica la app con HTTPS.
- **V2 informa un origen inseguro**: aloja la app en un origen distinto de Conversa Labs; cambiar solo la
  ruta no basta.
- **Un agente no ve la app**: confirma que esté activa, en la superficie correcta, y que el agente
  coincida con al menos un rol, equipo o usuario configurado.
- **No aparece el grupo Aplicaciones**: asigna al menos una app activa y visible a la categoría
  **Aplicaciones**. El grupo vacío se oculta automáticamente.
- **El orden cambió al guardar**: otro administrador puede haber reordenado la superficie. Recarga y
  envía otra vez la versión actual.
- **El handshake del SDK expira**: el panel reenvía la invitación hasta 10 segundos desde la carga del
  marco, así que un tiempo agotado significa que la aplicación no respondió en esa ventana. Empieza
  por la aplicación — debe llamar a `connect()` del SDK apenas carga su página. Luego comprueba el
  origen del dashboard pasado al SDK, los encabezados de incrustación, la versión del protocolo y
  proxies. En **Dual**, usa el desglose por bridge de **Probar** para ver el error de V2; para verlo
  crudo, cambia la instalación a **V2** temporalmente.
- **Falta correo o teléfono**: confirma V2/dual y las capacidades `current_user:email`, `contact:email`
  y `contact:phone`. Los datos del contacto solo existen en la superficie de conversación.
- **Identidad devuelve `capability_denied`**: habilita `identity:assertion` y confirma que la instalación
  esté activa, visible para el usuario y con la feature habilitada.

## Ver también

- [Integraciones: proveedores, credenciales, OAuth, webhooks y API](/hc/ajuda/articles/administration-integracoes-es)
- [SDK, API REST y MCP de Dashboard Apps](/hc/ajuda/articles/api-developers-dashboard-apps-sdk-rest-mcp-es)
- [Roles personalizados y gobernanza (RBAC)](/hc/ajuda/articles/administration-custom-roles-governanca-rbac-es)
- [Registros de auditoría](/hc/ajuda/articles/administration-auditoria-es)