Skip to main content
A seção de Funções Personalizadas (Custom Roles) permite que você crie e gerencie funções personalizadas com permissões granulares para controlar o acesso de usuários a diferentes recursos e funcionalidades do sistema. Com as funções personalizadas, você pode definir exatamente quais ações cada função pode realizar em cada recurso, proporcionando controle preciso sobre o que cada membro da equipe pode visualizar, criar, editar ou excluir. Cada função personalizada pode ter um nome, descrição, status (ativo/inativo) e um conjunto detalhado de permissões organizadas em categorias: Core Features (Funcionalidades Principais), AI Agents (Agentes de IA) e Settings (Configurações).

​
Acessando Funções Personalizadas

Para acessar a área de gerenciamento de funções personalizadas:
  1. No menu lateral esquerdo, clique em Settings (Configurações).
  2. Na lista de opções de configurações, selecione Custom Roles (Funções Personalizadas).
Navegação para Funções Personalizadas - Item Custom Roles destacado no menu lateral A tela principal de funções personalizadas será exibida, mostrando todas as funções criadas ou uma mensagem indicando que nenhuma função foi criada ainda.

​
Visualizando a Lista de Funções Personalizadas

A tela principal de funções personalizadas exibe:
  • Título: “Custom Roles” no topo esquerdo em fonte grande e em negrito
  • Subtítulo: “Manage custom roles with granular permissions” abaixo do título
  • Barra de Pesquisa: Campo para filtrar funções por nome, localizado abaixo do subtítulo com placeholder “Search roles…”
  • Botão de Criação: Botão verde ”+ New Role” no canto superior direito da tela
  • Alternância de Visualização: Ícones de grid e lista abaixo do botão ”+ New Role” para alternar entre visualizações
  • Estado Vazio: Quando não há funções criadas, uma mensagem central “No custom roles yet” com um botão “Create Custom Role”

​
Pesquisando Funções Personalizadas

A barra de pesquisa permite localizar funções rapidamente pelo nome.

​
Como pesquisar

  1. Na parte superior da tela, localize o campo “Search roles…” com o ícone de lupa
  2. Digite o nome ou parte do nome da função desejada
  3. A lista de funções será atualizada automaticamente conforme o termo digitado, mostrando apenas as funções que correspondem à busca
Barra de pesquisa de funções personalizadas destacada A busca é realizada em tempo real, facilitando a localização de funções específicas quando há muitas cadastradas.

​
Criando uma Nova Função Personalizada

Existem duas formas de iniciar a criação de uma nova função personalizada:

​
Opção 1: Botão no Cabeçalho

  1. Clique no botão verde ”+ New Role” localizado no canto superior direito da tela
Botão New Role no cabeçalho destacado

​
Opção 2: Botão no Estado Vazio

Quando não há funções criadas, clique no botão verde “Create Custom Role” no centro da tela.

​
Preenchendo o Formulário de Criação

Após clicar em qualquer um dos botões, um modal será exibido com fundo escuro contendo:
  • Título: “New Custom Role” no topo do modal
  • Descrição: “Create a new role with specific permissions.” logo abaixo do título
Modal de criação de nova função personalizada com todos os campos destacados No formulário, preencha os seguintes campos:

​
1. Informações Básicas

Nome (Obrigatório)
  • Campo: Name (marcado com asterisco vermelho * indicando campo obrigatório)
  • Tipo: Campo de texto simples
  • Descrição: Nome identificador da função personalizada
  • Exemplo: “Gerente de Vendas”, “Analista de Suporte”, “Administrador de IA”
  • Recomendação: Use nomes claros e descritivos que indiquem o propósito da função
  • Localização: Primeiro campo do formulário, na seção “Basic Information”
Descrição (Opcional)
  • Campo: Description (sem asterisco, indicando campo opcional)
  • Tipo: Área de texto (textarea) maior que o campo de nome
  • Descrição: Texto explicativo sobre o propósito e responsabilidades da função
  • Exemplo: “Responsible for managing the sales team, monitoring performance, setting goals, analyzing reports, and making strategic business decisions.”
  • Uso: Ajuda outros membros da equipe a entenderem quando atribuir esta função
  • Localização: Segundo campo do formulário, abaixo do campo Name
