Visão geral
Uma automação no Vistum é um fluxo construído visualmente no editor (Automações). Todo fluxo começa por um gatilho (entrada) e segue por uma sequência de nós que enviam mensagens, ramificam o caminho, esperam, executam ações ou chamam serviços externos.
Esta página é a referência técnica de cada gatilho e nó, das variáveis disponíveis e dos limites e proteções aplicados em cada execução.
A ação Enviar Webhook (webhook_out) tem documentação dedicada — payload padrão, variáveis, proteção SSRF e timeout. Veja Enviar webhook por automação. Gatilhos (entrada do fluxo)
O gatilho define quando a automação entra em execução para um contato. Todo fluxo tem exatamente um gatilho.
| Gatilho | Dispara quando |
|---|
| Novo contato | Um contato é criado no workspace |
| Tag adicionada | Uma tag específica é atribuída ao contato |
| Tag removida | Uma tag específica é retirada do contato |
| Mudança de etapa | O card do contato muda de etapa no pipeline |
| Negócio ganho | O negócio do contato é marcado como ganho |
| Negócio perdido | O negócio do contato é marcado como perdido |
| Mensagem recebida | O contato envia qualquer mensagem |
| Palavra-chave recebida | A mensagem recebida contém uma palavra-chave configurada |
| Sem resposta (X horas) | O contato não responde dentro de X horas |
| Webhook recebido | Uma requisição externa chega no endpoint da automação |
Gatilho de Webhook recebido
O gatilho Webhook recebido expõe uma URL de entrada com token único por automação. Sistemas externos chamam essa URL para iniciar o fluxo, e os dados enviados ficam acessíveis como variáveis (veja Variáveis).
O endpoint de entrada é protegido pelo token único embutido na URL — não há verificação HMAC no inbound. Trate a URL como um segredo: não a exponha em código frontend, repositórios públicos ou logs.
Nós do fluxo
Mensagem
Envia uma mensagem de texto via WhatsApp para o contato. Suporta variáveis no corpo (ex.: {{contact.name}}, {{contact.phone}}), substituídas pelos valores do contexto no momento do disparo.
Condição
Bifurca o fluxo em caminhos distintos com base em um critério do contato:
- Tag — o contato possui (ou não) uma tag
- Etapa — o card está em uma etapa específica do pipeline
- Campo personalizado — valor de um campo customizado do contato
Cada saída da condição segue para um ramo diferente do fluxo.
Aguardar
Pausa o fluxo por uma duração configurada em minutos, horas ou dias. Quando o tempo expira, a execução continua para o próximo nó.
Ação
Executa uma ação sobre o contato ou o pipeline:
| Ação | Efeito |
|---|
| Adicionar tag | Atribui uma tag ao contato |
| Remover tag | Retira uma tag do contato |
Enviar webhook (webhook_out) | Faz uma chamada HTTP POST a uma URL externa — veja Enviar webhook por automação |
Vistum IA
Gera uma resposta com IA (GPT-4o) a partir do contexto da conversa. O nó consome créditos de IA do workspace por execução. A saída pode ser usada nos nós seguintes do fluxo.
Operação
Executa uma operação de dados no CRM:
| Operação | Efeito |
|---|
| Criar lead | Cria um novo lead/contato |
| Criar tarefa | Cria uma tarefa associada ao contato |
| Verificar existência do lead | Confere se o lead já existe (idempotência por telefone) e expõe o resultado para o fluxo |
HTTP
Chama uma API externa (GET ou POST). O nó expõe uma variável de saída com o resultado da resposta, que pode ser referenciada nos nós seguintes (ex.: ler um campo retornado pela API para usar em uma condição ou mensagem).
Para o nó HTTP e a ação Enviar Webhook, todas as chamadas de saída passam por proteção SSRF: o host é resolvido por DNS e endereços de redes privadas/internas são bloqueados. O timeout da ação Enviar Webhook é de 10 segundos, sem retry.
Variáveis
As variáveis seguem o padrão {{...}} e são substituídas pelos valores do contexto no momento da execução. Em vez de uma lista fechada, pense em categorias:
Dados do contato
Atributos do contato que disparou ou avançou no fluxo:
{{contact.name}} // Nome do contato
{{contact.phone}} // Telefone (formato E.164)
{{contact.email}} // Email do contato
Dados do gatilho
Valores específicos do evento que iniciou o fluxo — por exemplo, os campos enviados na requisição de um Webhook recebido, a etapa de origem/destino em uma Mudança de etapa, ou a palavra-chave que casou em Palavra-chave recebida.
Saída de nós (HTTP / IA)
Resultados produzidos por nós anteriores do fluxo:
- A variável de saída de um nó HTTP (campos da resposta da API externa)
- O texto gerado por um nó Vistum IA
Limites e proteções
Cada automação aplica proteções para evitar loops, disparos duplicados e abuso:
| Proteção | Comportamento |
|---|
| Dedup 30s | Execuções repetidas da mesma automação para o mesmo contato dentro de 30 segundos são descartadas (anti-loop) |
onlyOnce | Opção que limita a automação a uma execução por contato (a partir da segunda, é ignorada) |
| Rate limit | 50 execuções por hora por instância de WhatsApp |
Logs e histórico
Cada execução gera um registro em AutomationLog, com status:
| Status | Significado |
|---|
success | A execução concluiu sem erros |
error | A execução falhou em algum nó |
dedup | A execução foi descartada pela proteção anti-loop ou onlyOnce |
