## 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

1. Open **Settings → Integrations → Dashboard Apps** and select **Add a new dashboard app**.
2. 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.
3. 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.
4. 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.
5. 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.
6. Save. The app and selected surfaces are created together, enabled and initially visible to the
   whole account.
7. 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.
8. 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.
9. 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.
10. 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.
11. 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.

## See also

- [Integrations: providers, credentials, OAuth, webhooks and API](/hc/ajuda/articles/administration-integracoes-en)
- [Dashboard Apps SDK, REST API and MCP](/hc/ajuda/articles/api-developers-dashboard-apps-sdk-rest-mcp-en)
- [Custom roles and governance (RBAC)](/hc/ajuda/articles/administration-custom-roles-governanca-rbac-en)
- [Audit logs](/hc/ajuda/articles/administration-auditoria-en)