> ## Documentation Index
> Fetch the complete documentation index at: https://docs.evolutionfoundation.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# Funções Personalizadas
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).
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
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
### 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
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
**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](/user-guides/products/overview).
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](/user-guides/settings/template-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
**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
**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
6. Modifique os campos desejados:
* Nome
* Descrição
* Status Ativo (toggle)
* Permissões (adicione ou remova permissões conforme necessário)
7. Revise as alterações
8. Clique no botão verde **"Update Role"** ou **"Save"** para salvar as alterações
9. 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.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.