## Visão geral

As **automações de contato** deixam você reagir a mudanças no **cadastro do contato**, e não só nas
conversas. Com elas, a plataforma pode etiquetar um contato, registrar uma nota, gravar um atributo
personalizado, criar um novo contato ou até abrir uma nova conversa — automaticamente, no momento em
que o dado muda.

Há dois grupos de recursos que trabalham juntos:

- **Gatilhos de contato**: **contato criado**, **contato atualizado**, **contato mesclado** e
  **contato excluído**. Eles avaliam a regra sobre o próprio contato, sem depender de uma conversa aberta.
- **Ações de contato e de criação**: adicionar/remover etiqueta, adicionar nota, definir atributo
  personalizado, **criar contato**, **criar conversa** e **adicionar nota privada** — disponíveis nas
  **Regras de automação**, nas **Macros** e no **Flow Builder**.

Nas **Regras de automação**, os gatilhos de contato **criado**, **atualizado** e **mesclado** deixaram
de ficar restritos a essas ações: eles oferecem agora **todo o catálogo de ações ancoradas no
contato** — CRM, tarefas, agenda, cobranças, assinaturas, follow-ups, contratos, engajamento e ações
de grupo do WhatsApp — descrito na seção "O catálogo completo no contato" abaixo.

## Pré-requisitos

- Permissão de **administrador** para criar regras, macros e fluxos com ações de contato.
- Ao menos um contato no cadastro, para que os gatilhos de contato tenham o que avaliar.
- Para a ação **criar conversa**, é necessário escolher uma **caixa de entrada** de destino.
- Para condições por **atributo personalizado do contato**, os atributos precisam estar definidos na
  conta (eles aparecem automaticamente nos seletores).

## Passo a passo

Exemplo: **quando um contato for atualizado E o atributo personalizado `plano` for igual a `premium`,
adicionar a etiqueta `cliente-premium`**.

1. Em Configurações, abra a área de **Automação** e crie uma nova regra.
2. Em **gatilho**, escolha **Contato atualizado**.
3. Adicione a **condição**: selecione o atributo personalizado **plano**, o operador **igual a** e o
   valor **premium**. Os valores possíveis são carregados automaticamente no seletor — você não digita
   um texto solto.
4. Em **ações**, escolha **Adicionar etiqueta ao contato** e selecione `cliente-premium`.
5. **Salve** e ative a regra. Atualize um contato de teste para confirmar o comportamento.

Para usar as mesmas ações em outros lugares: em uma **Macro**, adicione a ação de contato à sequência
que o agente dispara com um clique; no **Flow Builder**, use o nó **Ação de contato** (ou a ação
correspondente dentro do nó de ação) — veja o artigo de ações nativas do Flow Builder.

## Configurações & opções

Ações disponíveis nos três lugares (Automações, Macros e Flow Builder):

| Ação | Chave | O que faz |
| --- | --- | --- |
| Adicionar etiqueta ao contato | `add_contact_label` | Marca o contato com uma ou mais etiquetas. |
| Remover etiqueta do contato | `remove_contact_label` | Remove etiquetas do cadastro do contato. |
| Adicionar nota ao contato | `add_contact_note` | Registra uma nota interna no contato. |
| Definir atributo do contato | `set_contact_custom_attribute` | Grava um valor em um atributo personalizado. |
| Criar contato | `create_contact` | Cria um contato com nome, e-mail e telefone (caixa de entrada opcional). |
| Criar conversa | `create_conversation` | Abre uma conversa em uma caixa de entrada, com status e mensagem inicial opcionais. |
| Adicionar nota privada | `add_private_note` | Escreve uma nota privada na conversa. |

- **Criar contato**: informe **nome**, **e-mail** e **telefone**, e opcionalmente a **caixa de
  entrada**. A criação passa pelo construtor nativo de contatos, que **deduplica** por identificador,
  e-mail ou telefone — se o contato já existir, ele é reaproveitado em vez de duplicado.
- **Criar conversa**: escolha a **caixa de entrada** (obrigatória) e, se quiser, o **status inicial**
  (aberta, pendente ou adiada) e uma **mensagem inicial**. A conversa é criada para o contato resolvido.
- **Autocarregamento de condições**: nos seletores de condição, os atributos personalizados do contato
  e seus valores são carregados automaticamente — sem caixas de texto livres para adivinhar.
- **Webhooks de conta**: além de contato criado e atualizado, você pode assinar os eventos
  **contact.merged** (contato mesclado) e **contact.deleted** (contato excluído) para notificar
  sistemas externos.

### O catálogo completo no contato

Nas **Regras de automação**, além das ações da tabela acima, os gatilhos de contato **criado**,
**atualizado** e **mesclado** oferecem agora **todas as ações que têm o contato como âncora**:

