> ## 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.

# Bundles de Configuração

A funcionalidade **Bundles de Configuração** permite exportar e importar a configuração da sua instalação como um arquivo ZIP portável. É útil para migrar entre ambientes (staging → produção), replicar setups entre clientes ou criar templates de instalação reutilizáveis.

> Disponível a partir do `v1.0.0-rc3` (EVO-1116).

### O que vai dentro de um Bundle?

Um bundle inclui (quando você marca cada categoria no wizard de export):

* **Inboxes** — canais conectados (configuração, sem credenciais sensíveis).
* **Agentes de IA** — prompts, ferramentas, configurações de modelo.
* **Automation rules** — regras `trigger → action`.
* **Respostas prontas (canned responses)**.
* **Templates de mensagem** — incluindo variáveis declaradas.
* **Funções personalizadas** — papéis customizados com permissões.

> **O que NÃO vai:** credenciais (tokens, senhas, API keys), dados de conversa, contatos, histórico. Bundles são **configuração**, não dados de operação.

***

## Acessando

`Configurações → Templates / Bundles` (a entrada aparece se você tiver permissão `template_bundles.read` ou `template_bundles.manage`).

***

## Exportando um Bundle

1. Clique em **Exportar Bundle**.
2. No wizard, marque as categorias que deseja incluir. Cada categoria expõe a lista de itens disponíveis — você pode escolher exportar tudo ou apenas alguns itens específicos.
3. Confirme. O sistema gera um ZIP com a estrutura interna do bundle.
4. Faça o download.

O nome padrão é `bundle-{instalação}-{data}.zip`. Você pode renomear livremente após o download.

### O que esperar

* Bundles pequenos (apenas templates e canned responses) saem rápido.
* Bundles grandes (todos os agentes + automation rules) podem levar alguns segundos.
* Não há limite duro de tamanho, mas mantenha bundles focados (não exporte tudo se você só precisa migrar um agente).

***

## Importando um Bundle

1. Clique em **Importar Bundle**.
2. Selecione o arquivo ZIP.
3. O sistema valida o conteúdo e mostra preview do que será importado.
4. Você decide o que **importar**, **sobrescrever** ou **ignorar** item a item.
5. Confirme.

### Comportamento em caso de conflito

Quando um item do bundle já existe na instalação de destino (mesmo nome / mesmo identificador):

* **Importar como novo:** cria com sufixo para evitar colisão (ex.: `Boas-vindas (importado)`).
* **Sobrescrever:** substitui o existente. Use com cuidado em produção.
* **Ignorar:** pula esse item específico, mas segue com o resto do bundle.

> Não há rollback automático após confirmar o import. Faça backup do banco antes de importar em produção.

***

## Casos de Uso

### 1. Staging → Produção

Você ajusta agentes e automations em staging, valida com a equipe e exporta um bundle. Em produção, importa sobrescrevendo apenas os itens validados.

### 2. Template de instalação

Você mantém um bundle "template padrão" com automations e canned responses que toda nova instalação deve ter. Ao subir uma nova instância, basta importar.

### 3. Migração entre clientes (multi-tenant)

Empresas que prestam serviço de implantação podem ter um catálogo de bundles por vertical (varejo, saúde, educação) e importar o relevante ao iniciar um cliente.

***

## Permissões

| Permissão | O que permite |
| - | - |
| `template_bundles.read` | Ver bundles disponíveis e baixar exports anteriores |
| `template_bundles.manage` | Criar exports, importar bundles novos |

Por padrão apenas o `account_owner` recebe `manage`. Conceda a outros papéis com cuidado — `manage` permite sobrescrever configuração crítica.

***

## Limitações conhecidas

* **Credenciais não viajam.** Após importar um inbox WhatsApp, você precisa reconectar o canal manualmente (o token de instância não está no bundle).
* **Referências cruzadas.** Se um agente referencia um Knowledge Nexus space que não existe no destino, o agente é importado mas a referência fica quebrada (visível na UI como "space não encontrado"). Configure os spaces no destino antes de importar.
* **Versões de schema.** Bundles exportados em versões diferentes do CRM podem precisar de adaptação. Mantenha staging e produção próximos em versão.

***

## Considerações Finais

Bundles são a forma recomendada de **mover configuração** entre instalações do CRM Community. Para mover **dados** (contatos, conversas), use as funcionalidades específicas de import/export de cada módulo.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.