> ## Documentation Index
> Fetch the complete documentation index at: https://help.vistum.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Gatilhos disponíveis

> Todos os eventos que podem disparar uma automação no Vistum.

## O que é um gatilho

O **gatilho** é o evento que dá início à automação. Cada automação tem exatamente um gatilho.

## Lista completa de gatilhos

### Novo contato criado

Dispara quando um contato entra no workspace pela primeira vez — seja via mensagem recebida no WhatsApp ou criado manualmente.

**Caso de uso**: enviar mensagem de boas-vindas para todos os novos leads.

***

### Mensagem recebida

Dispara a cada mensagem recebida de qualquer contato.

**Configurações adicionais:**

* Filtrar por **instância** específica (número de WhatsApp)
* Executar **somente uma vez** por contato (`onlyOnce`)

**Caso de uso**: responder automaticamente fora do horário comercial.

***

### Palavra-chave recebida

Dispara apenas quando a mensagem recebida contém uma palavra ou frase específica.

**Configurações:**

* Lista de palavras-chave (ex: `preço`, `orçamento`, `quero comprar`)
* Match case-insensitive

**Caso de uso**: quando alguém digitar "preço", enviar a tabela de valores.

***

### Sem resposta (X horas)

Dispara quando um contato não recebeu resposta depois de X horas.

**Configurações:**

* Quantidade de horas sem resposta

**Caso de uso**: alertar o atendente que há um contato aguardando há mais de 2 horas.

***

### Tag adicionada ao contato

Dispara quando uma tag específica é adicionada a um contato.

**Configurações:**

* Qual tag deve ser adicionada para disparar

**Caso de uso**: quando a tag "proposta-enviada" for adicionada, aguardar 2 dias e perguntar se o cliente tem dúvidas.

***

### Tag removida do contato

Dispara quando uma tag específica é removida de um contato.

***

### Negócio criado

Dispara quando um **novo card (negócio) é criado** em qualquer pipeline — pelo Kanban, pela ficha do contato, por um formulário ou pela API.

**Configurações:**

* Pipeline específico (opcional — em branco dispara para qualquer pipeline)

**Caso de uso**: assim que um novo negócio entra no funil, enviar uma mensagem de boas-vindas ao lead e criar uma tarefa de primeiro contato para o atendente.

<Note>
  Se você criar o card já em uma etapa de ganho ou perda, o gatilho **Negócio criado** dispara mesmo assim — ele reage à criação, não à etapa.
</Note>

***

### Contato atualizado

Dispara quando os dados de um contato são **editados** na ficha do contato. Só dispara quando há uma **mudança real** em pelo menos um destes campos:

* Nome
* E-mail
* Telefone
* Observações (notas)
* Tags

Salvar a ficha sem alterar nada **não** dispara o gatilho.

**Configurações:**

* Filtrar por **campos específicos** (opcional): a automação só dispara se um dos campos escolhidos mudar. Em branco, dispara para qualquer um dos campos acima.

**Caso de uso**: quando o e-mail de um contato for preenchido, enviar os dados atualizados para uma planilha ou para o seu sistema externo via webhook.

<Warning>
  **Isso não gera loop.** Quando uma automação usa a ação *Atualizar contato*, a escrita é feita direto no banco — ela **não** passa pelo caminho que emite o gatilho "Contato atualizado". Ou seja: uma automação alterar o contato **nunca** dispara outra automação de "Contato atualizado". O gatilho só dispara quando **uma pessoa** edita a ficha manualmente. Além disso, o motor de automações tem proteção de deduplicação de 30 segundos por contato como defesa adicional.
</Warning>

***

### Mudança de etapa no pipeline

Dispara quando um card é movido para uma etapa específica do pipeline.

**Configurações:**

* Pipeline de origem
* Etapa de destino

**Caso de uso**: quando o card entrar em "Proposta Enviada", enviar confirmação por WhatsApp.

***

### Negócio ganho

Dispara quando um card é movido para uma etapa de **ganho** (ou marcado com status **Ganho**) no pipeline.