Status Ativo
  • Campo: Active
  • Tipo: Toggle switch (interruptor)
  • Descrição: Define se a função está ativa e pode ser atribuída a usuários
  • Estado Visual:
    • Quando Ativado: O toggle fica na posição “on” com fundo verde/turquesa
    • Quando Desativado: O toggle fica na posição “off” com fundo cinza
  • Comportamento:
    • Quando Ativado: A função pode ser atribuída a usuários e está disponível para uso
    • Quando Desativado: A função existe, mas não pode ser atribuída a novos usuários
  • Localização: Terceiro campo do formulário, abaixo do campo Description

​
2. Permissões

A seção de Permissions (Permissões) permite definir quais ações a função pode realizar em cada recurso do sistema. As permissões são organizadas em três categorias principais:
Visão Geral das Permissões
  • Texto Explicativo: “Select which actions this role can perform on each resource”
  • Contador de Seleção: Exibe “0 selected” ou “X selected” indicando quantas permissões foram selecionadas no total
  • Botão Select All: Permite selecionar todas as permissões disponíveis de uma vez
Core Features (Funcionalidades Principais)
Esta categoria contém permissões relacionadas às funcionalidades principais do sistema:
  • Contador: Exibe “0/21” ou “X/21” indicando quantas permissões foram selecionadas de um total de 21
  • Select All: Checkbox para selecionar todas as permissões desta categoria
  • Ícone de Expansão: Seta para expandir/colapsar a seção
Seção Core Features expandida mostrando todas as subcategorias e permissões disponíveis Subcategorias disponíveis:
  1. Dashboard (0/1)
    • Descrição: “Main panel with metrics and overview”
    • Permissões: View
  2. Conversations (0/4)
    • Descrição: “Manage customer conversations”
    • Permissões: View, Create, Edit, Delete
  3. Contacts (0/4)
    • Descrição: “Manage contacts and leads”
    • Permissões: View, Create, Edit, Delete
  4. Pipelines (0/4)
    • Descrição: “Manage sales pipelines”
    • Permissões: View, Create, Edit, Delete
  5. Journeys (0/4)
    • Descrição: “Automate customer journeys”
    • Permissões: View, Create, Edit, Delete
  6. Channels (0/4)
    • Descrição: “Manage communication channels”
    • Permissões: View, Create, Edit, Delete
  7. Products (0/4) (a partir do v1.0.0-rc3)
    • Descrição: “Manage product catalog and variants”
    • Permissões: View, Create, Edit, Delete
    • Por padrão, account_owner recebe todas; agent recebe View. Ver Produtos.
  8. Template Bundles (0/2) (a partir do v1.0.0-rc3)
    • Descrição: “Export and import configuration bundles”
    • Permissões: View, Manage
    • Por padrão, apenas account_owner recebe Manage. Conceder a outros papéis com cuidado — Manage permite sobrescrever configuração crítica. Ver Bundles.
Cada subcategoria possui:
  • Um checkbox principal à direita para selecionar todas as permissões da subcategoria
  • Checkboxes individuais para cada ação (View, Create, Edit, Delete)
AI Agents (Agentes de IA)
Esta categoria contém permissões relacionadas à gestão de agentes de inteligência artificial:
  • Contador: Exibe “0/14” ou “X/14” indicando quantas permissões foram selecionadas de um total de 14
  • Select All: Checkbox para selecionar todas as permissões desta categoria
  • Ícone de Expansão: Seta para expandir/colapsar a seção
Seção AI Agents expandida mostrando todas as subcategorias e permissões disponíveis Subcategorias disponíveis:
  1. AI Agents (0/4)
    • Descrição: “Manage artificial intelligence agents”
    • Permissões: View, Create, Edit, Delete
  2. Custom Tools (0/4)
    • Descrição: “Create custom tools for agents”
    • Permissões: View, Create, Edit, Delete
  3. Custom MCP Servers (0/4)
    • Descrição: “Configure custom MCP servers”
    • Permissões: View, Create, Edit, Delete
  4. MCP Servers (0/1)
    • Descrição: “Manage system MCP servers”
    • Permissões: View
  5. AI Tools (0/1)
    • Descrição: “Tools available for agents”
    • Permissões: View
