## Visão geral

Dashboard Apps incorporam uma aplicação web externa à Conversa Labs. Com as **superfícies nativas**
habilitadas, uma pessoa autorizada instala cada app na **conversa** ou na **barra lateral** da
conta, controla quem pode vê-lo e migra da integração legada sem interromper os apps existentes.

A funcionalidade vem desligada por padrão. Enquanto estiver desligada, os Dashboard Apps existentes
continuam na experiência legada da conversa; as telas e APIs de instalações nativas não ficam disponíveis.

## Pré-requisitos

- Perfil **Administrador** na conta ou função personalizada com permissão `integration_manage`.
- Feature `dashboard_apps_native_surfaces` habilitada na conta exclusivamente pelo Super Admin.
- URL do app acessível pelo navegador de todos os agentes. Use HTTPS em produção.
- Permissão para incorporar a URL: a política CSP `frame-ancestors` deve permitir a origem exata da
  Conversa Labs e não pode haver um cabeçalho `X-Frame-Options` conflitante.

## Passo a passo

1. Acesse **Configurações → Integrações → Dashboard Apps** e selecione **Adicionar um novo aplicativo**.
2. Informe um nome fácil de reconhecer e a URL HTTP(S) exata. Query string e fragmento são
   preservados; use-os apenas para parâmetros estáticos não sensíveis, como tenant, idioma ou rota.
3. No mesmo assistente, escolha onde o app deve aparecer:
   - **Conversa** mostra o app com o contexto da conversa selecionada.
   - **Barra lateral** mostra o app no nível da conta. Escolha uma das categorias nativas — Atendimento,
     Contatos & CRM, Aplicativos, Comercial, Produtividade, Automação, Crescimento ou Análise &
     Configurações —, selecione um ícone e confira a prévia do item antes de salvar.
4. Escolha o modo de compatibilidade:
   - **Legado** mantém o comportamento anterior de mensagens do iframe durante a migração.
   - **V2** usa a ponte versionada do SDK e exige uma origem diferente.
   - **Dual** aceita temporariamente legado e V2 durante uma migração controlada.
5. Em **Dados e identidade**, revise o que a instalação V2/dual pode receber. O padrão completo inclui
   e-mail do usuário atual, identidade assinada e, na conversa, e-mail e telefone do contato. Desative
   somente o que o app não precisa; tokens de sessão/API nunca são concedidos. Novos apps nativos vêm
   com V2 pré-selecionado e mostram essas concessões antes da criação. Legado/dual exibe o aviso de seu
   contexto legado mais amplo.
6. Salve. O app e as superfícies escolhidas são criados juntos, ativos e inicialmente visíveis para
   toda a conta.
7. No cartão do app, edite cada superfície para ativá-la ou desativá-la, mudar categoria, ícone, posição,
   capacidades e público. As posições usam nomes como **Primeiro** e **Depois de...**, sem números manuais.
   Use **Adicionar local** quando quiser incluir depois um local ainda não configurado.
8. Em **Público**, **Todos** disponibiliza o app aos membros elegíveis. **Selecionado** restringe
   por função de administrador/agente, equipes e usuários; corresponder a qualquer critério selecionado
   concede visibilidade.
9. Na barra lateral, o app vira um item direto da categoria selecionada. O grupo **Aplicativos** fica
   imediatamente abaixo de **Contatos & CRM** e só aparece quando existe ao menos um app visível
   atribuído a ele. A posição é normalizada separadamente em cada categoria; na conversa, entre as abas.
10. Selecione **Testar** no local configurado. A prévia usa a URL, query string, hash, sandbox e bridge
    reais. Em **V2**, o resultado confirma o handshake. Em **Legado**, a conferência é visual e o
    diálogo diz isso. Em **Dual**, o diálogo lista o resultado de cada bridge separadamente — repare
    nessa quebra: o atendimento segue pelo lane legado mesmo com a V2 falhando, então o status geral
    pode aparecer pronto enquanto a migração está bloqueada.
11. Teste também com uma pessoa administradora e um agente comum antes de ampliar o público.

## Configurações e opções

- Um app pode ter no máximo uma instalação em cada superfície.
- A instalação expõe `surface`, `compatibility_mode`, `enabled`, `position`, `sidebar_category`,
  `sidebar_icon`, `capabilities` e `audience`. Categoria e ícone existem apenas para a barra lateral,
  usam listas fechadas e são escolhidos pelo seletor visual.
- Capacidades básicas de conta, usuário, permissões, aparência e instalação são obrigatórias. Conversa,
  contato e mensagens existem somente na superfície de conversa. E-mail/telefone e
  `identity:assertion` são concessões explícitas, configuráveis por instalação.
- Público é um limite de acesso, não apenas um filtro visual. Quem estiver fora dele não recebe a
  instalação pela interface nem pela API.
- Administradores e funções personalizadas com `integration_manage` gerenciam instalações e
  inspecionam o público completo. A lista de gestão pode incluir linhas `visible: false` porque estão
  desativadas ou fora do público do próprio gestor, mas elas nunca montam na conversa, barra lateral
  ou link direto. Os
  demais agentes recebem somente instalações ativas compatíveis com sua função, equipe ou identidade.