**Caso de uso**: enviar mensagem de parabéns e iniciar o fluxo de onboarding do cliente.

***

### Negócio perdido

Dispara quando um card é marcado como **Perdido**.

**Caso de uso**: enviar uma pesquisa de motivo de perda ou agendar um follow-up de reativação para daqui a 30 dias.

***

### Webhook recebido

Dispara quando um sistema externo envia uma requisição POST para o endpoint único da automação.

**Como usar:**

1. Configure o gatilho como **Webhook recebido**
2. O Vistum gera uma URL única (ex: `/api/automations/webhook-in/TOKEN`)
3. Configure seu sistema externo (checkout, n8n, Zapier, etc.) para fazer POST nessa URL

**Filtro por evento (eventFilter):** você pode dizer ao Vistum para só disparar quando um campo do payload tiver um valor específico — por exemplo, só quando o checkout enviar `PURCHASE_APPROVED`. Eventos que não batem com o filtro ficam registrados como **filtrados** e não disparam a automação. É assim que se trata reembolso e cancelamento (veja [Reembolso e cancelamento](#reembolso-e-cancelamento) abaixo).

**Caso de uso**: quando um formulário for preenchido no site, criar o lead no Vistum e disparar a automação.

<Note>
  Cada automação tem um token único. Se o token for comprometido, você pode rotacioná-lo em **Configurações do webhook** da automação.
</Note>

***

## Reembolso e cancelamento

O Vistum ainda **não** tem um gatilho dedicado de "pagamento reembolsado". Até lá, você trata reembolso e cancelamento com o gatilho **Webhook recebido** + **filtro de evento**, porque o próprio checkout (Hotmart, Kiwify, etc.) já envia um webhook quando isso acontece.

<Steps>
  <Step title="Crie uma automação com o gatilho Webhook recebido">
    Em **Automações → Nova Automação**, selecione o gatilho **Webhook recebido**. O Vistum gera uma URL única.
  </Step>

  <Step title="Cole a URL no checkout">
    No painel do seu checkout (Hotmart, Kiwify, etc.), cadastre essa URL como destino de webhook e marque os eventos de reembolso/cancelamento (ex: `REFUNDED`, `PURCHASE_REFUNDED`, `CANCELED`, `SUBSCRIPTION_CANCELLATION`).
  </Step>

  <Step title="Configure o filtro de evento">
    Nas configurações do gatilho, defina o **filtro de evento**:

    * **Campo**: o caminho do campo de status no payload do checkout (ex: `event` ou `data.status`)
    * **Valor**: o status que deve disparar (ex: `REFUNDED` ou `CANCELED`)

    Assim, vendas aprovadas não disparam essa automação — só os eventos de reembolso/cancelamento passam.
  </Step>

  <Step title="Monte a ação de reação">
    No fluxo, adicione as ações que quer executar nesse caso, por exemplo:

    * Mover o negócio do contato para uma etapa "Reembolsado"
    * Adicionar a tag `reembolso`
    * Enviar uma mensagem de confirmação ao cliente
    * Avisar o time por webhook de saída
  </Step>

  <Step title="Ative e teste">
    Ative a automação e faça um reembolso de teste no checkout (ou reenvie o evento pelo painel do checkout) para confirmar que dispara.
  </Step>
</Steps>

<Tip>
  Os campos recebidos no webhook ficam disponíveis nas ações como variáveis `webhook.campo` — por exemplo `webhook.status`, `webhook.product`, `webhook.amount`. Use-as nas mensagens e condições do fluxo.
</Tip>

***

## Acompanhar a execução

Toda vez que um gatilho dispara, a execução fica registrada. Para acompanhar:

1. Acesse **Histórico** no menu lateral
2. Filtre por automação e por status (sucesso / erro / filtrado / dedup)
3. Clique em uma execução para ver o passo a passo e as variáveis recebidas

<Note>
  Execuções com status **dedup** não são erros — significam que a automação foi bloqueada de propósito para evitar repetição em curto intervalo. Execuções **filtrado** significam que o webhook chegou, mas não bateu com o filtro de evento configurado.
</Note>