Cada subcategoria possui:
  • Um checkbox principal à direita para selecionar todas as permissões da subcategoria
  • Checkboxes individuais para cada ação disponível
Settings (Configurações)
Esta categoria contém permissões relacionadas às configurações do sistema:
  • Contador: Exibe “0/45” ou “X/45” indicando quantas permissões foram selecionadas de um total de 45
  • Select All: Checkbox para selecionar todas as permissões desta categoria
  • Ícone de Expansão: Seta para expandir/colapsar a seção
Seção Settings expandida mostrando todas as subcategorias e permissões disponíveis Subcategorias disponíveis:
  1. Account (0/2)
    • Descrição: “Account settings”
    • Permissões: View, Edit
  2. Users (0/4)
    • Descrição: “Manage account users”
    • Permissões: View, Create, Edit, Delete
  3. Teams (0/4)
    • Descrição: “Manage teams and groups”
    • Permissões: View, Create, Edit, Delete
  4. Custom Roles (0/4)
    • Descrição: “Create and manage custom roles”
    • Permissões: View, Create, Edit, Delete
  5. Labels (0/4)
    • Descrição: “Manage labels for organization”
    • Permissões: View, Create, Edit, Delete
  6. Custom Attributes (0/4)
    • Descrição: “Create custom fields”
    • Permissões: View, Create, Edit, Delete
  7. Canned Responses (0/4)
    • Descrição: “Pre-defined messages”
    • Permissões: View, Create, Edit, Delete
  8. Macros (0/4)
    • Descrição: “Automate repetitive actions”
    • Permissões: View, Create, Edit, Delete
Cada subcategoria possui:
  • Um checkbox principal à direita para selecionar todas as permissões da subcategoria
  • Checkboxes individuais para cada ação disponível

​
Como Selecionar Permissões

  1. Seleção Individual: Clique nos checkboxes individuais de cada ação (View, Create, Edit, Delete) para conceder permissões específicas
  2. Seleção por Subcategoria: Clique no checkbox principal à direita de cada subcategoria para selecionar todas as permissões daquela subcategoria
  3. Seleção por Categoria: Clique no checkbox “Select All” no cabeçalho de cada categoria (Core Features, AI Agents, Settings) para selecionar todas as permissões da categoria
  4. Seleção Total: Clique no botão “Select All” no topo da seção de permissões para selecionar todas as permissões disponíveis

​
Finalizando a Criação

Na parte inferior do modal, há dois botões de ação:
  • Cancel: Botão cinza escuro com texto branco, localizado à esquerda
  • Create Role: Botão verde/turquesa brilhante com texto branco, localizado à direita
Após preencher os campos desejados:
  1. Revise as informações inseridas, especialmente as permissões selecionadas
  2. Clique no botão verde “Create Role” para criar a função personalizada
  3. Ou clique em “Cancel” para fechar o modal sem salvar
A função será criada e aparecerá imediatamente na lista de funções personalizadas.

​
Visualizando Funções Personalizadas na Lista

Após criar funções personalizadas, elas serão exibidas em cards com as seguintes informações:

​
Informações do Card

  • Nome da Função: Título em negrito no topo do card
  • Descrição: Texto descritivo da função (pode estar truncado com ”…”)
  • Status: Badge indicando se a função está “Active” (Ativa) ou “Inactive” (Inativa)
  • Estatísticas: Três métricas exibidas na parte inferior do card:
    • Users: Número de usuários atribuídos a esta função (ex: “0 users”)
    • Permissions: Número de permissões concedidas à função (ex: “0 permissions”)
    • Scopes: Número de escopos configurados (ex: “0 scopes”)
  • Menu de Ações: Ícone de três pontos (...) no canto superior direito do card para acessar opções

​
Funcionalidades da Lista

  • Busca Integrada: A barra de pesquisa acima da lista filtra os resultados em tempo real
  • Alternância de Visualização: Use os ícones de grid e lista para alternar entre visualizações diferentes

​
Editando uma Função Personalizada