- A reordenação é otimista: se outra pessoa administradora alterar primeiro, recarregue a lista.

## Casos de uso

- Exibir contexto de CRM ou pedidos ao lado de uma conversa.
- Colocar um painel operacional de toda a conta na barra lateral.
- Integrar CRM e ERP com conversas de e-mail, WhatsApp, SMS e outros canais usando o mesmo contexto
  omnichannel; o app recebe IDs/contexto permitidos, nunca a credencial do provedor do canal.
- Liberar um novo app interno para uma equipe antes de habilitá-lo para todos.
- Migrar um app legado com **Dual**, validar e depois selecionar **V2**.

## Dicas, limites e boas práticas

- Use HTTPS e uma origem separada. O V2 rejeita mesma origem porque o isolamento faz parte do limite
  de confiança.
- Nunca coloque tokens de API, senhas ou dados pessoais na URL. Query string e fragmento são úteis para
  parâmetros estáticos, mas podem aparecer em histórico e logs do servidor do app. O host preserva os
  parâmetros existentes e, em V2/dual, adiciona somente nomes `cl_*` para origem do dashboard, IDs,
  superfície, protocolo e idioma. Todo nome `cl_*` é reservado: o host remove valores estáticos
  nesse namespace e escreve novamente somente os parâmetros de lançamento permitidos.
- A criação nativa exige exatamente um quadro HTTP(S). Ao habilitar a feature, o Super Admin prepara
  apps legados com um único quadro e informa apenas definições realmente incompatíveis.
- Conceda o menor público possível e revise periodicamente equipes e usuários.
- Trate os dados do SDK como contexto somente leitura. Faça alterações de negócio por um backend
  autenticado e pela API REST, onde autorização e auditoria são aplicadas.
- Quando um backend próprio ou n8n precisar confirmar quem abriu o app, use a identidade assinada de
  dois minutos e a introspecção pública. Ela comprova conta/usuário/instalação, mas não autoriza REST/MCP.
- O app pode pedir ajuste de altura e abertura de link, mas a ponte V2 não é um proxy geral de API.
- HTTP simples pode servir no desenvolvimento local, mas navegadores bloqueiam conteúdo misto quando
  a Conversa Labs usa HTTPS. O aviso de HTTP não remove essa proteção.

## Solução de problemas

- **As configurações nativas não aparecem**: confirme a feature na conta. A integração legada de
  Dashboard Apps continua disponível enquanto a flag estiver desligada.
- **A feature não pode ser habilitada**: somente o Super Admin pode ativá-la. O operador prepara os
  apps compatíveis; corrija os IDs informados para que cada app tenha exatamente um quadro HTTP(S).
- **O quadro fica vazio ou recusa a conexão**: use **Testar** para reproduzir a configuração real; depois
  inspecione CSP `frame-ancestors` e `X-Frame-Options` e permita a origem exata da Conversa Labs.
  `X-Frame-Options: SAMEORIGIN` bloqueia qualquer painel em outra origem, inclusive localhost; o modo
  Legado dispensa o SDK, mas não contorna essa política do navegador.
- **HTTP funciona localmente, mas não em produção**: publique o app em HTTPS. Uma página segura não
  incorpora conteúdo HTTP ativo em navegadores modernos.
- **V2 informa origem insegura**: hospede o app em origem diferente da Conversa Labs; mudar só o caminho
  não basta.
- **Um agente não vê o app**: confirme que está ativo, na superfície correta, e que o agente atende
  a pelo menos uma função, equipe ou pessoa configurada.
- **O grupo Aplicativos não aparece**: atribua ao menos um app ativo e visível à categoria
  **Aplicativos**. O grupo vazio é ocultado automaticamente.
- **A ordem mudou ao salvar**: outra pessoa pode ter reordenado a superfície. Recarregue e envie a
  versão atual novamente.
- **O handshake do SDK expira**: o painel reenvia o convite por até 10 segundos a partir do
  carregamento do quadro; o tempo esgotado significa que o aplicativo não respondeu nesse prazo.
  Comece pelo aplicativo — ele precisa chamar `connect()` do SDK assim que a página carrega. Depois
  confira a origem do dashboard passada ao SDK, os cabeçalhos de incorporação, a versão do protocolo e
  proxies. Em **Dual**, use a quebra por bridge do **Testar** para ver o erro da V2; para vê-lo cru,
  mude a instalação para **V2** temporariamente.
- **E-mail ou telefone não chegam**: confirme V2/dual e as capacidades `current_user:email`,
  `contact:email` e `contact:phone`. Dados de contato só existem na superfície de conversa.
- **Identidade retorna `capability_denied`**: ative `identity:assertion` na instalação e confirme que
  ela continua ativa, no público do usuário e com a feature habilitada.

## Veja também

- [Integrações: provedores, credenciais, OAuth, webhooks e API](/hc/ajuda/articles/administration-integracoes-pt-br)
- [SDK, API REST e MCP de Dashboard Apps](/hc/ajuda/articles/api-developers-dashboard-apps-sdk-rest-mcp-pt-br)
- [Funções personalizadas e governança (RBAC)](/hc/ajuda/articles/administration-custom-roles-governanca-rbac-pt-br)
- [Logs de auditoria](/hc/ajuda/articles/administration-auditoria-pt-br)