Dashboard Apps: native surfaces, audience and security

Overview

Dashboard Apps embed an external web application inside Conversa Labs. With native surfaces enabled, an authorized manager can install each app in the conversation or the account sidebar, control who can see it, and migrate from the legacy integration without interrupting existing apps.

The feature switch is deliberately off by default. While it is off, existing Dashboard Apps continue to use the legacy conversation experience; native installation screens and APIs are unavailable.

Prerequisites

An account Administrator, or a custom role with integration_manage permission.
The dashboard_apps_native_surfaces feature enabled for the account exclusively by Super Admin.
An app URL reachable from every agent's browser. Use HTTPS in production.
Permission for the app URL to be embedded: its CSP frame-ancestors policy must allow the exact Conversa Labs origin, and it must not send a conflicting X-Frame-Options header.

Step by step

Open Settings → Integrations → Dashboard Apps and select Add a new dashboard app.
Enter a recognizable name and the exact HTTP(S) URL. Query strings and fragments are preserved; use them only for non-sensitive static parameters such as tenant, language, or route.
In the same guided form, choose where the app should appear:
- Conversation displays it with the selected conversation context.
- Sidebar displays it at account level. Choose one of the native categories — Support, Contacts & CRM, Applications, Commercial, Productivity, Automation, Growth, or Analytics & Settings —, select an icon, and review the direct-item preview before saving.
Choose the compatibility mode:
- Legacy keeps the previous iframe messaging behavior while you migrate.
- V2 uses the versioned Dashboard App SDK bridge and requires a distinct origin.
- Dual temporarily supports legacy and V2 during a controlled migration.
Under Data and identity, review what each V2/dual installation may receive. The complete default includes current-user email, signed identity and, in conversations, contact email and phone. Disable only what the app does not need; session/API tokens are never granted. New native apps preselect V2 and show these grants before creation. Legacy/dual displays its broader legacy-context warning.
Save. The app and selected surfaces are created together, enabled and initially visible to the whole account.
On the app card, edit each surface to enable or disable it and change its category, icon, readable position, capabilities, or audience. Positions use First and After..., with no manual numbers. Use Add location later when you want to include a location that is not configured yet.
Under Audience, All makes it available to eligible account members. Selected can restrict it to administrator/agent roles, teams and individual users; matching any selected criterion grants visibility.
A sidebar app becomes a direct item in the selected category. The Applications group sits immediately below Contacts & CRM and appears only when at least one visible app is assigned to it. Position is normalized per category; conversation positions are normalized among app tabs.
Select Test on the configured location. The preview uses the real URL, query string, hash, sandbox, and bridge. Under V2 the result confirms the handshake. Under Legacy validation is visual and the dialog says so. Under Dual the dialog lists each bridge separately — read that breakdown: agents keep working through the legacy lane even when V2 fails, so the overall status can read ready while the migration is blocked.
Also test with one administrator and one regular agent before expanding the audience.

Settings & options

One app can have at most one installation on each surface.
An installation exposes surface, compatibility_mode, enabled, position, sidebar_category, sidebar_icon, capabilities, and audience. Category and icon exist only on sidebar resources, use closed enums, and are selected through the visual picker.
Core account, current-user, permissions, appearance and installation capabilities are required. Conversation, contact and message capabilities exist only on the conversation surface. Email/phone and identity:assertion are explicit grants configurable per installation.
Audience is an access boundary, not merely a visual filter. A user who is outside it must not receive that installation through the interface or API.
Administrators and custom roles with integration_manage can manage installations and inspect audience details. Their management list can include visible: false rows because they are disabled or outside the manager's own audience, but those rows never mount in conversation, sidebar or a deep link. Other agents see only enabled installations that match their role, team or user identity.
Reordering is optimistic: if another administrator changed the installation first, reload the list before trying again.

Use cases

Show CRM or order context beside a conversation.
Put an account-wide operations panel in the sidebar.
Integrate CRM and ERP with email, WhatsApp, SMS and other inbox conversations through the same omnichannel context; the app receives allowed IDs/context, never channel-provider credentials.
Roll out a new internal app to one team before enabling it for everyone.
Move a legacy conversation app to the V2 bridge with Dual, validate it, then select V2.

Tips, limits & best practices

Use HTTPS and a separate app origin. V2 rejects same-origin embedding because origin isolation is part of its trust boundary.
Never put API tokens, passwords or personal data in the URL. Query strings and fragments are useful for static parameters but can appear in browser history and the app server logs. The host preserves existing parameters and, in V2/dual, adds only cl_* names for dashboard origin, IDs, surface, protocol and locale. Every cl_* name is reserved: the host removes static values in that namespace and writes back only the permitted launch parameters.
Native creation requires exactly one HTTP(S) frame. When the feature is enabled, Super Admin prepares legacy apps with one frame and reports only truly incompatible definitions.
Grant the smallest practical audience and review team/user membership periodically.
Treat data delivered by the SDK as read-only context. Perform business changes through an authenticated backend and the REST API, where authorization and audit controls apply.
When an app backend or n8n must verify who opened the app, use the two-minute signed identity and public introspection. It proves account/user/installation identity but never authorizes REST/MCP.
The app can ask the host to resize its frame or open a link, but the V2 bridge is not a general proxy for arbitrary API calls.
Plain HTTP may be useful for local development, but browsers block mixed content when Conversa Labs itself runs over HTTPS. An HTTP warning does not bypass that browser protection.

Troubleshooting

Native settings do not appear: confirm the feature is enabled for this account. The legacy Dashboard Apps integration remains available while the flag is off.
The feature cannot be enabled: only Super Admin can activate it. The operator prepares compatible apps; correct reported IDs so each app has exactly one HTTP(S) frame.
The frame is blank or says it was refused: use Test to reproduce the real configuration, then inspect the app response for CSP frame-ancestors and X-Frame-Options; allow the exact Conversa Labs origin. X-Frame-Options: SAMEORIGIN blocks every dashboard on a different origin, including localhost; Legacy removes the SDK requirement but does not bypass this browser policy.
HTTP works locally but not in production: serve the app over HTTPS. A secure page cannot embed active HTTP content in modern browsers.
V2 reports an unsafe origin: host the app on a different origin from Conversa Labs; changing only the path is not enough.
An agent cannot see the app: confirm it is enabled, installed on the expected surface, and that the agent matches at least one configured role, team or user selector.
The Applications group is missing: assign at least one enabled, visible app to the Applications category. The empty group is hidden automatically.
The order changed after saving: another administrator may have reordered the surface. Reload and submit the current version again.
The SDK handshake times out: the dashboard re-sends the invitation for up to 10 seconds from frame load, so a timeout means the app did not answer within that window. Start with the app — it must call the SDK's connect() as soon as its page loads. Then verify the dashboard origin passed to the SDK, embedding headers, protocol version and that no proxy strips browser messaging behavior. Under Dual, use the per-bridge breakdown in Test to see the V2 error; to see it raw, switch the installation to V2 temporarily.
Email or phone is missing: confirm V2/dual and the current_user:email, contact:email and contact:phone capabilities. Contact data exists only on the conversation surface.
Identity returns capability_denied: enable identity:assertion and confirm the installation is active, visible to the user and the feature remains enabled.