Gatilhos: quando uma automação dispara

O gatilho é o ponto de partida de todo fluxo no Flow Builder. Ele responde uma pergunta única: quando este fluxo deve disparar?

Cada fluxo tem exatamente um gatilho — o nó Início. O que muda é o tipo de evento que escolhe pra ele.

Tipos de gatilho disponíveis

Dados disponíveis em cada gatilho

Cada tipo de gatilho coloca um conjunto diferente de dados no trigger_data — o "snapshot" do evento que alimenta as variáveis ao longo do fluxo.

Pedido (Novo pedido, Pago, Status atualizado, Avaliação, Rastreio)

Você tem acesso a:

order.external_id        — número do pedido na loja (ex: #1234)
order.total              — valor total
order.status             — status atual
order.first_name         — primeiro nome do comprador
order.last_name          — sobrenome
order.email              — e-mail
order.phone              — telefone
order.coupon_code        — cupom usado
order.tracking_code      — código de rastreio
order.payment_method     — método de pagamento
order.shipping_method_label — nome do método de envio

order.address.city       — cidade
order.address.state      — UF
order.address.postcode   — CEP
order.address.address_1  — rua e número

order.customer.*         — dados completos do cliente vinculado
customer.*               — atalho pro cliente

Carrinho abandonado

cart_id                  — ID interno
cart_total               — valor numérico
cart_total_formatted     — formatado em BRL ("R$ 189,50")
cart_url                 — URL pra retomar o carrinho na loja
cart_token               — querystring do cart_url (pra montar links)
cart_contents            — array de itens

customer.first_name, customer.last_name, customer.full_name
customer.email, customer.phone
customer.city, customer.postcode

Tag adicionada / removida

customer.id, customer.email, customer.first_name, customer.last_name, customer.phone
tag.id, tag.uuid, tag.name, tag.color
action                   — "added" ou "removed"

Segmento

customer.id, customer.email, customer.first_name, customer.last_name, customer.phone
campaign.id, campaign.uuid, campaign.name

Evento de flow

customer.first_name, customer.last_name, customer.email, customer.phone
source_flow_id           — ID do fluxo que disparou o evento
source_flow_event        — "started", "completed" ou "failed"
source_execution_id      — ID da execução de origem

Detalhes importantes por tipo

Novo pedido vs. Pedido pago

• Novo pedido dispara assim que o pedido é criado, mesmo se ainda não foi pago (pendente, aguardando confirmação, etc.).
• Pedido pago dispara só quando o pedido transiciona pra "pago" — útil pra mensagens de "obrigado pela compra" sem confundir com cancelamentos.

Se você quer só pedidos pagos, use Pedido pago. Se quer reagir a qualquer venda (incluindo a janela entre criação e pagamento), use Novo pedido.

Tag Adicionada / Removida exige escolher a tag

No Inspector do gatilho, você precisa selecionar qual tag dispara o fluxo. Não existe gatilho "qualquer tag".

Use Tag Adicionada + Tag Removida em pares pra construir lógicas tipo "quando vira VIP, manda parabéns; quando perde a tag VIP, manda mensagem de despedida".

Segmento faz backfill na ativação

Quando você ativa um fluxo com gatilho Segmento, todos os membros atuais do segmento entram no fluxo imediatamente (via BackfillSegmentFlowMembersJob).

Depois do backfill, o fluxo dispara só pra quem entrar no segmento dali pra frente.

Evento de flow encadeia automações

Esse é o gatilho mais avançado. Ele te deixa montar fluxos em cadeia:

Fluxo A termina → dispara o Fluxo B

Configure no Inspector:

• Fluxo de origem — qual fluxo monitorar
• Tipo de evento — started, completed ou failed

Útil pra separar lógicas grandes em vários fluxos menores e reaproveitar pedaços.

Como variáveis são resolvidas

Quando o fluxo dispara, todo o trigger_data fica disponível pra ser referenciado em qualquer nó subsequente via {{caminho.do.dado}}.

A resolução acontece em ordem:

1. trigger_data — snapshot do evento
2. context — dados acumulados na execução (ex: {{coupon_code}} aparece após o nó Cupom)
3. FlowEntityData — carrega o model do banco em tempo real, se a variável não foi achada nas duas primeiras

Se a variável não for encontrada em nenhum lugar, o placeholder fica intacto no texto. Por exemplo, Olá {{customer.first_name_inexistente}} chega no destinatário literalmente como Olá {{customer.first_name_inexistente}}.

Re-disparo: quantas vezes o cliente entra

Filtros no nível do gatilho

Alguns gatilhos aceitam filtros adicionais no Inspector:

• Status do pedido — pra disparar só quando o status for específico (ex: só pedidos pagos via Pix)
• Valor mínimo — pra disparar só pra pedidos acima de X
• Tag/Segmento UUID — obrigatório nos gatilhos de Tag e Segmento

Esses filtros são aplicados antes de criar a execução. Se o evento não passa no filtro, o fluxo simplesmente não dispara — sem custo de processamento.

O que acontece se o cliente não tem telefone?

Se o cliente do evento não tem telefone cadastrado, os nós de Mensagem ao longo do fluxo são pulados silenciosamente — sem quebrar o fluxo. As outras ações (cupom, tag, webhook) continuam normalmente.

Isso é intencional: assim o fluxo segue funcionando pra cobrar tag/cupom mesmo quando a mensagem não pode sair.

Próximos passos

• Visão geral do Flow Builder — entenda o ciclo completo de execução.
• Veja os artigos detalhados de cada tipo de nó pra montar a árvore completa.