Funções & Acessos e governança (RBAC)

Abrir em

Ver como Markdown

Abrir no ChatGPT Abrir no Claude

Conversa Labs

Última atualização em 7 de set de 2026

Visão geral

O módulo nativo Funções & Acessos define o que cada pessoa pode abrir, consultar e alterar na conta. Além dos perfis padrão Administrador e Agente, um Administrador pode criar funções com permissões granulares, escopo operacional por times ou caixas e regras de visibilidade de dados pessoais.

Esse módulo pertence à instalação da ConversaLabs e não depende do recurso premium Custom Roles de uma edição enterprise legada. Quando uma função nativa é atribuída a um Agente, ela se torna a autorização efetiva: uma permissão ausente é uma negação, mesmo que o perfil genérico Agente normalmente tivesse acesso à tela.

Pré-requisitos

Perfil Administrador para criar, editar, excluir ou atribuir funções.
Recursos Permissões granulares, Permissões em nível de campo e Governança da plataforma habilitados na conta para usar, respectivamente, permissões/escopo, regras de campos e a galeria de modelos.
A função nativa só pode ser atribuída a um Agente da mesma conta. Administradores mantêm o acesso total e não recebem função nativa.

Passo a passo

Abra Configurações → Funções & Acessos.
Escolha Nova função ou Criar a partir de modelo.
Informe nome e descrição e marque somente as permissões necessárias.
Em Escopo, escolha Conta inteira, Times específicos ou Caixas específicas. Se usar times/caixas, selecione pelo menos um item da própria conta.
Em Campos, configure dados de Contatos e Empresas como Visível, Mascarado ou Oculto.
Salve. Em Configurações → Agentes, edite um Agente e atribua a função.
Valide com uma conta de teste do mesmo perfil: navegação, URL direta, consulta, criação, alteração, exclusão, exportação e eventos em tempo real devem seguir a função.

Como as três camadas funcionam

Permissões (L1): cada área possui uma chave própria para leitura ou gestão. Há chaves separadas para operações sensíveis, como exportar/excluir contatos, exportar relatórios, auditoria, governança, solicitações de titulares e ações administrativas de contratos. A navegação esconde ações sem acesso, mas a decisão final sempre acontece no backend.
Escopo operacional (L2): para conversas e pessoas, Times específicos e Caixas específicas limitam listas, busca, contadores, acesso por ID, ações em lote, exportação e entrega em tempo real. Recursos vinculados a uma conversa, contato, time ou caixa seguem o vínculo disponível. Cadastros e configurações globais sem esse vínculo continuam limitados pela permissão L1; o escopo não inventa uma associação inexistente.
Visibilidade de campos (L3): regras de Contatos abrangem nome, e-mail, telefone, identificador, CPF/CNPJ, endereço e atributos personalizados/adicionais. Regras de Empresas abrangem CPF/CNPJ, e-mail, telefone e endereço. Elas são aplicadas em respostas da API, CSV e eventos em tempo real. Campos mascarados ou ocultos também ficam bloqueados para edição, evitando substituir o valor real por uma máscara.

Regras importantes

Uma associação nunca pode usar uma função de outra conta.
Atribuir uma função nativa remove uma eventual função Enterprise da mesma associação; não há soma silenciosa entre dois modelos de autorização.
Uma função atribuída não pode ser excluída. Remova ou troque todas as atribuições antes de excluir.
Desabilitar Permissões granulares desativa o efeito das funções nativas e restaura o comportamento padrão Administrador/Agente da conta.
Administrador sempre permanece fora das restrições da função nativa. Para testar menor privilégio, use um Agente.

Custom Roles (Enterprise legado) passou a ser um gate duro

O recurso premium Custom Roles — a implementação Enterprise antiga, diferente do módulo nativo descrito acima — hoje é bloqueado de ponta a ponta pela funcionalidade custom_roles, que nasce desligada em toda conta. O que muda na prática:

