Automações: Nós e Limites

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 criado	Um contato é criado no workspace
Negócio criado	Um card é criado em um pipeline (filtros opcionais por pipeline e/ou etapa)
Contato atualizado	Um atendente atualiza a ficha do contato pelo painel (nome, e-mail, telefone ou notas). Filtro opcional pelos campos alterados
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
Mensagem veio de anúncio	O contato inicia a conversa clicando em um anúncio do WhatsApp (Click-to-WhatsApp). Detecta pelos metadados da Meta (ctwa_clid/referral), não pelo texto; filtros opcionais por ID do anúncio, tipo de origem e instância
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
Fora do horário de atendimento	Uma conversa de ingresso chega fora do expediente do departamento

O gatilho Fora do horário de atendimento existe no builder, mas hoje não dispara em produção: depende do roteamento por departamento (MVP3), que está atrás de uma flag ainda desligada por padrão para os workspaces comerciais. Não conte com esse gatilho até confirmar com o time Vistum que o roteamento está habilitado no seu workspace.

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 webhook.<campo> (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.: {{name}}, {{phone}}), substituídas pelos valores do contexto no momento do disparo.

Condição

Bifurca o fluxo em dois caminhos (sim / não) com base em um único critério:

Critério	Avalia
Tag	O contato possui uma tag específica
Etapa	O contato está em uma etapa específica do pipeline (etapa de origem ou destino)
Mensagem contém palavra-chave	O texto da última mensagem recebida contém um termo
Negócio existe	Existe um card de pipeline aberto para o contato
Variável igual / contém	O valor de uma variável do fluxo (ex.: saída de um nó HTTP ou IA) é igual a ou contém um texto
Campo do contato igual / contém	Apenas os campos fixos `name`, `email`, `phone`, `notes` ou `company` — não aceita campo personalizado
Horário comercial	A hora atual está dentro de uma janela configurada (`startHour`–`endHour`, fuso configurável)

Campo personalizado não está disponível na Condição. Se você precisa ramificar por um campo personalizado do contato (cf:<id>), use o nó Dividir / Switch com o assunto “Campo do contato” — ele é o único que aceita campos personalizados, além dos mesmos fixos (name, email, phone, notes).

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, a conversa ou o pipeline:

Ação	Efeito
Adicionar tag	Atribui uma tag ao contato
Remover tag	Retira uma tag do contato
Mover no pipeline	Move o card do contato para outra etapa
Criar card	Cria um novo card em um pipeline para o contato
Notificar atendente	Cria uma notificação interna para um atendente
Atualizar contato	Atualiza um campo fixo do contato (`name`, `email`, `phone` ou `notes`)
Atribuir atendente	Atribui a conversa a um atendente (ou por rotação round-robin)
Mover para departamento	Roteia a conversa para outro departamento
Pausar bot / Reativar bot	Pausa ou retoma a automação de bot para aquela conversa
Finalizar conversa / Reabrir conversa	Muda o status da conversa
Aguardando humano	Marca a conversa como aguardando atendimento humano
Adicionar observação	Registra uma nota interna na conversa
Sair do fluxo / Remover de outros fluxos	Encerra a execução atual (ou remove o contato de outras automações em andamento)
Enviar webhook (`webhook_out`)	Faz uma chamada HTTP a uma URL externa — veja Enviar webhook por automação

Template Meta

Envia um template oficial do WhatsApp Business (aprovado pela Meta). É o nó usado para alcançar o contato fora da janela de 24h, em que mensagens de texto livre não são permitidas pela política do WhatsApp.

Vistum IA

Gera uma resposta com IA (GPT-4o) a partir do prompt configurado no nó. O nó consome créditos de IA do workspace por execução — bloqueado antes mesmo de chamar a IA em planos sem IA habilitada ou sem créditos. A saída fica disponível na variável de saída ({{aiResult}} por padrão) para os nós seguintes do fluxo.

O modelo não é selecionável na interface hoje — todo nó de IA novo usa o modelo padrão configurado no builder, sem opção de troca por automação.

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 (outputVar) 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). Campos escalares do JSON de resposta também ficam disponíveis individualmente como <outputVar>_<campo>.

O nó HTTP tem timeout de 5 segundos e lê no máximo 2000 bytes da resposta. 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.

