Dashboard Apps: superficies nativas, audiencia y seguridad

Abrir en

Ver como Markdown

Abrir en ChatGPT Abrir en Claude

Conversa Labs

Última actualización el Aug 26, 2026

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

Abre Configuración → Integraciones → Dashboard Apps y selecciona Añadir una nueva aplicación.
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.
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.
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.
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.
Guarda. La app y las superficies elegidas se crean juntas, activas y visibles inicialmente para toda la cuenta.
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.
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.
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.
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.
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.