Flow Builder: nós de consulta (lookups) e Aguardar até

Visão geral

Além de agir (enviar mensagem, criar negócio, abrir tarefa), um fluxo agora consegue ler o que já existe na plataforma e decidir com base nisso. São sete nós de consulta:

E um nó de espera inteligente:

• Aguardar até: pausa o fluxo até uma condição (o mesmo editor do nó Condição, com grupos) virar verdadeira — verificando em intervalos regulares — ou até o tempo-limite estourar.

Uma consulta nunca derruba o fluxo: qualquer falha sai pela porta Erro, que você pode ligar a um caminho alternativo.

Pré-requisitos

• O módulo Flow Builder habilitado; Administrador para editar e publicar.
• Consultar cobranças exige o módulo Pagamentos; Consultar agendamento exige o módulo Agenda. Os demais funcionam em qualquer conta (CRM/Tarefas/Commerce degradam para a saída Vazio quando o módulo não está disponível).

Passo a passo

Exemplo: deduplicar leads que chegam por webhook.

1. No gatilho Webhook, mapeie o e-mail do payload para a variável lead_email (use o botão Mapear campos automaticamente).
2. Adicione Buscar contato com Buscar por = E-mail e Valor = {{ vars.lead_email }}. Ligue Não encontrado ao caminho que cria o contato/negócio.
3. Ligue Encontrado a um Consultar CRM com Status do negócio = Aberto.
4. Na saída Encontrado do CRM, encerre o fluxo (o lead já tem negócio aberto); na saída Vazio, crie o negócio.

Dica: a galeria traz o template "Entrada de leads por webhook (dedupe + CRM)" com esse fluxo pronto.

Configurações & opções

• Variável de resultado: cada consulta grava o que encontrou numa variável (ex.: found_contact, found_deal). As listas ganham companheiras _count e _list — use {{ vars.found_deal.title }}, {{ vars.found_deal_count }} etc.
• Contato de referência: por padrão é o contato da conversa/sessão; escolha De uma variável para apontar outro (um id ou o resultado de um Buscar contato anterior).
• Usar o contato encontrado neste fluxo (Buscar contato): os próximos nós — inclusive {{ contact.* }} — passam a ler o contato encontrado. Quando a conversa já pertence a outro contato, a troca é ignorada com segurança (a variável continua disponível).
• Aguardar até: defina as condições (lista simples ou grupos TODAS/QUALQUER), o intervalo de verificação (mínimo 60 s) e o tempo-limite (obrigatório, até 30 dias). A saída Condição atendida dispara assim que a condição passar — inclusive imediatamente quando o contato responde; a saída Timeout dispara quando o prazo estoura. As verificações são limitadas (no máximo 500 por espera) e não consomem o orçamento de passos do fluxo.

Casos de uso

• Dedupe antes de criar: Buscar contato + Consultar CRM antes de abrir negócio (template pronto).
• Roteamento VIP: Buscar conversas e comparar {{ vars.found_conversations.count }} para reconhecer clientes recorrentes (template "Roteamento VIP").
• Resgate de pagamento: Consultar commerce + Aguardar até {{ commerce.stage }} = payment_confirmed (template "Resgate de pagamento pendente").
• Cobrança vencida: Consultar cobranças com status Vencida e reenviar o link (template "Aviso de cobrança vencida").

Dicas, limites e boas práticas

• As consultas retornam no máximo 10 itens (as mais recentes primeiro).
• Os dados gravados são resumos seguros (campos essenciais, sem despejar o cadastro inteiro).
• Aguardar até reavalia dados AO VIVO quando a condição usa tokens de contexto (ex.: {{ commerce.stage }}); variáveis gravadas por consultas anteriores são fotografias do momento da consulta.
• Ligue sempre a saída Erro a um caminho de contingência em fluxos críticos.

Solução de problemas

• Sempre cai em Vazio: confira o contato de referência (a sessão tem contato?) e os filtros (status/pipeline). No rastreio da sessão, o passo mostra count e o motivo (no_contact).
• Consulta de cobranças/agendamento sai em Vazio com "indisponível": o módulo correspondente está desligado para a conta.
• Aguardar até nunca dispara: confira o intervalo/tempo-limite e se a condição usa um token que realmente muda (uma variável estática nunca vai mudar sozinha).

Veja também

• Flow Builder: dados do gatilho, mapeamento e transformação
• Flow Builder: construir fluxos conversacionais visualmente
• Flow Builder: ações nativas e nó de ação de contato