Para modificar uma função personalizada existente:
  1. Na lista de funções personalizadas, localize a função que deseja editar
  2. No card da função, clique no ícone de três pontos (...) no canto superior direito
  3. Um menu dropdown será exibido com as opções disponíveis
  4. No menu dropdown, clique em Edit (acompanhado de um ícone de lápis)
  5. Um modal semelhante ao de criação será aberto, mas com o título “Edit Custom Role” e os campos já preenchidos com os valores atuais da função
Menu de ações da função personalizada destacado - opções Edit, Activate e Delete
  1. Modifique os campos desejados:
    • Nome
    • Descrição
    • Status Ativo (toggle)
    • Permissões (adicione ou remova permissões conforme necessário)
  2. Revise as alterações
  3. Clique no botão verde “Update Role” ou “Save” para salvar as alterações
  4. Ou clique em “Cancel” para descartar as alterações
As alterações serão aplicadas imediatamente e refletidas na lista de funções personalizadas e nos usuários que possuem esta função atribuída.

​
Ativando/Desativando uma Função Personalizada

Para alterar o status de uma função personalizada:
  1. Na lista de funções personalizadas, localize a função que deseja ativar ou desativar
  2. No card da função, clique no ícone de três pontos (...) no canto superior direito
  3. No menu dropdown que aparece:
    • Se a função estiver Inativa, clique em “Activate” para ativá-la
    • Se a função estiver Ativa, clique em “Deactivate” para desativá-la
Observação: Funções inativas não podem ser atribuídas a novos usuários, mas usuários que já possuem a função atribuída mantêm suas permissões até que a função seja removida manualmente.

​
Excluindo uma Função Personalizada

Para remover uma função personalizada:
  1. Na lista de funções personalizadas, localize a função que deseja excluir
  2. No card da função, clique no ícone de três pontos (...) no canto superior direito
  3. No menu dropdown que aparece, clique em Delete (acompanhado de um ícone de lixeira, exibido em texto vermelho para indicar uma ação destrutiva)
  4. Um diálogo de confirmação será exibido
  5. Confirme a exclusão no diálogo que aparecer
Atenção: A exclusão de uma função personalizada pode afetar os usuários que possuem esta função atribuída. Verifique se não há dependências antes de excluir. A ação de exclusão é permanente e não pode ser desfeita. Recomenda-se revisar quais usuários possuem a função antes de excluí-la.

​
Considerações Finais

  • Princípio do Menor Privilégio: Conceda apenas as permissões necessárias para cada função realizar seu trabalho, evitando acesso excessivo
  • Nomenclatura Clara: Use nomes descritivos e claros para que todos os membros da equipe entendam o propósito de cada função
  • Descrições Detalhadas: Preencha as descrições das funções para documentar responsabilidades e quando utilizá-las
  • Revisão Regular: Revise periodicamente as permissões das funções para garantir que continuam adequadas às necessidades da equipe
  • Status Ativo: Mantenha apenas funções ativas que estão em uso, desativando funções obsoletas em vez de excluí-las imediatamente
  • Permissões Granulares: Utilize as permissões granulares para criar funções específicas que atendam exatamente às necessidades de cada equipe ou departamento
  • Teste de Permissões: Após criar uma função, teste atribuindo-a a um usuário de teste para garantir que as permissões funcionam como esperado
As funções personalizadas são uma ferramenta poderosa para controle de acesso e segurança, permitindo que você defina exatamente o que cada membro da equipe pode fazer no sistema, melhorando a segurança e a organização do trabalho em equipe.

​
Guard de Privilege Escalation (a partir do v1.0.0-rc3)

A partir do v1.0.0-rc3, o endpoint de criação/edição de funções aplica uma proteção contra privilege escalation via delegation (EVO-1061):
  • Um account_owner só pode delegar permissões que ele mesmo detém.
  • Tentar criar uma função com uma permissão fora do conjunto do solicitante retorna 403 Forbidden com motivo explícito.
  • O escopo do super_admin (permissões installation_configs.manage) continua exclusivo — outros papéis não podem delegar essas permissões.
Isso impede que um account_owner crie uma função “Super Helper” que dá a um agente comum acesso ao painel de instalação. O comportamento é estrito por design.