Dividir / Switch

Roteia o fluxo em múltiplas saídas (mais de duas), com base em um assunto configurável: tag, variável do fluxo, resposta capturada (nó Perguntar), etapa do pipeline, origem do contato ou campo do contato — este último aceita tanto os campos fixos (name, email, phone, notes) quanto um campo personalizado via cf:<id>. Toda saída sem correspondência cai no ramo default.

Divisão aleatória / A-B

Distribui a execução entre variantes ponderadas (A/B/C), de forma determinística por execução — o mesmo contato sempre cai na mesma variante dentro de uma execução já em andamento.

Perguntar

Envia uma pergunta ao contato e pausa o fluxo aguardando a resposta (por texto ou botão), com timeout configurável. Se o contato não responder a tempo, o fluxo segue pelo ramo timeout.

Variáveis

As variáveis seguem o padrão {{...}} e são substituídas pelos valores do contexto no momento da execução. Não há notação com ponto ({{contact.name}} não funciona — fica literal na saída): use sempre a chave plana.

Dados do contato (chaves planas)

{{name}}            // Nome do contato
{{phone}}           // Telefone
{{email}}           // E-mail do contato (busca o contato no banco no momento da interpolação)
{{company}}         // Empresa do contato
{{notes}}           // Notas do contato
{{stage}}           // Nome da etapa atual do card do contato no pipeline
{{assigned_agent}}  // Nome do atendente responsável
{{lastMessage}}     // Texto da última mensagem recebida

Dados de um gatilho “Webhook recebido”

Todo campo escalar (string, número ou booleano) do corpo recebido vira uma variável com o prefixo webhook.:

{{webhook.product}}     // Campo mapeado como "produto"
{{webhook.amount}}      // Valor normalizado (número)
{{webhook.status}}      // Status do evento recebido
{{webhook.email}}       // E-mail extraído do payload
{{webhook.document}}    // CPF/CNPJ extraído do payload
{{webhook.externalId}}  // ID externo (dedup)
{{webhook.eventType}}   // Tipo do evento (quando mapeado)
{{webhook.phoneMissing}} // "1" quando não foi possível normalizar um telefone do payload

Qualquer outro campo do corpo recebido também vira {{webhook.<nomeDoCampo>}} automaticamente (não só os campos citados acima).

Dados do gatilho “Contato atualizado”

{{changedFields}}  // Lista separada por vírgula dos campos que mudaram (name, email, phone, notes)

Saída de nós (HTTP / IA)

Resultados produzidos por nós anteriores do fluxo, acessados pela variável de saída definida em cada nó:

{{<outputVar>}} — corpo bruto da resposta de um nó HTTP (truncado em 2000 caracteres)
{{<outputVar>_<campo>}} — campos escalares individuais do JSON de resposta de um nó HTTP
{{aiResult}} (ou o nome definido no nó) — 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
Chamadas HTTP por execução	Máximo de 3 chamadas por execução do fluxo, somando o nó HTTP e a ação Enviar Webhook juntos. A 4ª chamada (de qualquer um dos dois tipos) é ignorada silenciosamente

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`

Os registros podem ser consultados e filtrados na rota /historico.

​Visão geral

​Gatilhos (entrada do fluxo)

​Gatilho de Webhook recebido

​Nós do fluxo

​Mensagem

​Condição

​Aguardar

​Ação

​Template Meta

​Vistum IA

​Operação

​HTTP

​Dividir / Switch

​Divisão aleatória / A-B

​Perguntar

​Variáveis

​Dados do contato (chaves planas)

​Dados de um gatilho “Webhook recebido”

​Dados do gatilho “Contato atualizado”

​Saída de nós (HTTP / IA)

​Limites e proteções

​Logs e histórico

Visão geral

Gatilhos (entrada do fluxo)

Gatilho de Webhook recebido

Nós do fluxo

Mensagem

Condição

Aguardar

Ação

Template Meta

Vistum IA

Operação

HTTP

Dividir / Switch

Divisão aleatória / A-B

Perguntar

Variáveis

Dados do contato (chaves planas)

Dados de um gatilho “Webhook recebido”

Dados do gatilho “Contato atualizado”

Saída de nós (HTTP / IA)

Limites e proteções

Logs e histórico