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

# Regras de Automação

Este guia mostra como criar, gerenciar e diagnosticar regras de automação. Para o modelo conceitual (triggers, conditions, actions), ver [Visão Geral](/user-guides/automation/overview).

***

## Criando uma regra

1. Acesse `Configurações → Automação`.
2. Clique em **Nova Regra**.
3. Dê um **nome** descritivo (ex.: "Atribuir leads do WhatsApp ao time comercial").
4. Escolha um **trigger** da lista.
5. (Opcional) Adicione **conditions** para filtrar quando a regra deve disparar.
6. Adicione uma ou mais **actions**.
7. Ative a regra.

### Dicas para nomes

* Comece com o verbo da ação principal (`Atribuir...`, `Mover...`, `Etiquetar...`).
* Inclua o contexto (canal, time, estágio) para que outros operadores entendam sem abrir o detalhe.
* Evite nomes genéricos como "Regra 1" ou "Auto" — você vai acumular dezenas e precisa achá-las pela busca.

***

## Conditions e templates de mensagem

Conditions usam o sistema de **variáveis de template** quando você precisa fazer comparações dinâmicas. A partir do `v1.0.0-rc3` (EVO-1146), as variáveis ganharam campos adicionais:

* `label`, `source`, `example`, `position`, `component`

Use esses campos nas conditions para expressões mais precisas. Por exemplo: filtrar por uma label específica usando o `label.title` resolvido em vez do UUID cru.

### Operador `attribute_changed` com From/To

Quando você quer disparar regra apenas em uma transição específica de atributo (ex.: "status mudou de `aguardando` para `qualificado`"), use o operador `attribute_changed` com os pickers explícitos de valor **antes** e valor **depois**.

***

## Actions com payload dinâmico

### `send_template`

Permite enviar um template de mensagem com variáveis preenchidas dinamicamente. O sistema usa `deep_stringify_keys` no payload para que a chamada funcione independente do shape das keys (string ou symbol).

### `send_canned_response`

Atalho para enviar uma resposta pronta cadastrada em `Configurações → Respostas Prontas`. O payload aceita variáveis substituídas com dados da conversa.

### `move_to_pipeline` (rc3)

Move o item de pipeline para outro pipeline preservando o `id` do item. Útil para regras tipo "se label `qualificado` foi adicionada no pipeline Leads, move para o pipeline Vendas".

> A action faz bypass da validação de `same-pipeline` automaticamente. Não confunda com `move_to_stage`, que move dentro do mesmo pipeline.

### `apply_label`

A partir do `v1.0.0-rc3`, a action exibe um **picker de labels** em vez de campo de texto livre. UUIDs são resolvidos para titles antes de tagear, com fallback caso a label tenha sido renomeada.

***

## Painel de Logs (rc3)

Cada execução de regra agora gera um registro no painel `Automação → Logs`. Você vê:

* **Quando** a regra disparou.
* **Qual conversa / item** acionou.
* **Conditions avaliadas** — quais passaram e quais não.
* **Actions executadas** — sucesso ou erro.
* **Erros surfaceados** — incluindo falhas em macro webhooks (que antes ficavam silenciosas, ver EVO-1041).

### Limpeza automática

Logs antigos são removidos por um **cleanup job** que roda periodicamente. Você não precisa apagar manualmente.

### Endpoint de API

Para consumir logs programaticamente (dashboards externos, alertas), use o endpoint de listagem de `automation_rule_runs`. Ver a [API Reference](/api-reference/openapi/EvoAI-CRM-Service) para o schema completo.

***

## Diagnóstico de regras que não disparam

Roteiro rápido quando uma regra parece não estar funcionando:

1. **Verifique se está ativa.** Regras desativadas não aparecem como erro — simplesmente não rodam.
2. **Confirme o trigger.** `conversation_updated` cobre vários casos, mas `attribute_changed` é específico.
3. **Veja o log da execução.** No painel de logs, filtre pela regra. Se aparece com "no match", suas conditions estão filtrando ele.
4. **Conditions com label.** A condition `labels` usa subquery `EXISTS` (independente e NULL-safe) e casa label em **conversation OU contact**. Se você esperava casamento só na conversa, restrinja com outra condition.
5. **Dedup.** Para `pipeline_stage_updated`, há janela de 5s — dois eventos no mesmo `(rule, pipeline_item, stage)` em janela curta executam só uma vez.

***

## Loop prevention

Quando uma regra `move_to_stage` aciona um evento `pipeline_stage_updated` que poderia disparar a mesma regra recursivamente, o sistema marca a execução com `Current.executed_by = :stage_automation` e ignora reentrâncias. Isso evita loops infinitos por design.

***

## Considerações Finais

Automation rules são a forma declarativa de codificar comportamento operacional do CRM. Para fluxos mais complexos que envolvam IA conversacional, considere combinar uma automation rule com um agente — a regra cuida do roteamento e o agente cuida do diálogo.


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