A API de Custom Roles é recusada sem a funcionalidade. Ela responde 401 com "You are not authorized to do this action". A verificação acontece antes da checagem de perfil, então nem um Administrador consegue listar, abrir, criar, editar ou excluir um custom role enquanto a funcionalidade estiver desligada.
Atribuir um custom role a um agente é ignorado em silêncio. Se a funcionalidade está desligada e a requisição traz um custom role, a atribuição simplesmente não é gravada — sem erro. Já limpar a atribuição (enviar o campo vazio) continua funcionando de propósito, para que uma conta que perdeu o recurso consiga remover uma atribuição antiga que ficou para trás.
Quem já usava não perde nada. Na atualização, uma rotina de dados liga a funcionalidade automaticamente em toda conta que já tem custom roles criados. Ela só liga onde há uso comprovado, relê o estado antes de escrever (rodar duas vezes não muda nada) e não desliga nada na volta — uma funcionalidade ligada à mão por um operador é indistinguível de uma ligada por ela.
Conta nova continua nascendo sem o recurso, que é o comportamento padrão.

O módulo nativo Funções & Acessos não depende dessa funcionalidade. Ele é governado por Permissões granulares, que vem habilitada. Se a sua conta usa apenas funções nativas, nada disso muda para você.

Configurações & opções

Modelos de função: comece por um modelo da galeria de governança quando ele representar a responsabilidade da pessoa; revise cada permissão antes de salvar, pois o modelo não substitui a revisão de menor privilégio.
Escopo: prefira times ou caixas específicas quando o trabalho não exige a conta inteira. Revise o escopo sempre que um Agente mudar de time ou de responsabilidade.
Campos: use Mascarado para permitir atendimento sem exibir o valor e Oculto quando a pessoa não deve nem consultar o dado. Registre a justificativa da regra de dados pessoais na sua política.

Casos de uso

Atendimento terceirizado limitado a uma caixa e com telefone/e-mail mascarados.
DPO com acesso a solicitações de titulares e auditoria, sem gestão operacional.
Supervisor com conversas do próprio time, relatórios e gestão de equipe, sem integrações ou cobrança.
Financeiro com pagamentos e relatórios exportáveis, sem acesso a mensagens de outras áreas.

Dicas, limites e boas práticas

Conceda a menor combinação de permissões que permite concluir o trabalho e valide a função com um Agente de teste antes de atribuí-la em produção.
Revise funções, escopos e regras de campos periodicamente e após mudanças de equipe, processo ou obrigação de privacidade.
Não trate a ocultação de botões como controle suficiente: mantenha a validação de permissões no servidor e investigue tentativas negadas no histórico de auditoria.

Solução de problemas

A função parece não restringir nada: confirme que ela está atribuída a um Agente, que pertence à mesma conta e que Permissões granulares está habilitado.
A pessoa vê a rota, mas uma ação está indisponível: confira a chave específica da ação; acesso à página não concede automaticamente excluir, exportar ou administrar.
A pessoa vê dados fora do esperado: revise o tipo de escopo, os times/caixas selecionados e os vínculos da conversa ou contato. Configurações globais sem vínculo usam somente L1.
O valor mascarado não pode ser editado: é intencional. Altere a regra para Visível, atualize o dado e restaure a regra.
O telefone está mascarado, mas o botão de ligar continua funcionando: também é intencional. A chamada é feita pelo sistema a partir do contato, sem que o número apareça para quem atende — o objetivo da regra é impedir a leitura e a cópia do dado, não impedir o atendimento.
Um campo que a pessoa editava ontem ficou somente leitura: a regra passou a ser aplicada também na interface. Antes, o campo aparecia editável e a gravação era recusada pelo servidor; agora ele já aparece bloqueado. Se aquela pessoa precisa mesmo editar, mude a regra do campo para Visível.
Não consigo excluir uma função: ela ainda está atribuída. Troque as atribuições primeiro.
Abri /settings/custom-roles e caí em Funções & Acessos: é o comportamento esperado. Nesta instalação o endereço antigo redireciona para Funções & Acessos; não existe mais uma tela de Custom Roles no painel. A API custom_roles continua existindo e é recusada com 401 enquanto a funcionalidade estiver desligada — inclusive para um Administrador.
Atribuí um custom role e o agente continuou sem ele: com a funcionalidade desligada a atribuição é descartada sem erro. Confirme a funcionalidade ou use uma função nativa.
Preciso remover um custom role antigo e a conta perdeu o recurso: limpar a atribuição continua permitido mesmo com a funcionalidade desligada — envie o campo vazio.