- **CRM**: criar um negócio já vinculado ao contato, mover etapa, definir valor/prioridade e atribuir responsável.
- **Tarefas e agenda**: criar uma tarefa ou um agendamento ligados ao contato.
- **Pagamentos**: enviar cobranças e assinaturas para o contato.
- **Follow-ups, contratos e engajamento**: inscrever o contato em sequências, enviar contratos e disparar ações de engajamento.
- **Grupos do WhatsApp**: ações de grupo em que o participante padrão é o próprio contato.
- **Webhook e disparo em massa de fluxo**: notificar sistemas externos e lançar fluxos publicados.

**Ações de conversa não entram** nesses gatilhos — atribuir agente/equipe, resolver, enviar
mensagem/nota/anexo, SLA, IA/Maestro e template do WhatsApp exigem uma conversa, que não existe nesse
contexto. Para encadear: use **Criar conversa** na própria regra de contato e monte a segunda etapa em
um **gatilho de conversa** (o padrão "Criar conversa para encadear").

**Contato excluído** é a exceção: como o cadastro deixou de existir, esse gatilho oferece apenas
**webhook** e ações totalmente controladas por parâmetros.

## Casos de uso

- **Segmentação automática**: quando um contato é atualizado e o atributo `plano` vira `premium`,
  adicionar a etiqueta `cliente-premium`.
- **Higiene de cadastro**: ao mesclar contatos, registrar uma nota com a origem da fusão.
- **Onboarding**: ao criar um contato de um formulário, abrir uma conversa de boas-vindas em uma caixa
  de entrada específica.
- **Contexto para a equipe**: gravar um atributo (por exemplo, `origem = campanha-x`) para orientar o
  roteamento e os relatórios.

## Dicas, limites e boas práticas

- **Segurança contra loops**: as ações de contato respeitam proteções contra laços — evite regras que
  se disparam em cadeia (uma atualização que gera outra atualização). Mantenha cada regra objetiva.
- **Criar contato deduplica**: não se preocupe com duplicados — a mesma pessoa (mesmo e-mail, telefone
  ou identificador) é reaproveitada.
- **Criar conversa exige caixa de entrada**: sem uma caixa de entrada selecionada, a ação não roda.
- **Somente administradores**: essas ações exigem permissão de administrador para serem configuradas.
- **Variáveis nos campos de ação**: quando um campo da ação mostrar o botão `{ }`, ele pode receber uma
  variável (`{{ contact.name }}`, `{{ contact.custom_attribute.valor_orcamento }}`…) no fluxo, na automação
  ou na macro. A dica abaixo do campo informa quando essa opção está disponível.
- **Valor, data e vínculo não aceitam chute**: quando uma variável não existe — ou o texto não é um número,
  data ou vínculo válido — a ação compatível **não grava** um valor inventado, como 0 ou uma data vazia.
  Um negócio valendo R$ 0,00 sem ninguém saber é pior do que uma ação que não rodou.
- Documente para a equipe o que cada automação de contato faz — facilita a manutenção.

## Solução de problemas

- **A regra de contato não disparou**: confirme o gatilho (criado/atualizado/mesclado/excluído) e que
  **todas** as condições estão verdadeiras; verifique se a regra está ativa.
- **Criar conversa não funcionou**: confirme que uma **caixa de entrada** foi selecionada na ação.
- **Criei um contato duplicado?**: a ação deduplica por e-mail/telefone/identificador; se ainda parecer
  duplicado, verifique se os dados-chave batem exatamente.
- **O valor da condição não aparece**: os atributos personalizados e seus valores são carregados dos
  dados da conta — confirme se o atributo existe e tem valores registrados.
- **A ação não gravou o valor/data que eu esperava**: confirme que a variável existe para o contato
  (um atributo personalizado ainda não preenchido resolve vazio). Em um fluxo, o motivo aparece na saída
  do passo. Em uma automação ou macro, a atividade da conversa registra a quantidade de ações recusadas,
  e a auditoria identifica a ação e o campo que precisam ser revisados.
- **O webhook de mesclado/excluído não chegou**: confira se o endpoint assina **contact.merged** /
  **contact.deleted** e se responde com sucesso.

## Veja também

- [Regras de automação: gatilhos, condições e ações](/hc/ajuda/articles/automation-flows-regras-de-automacao-pt-br)
- [Macros: ações reutilizáveis em um clique](/hc/ajuda/articles/automation-flows-macros-pt-br)
- [Flow Builder: ações nativas e nó de ação de contato](/hc/ajuda/articles/automation-flows-flow-builder-acoes-nativas-pt-br)