Dashboard Apps: superfícies nativas, público e segurança

Abrir em

Ver como Markdown

Abrir no ChatGPT Abrir no Claude

Conversa Labs

Última atualização em Aug 26, 2026

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

Acesse Configurações → Integrações → Dashboard Apps e selecione Adicionar um novo aplicativo.
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.
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.
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.
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.
Salve. O app e as superfícies escolhidas são criados juntos, ativos e inicialmente visíveis para toda a conta.
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.
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.
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.
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.
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.