Tema
Referência do nó
Kind
startCategoriaGatilhosStart — Início do fluxo
Para que serve
É a porta de entrada do seu fluxo. Pense no Start como o botão "ligar" de uma máquina: sem ele, nada acontece. Cada fluxo tem exatamente um nó Start — é o ponto de entrada único por onde todas as ativações chegam, independentemente de qual gatilho dispara.
Quando usar
- Quando o fluxo vai ser iniciado manualmente por um atendente (ex.: enviar uma sequência de boas-vindas para um contato específico).
- Quando o fluxo vai ser ativado por uma mensagem recebida em um canal (WhatsApp, por exemplo).
- Quando você quer testar um fluxo rapidamente pelo simulador.
Passo a passo
- No painel lateral esquerdo, localize a categoria **Gatilhos** e arraste o bloco **Start** para o canvas.
Painel de busca de blocos aberto no canvas, com as categorias e a lista de nós disponíveis para arrastar
- Clique no bloco Start para abrir o painel de configuração à direita.
Painel de configuração do Início, com os campos Quando iniciar, Informações coletadas e Entradas/Saídas de subfluxo
- Conecte a saída do Start ao próximo bloco do seu fluxo arrastando a seta de conexão.
Blocos conectados no canvas, com a seta de ligação entre o Início e o próximo passo do fluxo
Campos
| Campo | O que faz |
|---|---|
| Título | Nome interno do nó (só aparece no canvas, ajuda a se organizar) |
Na maioria dos gatilhos, o Start não exige configuração adicional além do "Quando iniciar" — ele existe para marcar o ponto de entrada e carregar as variáveis iniciais do contexto (contato, canal, conversa). A exceção é o gatilho por mensagem recebida, que tem a opção de agrupamento descrita a seguir.
Múltiplos gatilhos no mesmo Start
Um nó Start pode ter vários gatilhos configurados ao mesmo tempo. Qualquer um deles dispara o fluxo — o contato entra no Start por meio do gatilho que ocorrer, e o fluxo segue seu caminho normalmente a partir daí.
Quando usar
- Múltiplas formas de iniciar o mesmo fluxo: por palavra-chave (contato digita "ajuda") ou por evento do sistema (problema relatado) ou por webhook (sistema externo notifica).
- Reação rápida: em vez de manter vários fluxos separados fazendo quase a mesma coisa, concentra a lógica em um único nó.
- Gatilhos que se complementam: agendamento (toda segunda-feira) e campo do contato alterado (quando o status muda) ambos iniciando a mesma sequência.
Regras e restrições
Nem toda combinação de gatilhos faz sentido junto. Aqui estão as restrições:
Limite por tipo de gatilho:
- Gatilhos que permitem múltiplas instâncias: até 10 do mesmo tipo quando o tipo em questão é Evento do Sistema (diferentes eventos), Palavra-chave (diferentes palavras), Agendamento (diferentes horários/frequências) ou Campo do Contato Alterado (diferentes campos observados).
- Gatilhos com limite de 1 por Start: Entrada Manual, Mensagem Recebida, Novo Contato, Webhook, Envio de Formulário, Data do Contato — no máximo um de cada tipo, nunca dois "Mensagem Recebida" no mesmo Start.
Conflitos e incompatibilidades:
- Aguardando Resposta do Usuário (user_input) é exclusivo: se estiver configurado no Start, é o único gatilho permitido — nenhum outro gatilho pode coexistir com ele.
- Mensagem Recebida e Evento do Sistema para "Mensagem Recebida" são a mesma coisa: não coloque ambos no mesmo Start (redundância de disparo).
Gatilhos que acontecem juntos disparam o fluxo uma vez só: Alguns eventos ocorrem simultaneamente na mesma ação. A primeira mensagem de um número novo, por exemplo, cria o contato (Contato criado), abre a conversa (Conversa aberta) e registra a mensagem (Mensagem recebida) — tudo de uma vez. Se o mesmo fluxo assina dois desses eventos, ele é iniciado uma única vez, não duas: o contato não recebe a mensagem de boas-vindas duplicada.
Quando Contato criado e Conversa aberta estão no mesmo Start, quem inicia o fluxo na primeira mensagem de um número novo é a Conversa aberta. Assim a execução já nasce com a conversa, o canal e as variáveis {{conversation.*}} preenchidas, e a primeira mensagem do fluxo chega normalmente. Contatos criados por importação ou API, que não abrem conversa, continuam iniciando o fluxo pelo Contato criado. Se você configurou filtros no gatilho Conversa aberta, são eles que decidem se o fluxo inicia nesse caso.
Isso vale apenas para eventos da mesma ação. Dois turnos de conversa diferentes continuam iniciando o fluxo duas vezes, como esperado.
Compatibilidade com fluxos antigos: Fluxos criados antes desta mudança continuam funcionando sem nenhuma ação necessária. Um fluxo com um único gatilho permanece um gatilho único — não precisa ser republicado nem reconfigured. Quando você abre o nó Start de um fluxo já publicado, o painel permite adicionar mais gatilhos se quiser modernizá-lo, mas nada é forçado.
Dica
Ao adicionar um segundo gatilho a um Start que já estava publicado, o fluxo já em execução (ativações antigas) continua ignorando o novo gatilho — só passa a reagir a ele na próxima vez que você publicar. Confirme que a publicação aconteceu e verifique nas métricas que o novo gatilho está sendo capturado.
Disparar quando a conversa abre
Quando o "Quando iniciar" está configurado para o evento Conversa aberta, o fluxo dispara toda vez que uma conversa entra no status Aberta — tanto quando um lead novo manda a primeira mensagem e a conversa nasce aberta, quanto quando uma conversa fechada anteriormente é reaberta por uma nova mensagem do contato.
Dica
Use este gatilho para uma sequência de boas-vindas ou triagem inicial que deve rodar sempre que alguém "chega" na conversa — não importa se é a primeira vez ou um retorno depois de um atendimento encerrado.
Agrupar mensagens (buffer)
Quando o "Quando iniciar" está configurado para o evento Mensagem Recebida, o painel do Start ganha a seção Agrupar mensagens (buffer). Ativada, ela junta mensagens que o contato manda em sequência rápida (rajada) e só dispara o fluxo depois que ele para de mandar mensagem — em vez de rodar o fluxo uma vez para cada mensagem separada.
Quando usar
- O contato costuma mandar a mesma ideia fatiada em várias mensagens seguidas ("Oi", "quero saber sobre", "meu processo").
- Você quer consolidar tudo antes de mandar para um nó de IA ou de condição, para não processar frases incompletas.
- O contato pode mandar um áudio e, logo depois, um texto complementar, e você quer que o fluxo veja os dois.
Campos
| Campo | O que faz |
|---|---|
| Agrupar mensagens (buffer) | Liga/desliga o agrupamento. Desligado por padrão |
| Aguardar (ms) | Janela de silêncio: tempo sem mensagem nova para considerar que o contato terminou (500 a 15000ms, padrão 2000ms) |
| Máximo de mensagens | Teto de mensagens agrupadas numa mesma rajada antes de forçar o disparo, mesmo que o contato não tenha parado de digitar (2 a 100, padrão 10) |
Atenção
O agrupamento só passa a valer depois de publicar o fluxo — é a publicação que leva a configuração para o motor. Se você ligou o toggle e o bot continua respondendo mensagem por mensagem, publique o fluxo novamente.
Vale para toda a conversa, não só para o primeiro disparo
O agrupamento vale nos dois momentos em que uma mensagem do contato chega ao fluxo:
- no disparo, quando a mensagem faz o fluxo começar; e
- no meio da conversa, quando o fluxo está parado num bloco de espera (ex.: Esperar Texto ou um bloco de IA aguardando resposta) e a mensagem do contato retoma a execução.
É a segunda situação que aparece na prática dos fluxos de IA: a partir da primeira resposta do bot, cada mensagem nova do contato retoma o fluxo. Com o agrupamento ligado, a rajada inteira é consolidada e o bot responde uma vez só, depois da janela de silêncio.
Atenção
Até esta correção, o agrupamento só era aplicado no disparo — da primeira resposta do bot em diante, cada mensagem do contato era respondida na hora, uma por uma, como se o buffer estivesse desligado. Em fluxo de IA isso ficava evidente: respostas instantâneas e picadas, uma por mensagem. Ligar o toggle não tinha efeito nesse trecho da conversa.
Como as mensagens agrupadas chegam no fluxo
O texto de event.message.content e de event.inbound_text (além de userinput.query) vira a concatenação, em ordem, de cada mensagem agrupada, separadas por quebra de linha. A mesma mensagem nunca entra duas vezes na concatenação, nem no histórico de conversa do agente, mesmo quando ela chega pelos dois caminhos (disparo e retomada). Se o contato enviar novas mensagens enquanto uma execução anterior ainda estiver em processamento, elas também são retidas na fila do buffer e processadas em um único turno combinado assim que a execução em andamento terminar.
Para mídia, a regra é diferente: a mídia sempre vence sobre a mensagem mais recente. Se o contato manda um áudio e, na mesma janela de agrupamento, manda um texto logo em seguida, event.has_media continua true e event.message (com media_url, media_type, etc.) continua sendo o do áudio — mesmo o áudio não sendo a última mensagem da rajada. Se mais de uma mídia for agrupada na mesma rajada, a mais recente ainda fica em event.message/event.message_id, e a lista completa, na ordem em que chegaram, fica disponível em event.media_items (campo adicional — nunca substitui event.message).
Atenção
Antes desta correção, mídia e texto agrupados na mesma rajada faziam a mídia desaparecer silenciosamente: como uma mensagem de áudio ou imagem chega com inbound_text vazio, se um texto chegasse logo depois dentro da janela de silêncio, event.has_media virava false e o nó de mídia (ex.: Entender Mídia) nunca rodava — sem erro nenhum. Isso já está corrigido: a mídia agrupada nunca é mais perdida, independente da ordem de chegada.
Dica
Se a janela de silêncio for muito longa (ex.: 10 segundos), o contato pode ter a sensação de que o sistema não está respondendo. Valores entre 1500ms e 3000ms costumam ser um bom equilíbrio — a mesma faixa recomendada para o bloco Aguardar silêncio (debounce).
Exemplo
Você quer enviar uma mensagem de boas-vindas toda vez que um novo contato inicia uma conversa no WhatsApp. Você cria:
- Start → recebe o evento de entrada
- Enviar Mensagem → "Olá, {{contact.name}}! Como posso te ajudar?"
- Esperar Texto → aguarda a resposta do contato
Fluxo de exemplo no canvas, com os blocos conectados em sequência do Início ao Fim
Dica
Quando o fluxo é ativado por uma mensagem de WhatsApp, a variável `userinput.query` já contém o texto que o contato enviou. Você pode usar isso logo no primeiro nó após o Start.
Filtros
Todo Evento do sistema escolhido em "Quando iniciar" (mensagens, negócios, processos, contatos, conversas, sessão do WhatsApp, comentários e campanhas) ganha a seção Filtros no painel do Start. Ela recorta, dentro de todas as ocorrências desse evento, exatamente quais devem disparar o fluxo — sem precisar de um nó "Se/Senão" logo no início para descartar o que não interessa.
Para que serve
Cada linha de filtro é uma condição — campo, operador e valor. Com duas ou mais condições, um seletor E / OU aparece à esquerda da lista e define como elas se combinam:
- E (padrão): o fluxo só inicia quando todas as condições forem verdadeiras ao mesmo tempo.
- OU: basta uma condição ser verdadeira para o fluxo iniciar.
É o mesmo seletor usado no bloco Se/Senão — clique no badge para alternar. Os filtros de contato dos gatilhos Data do Contato e Campo do Contato Alterado continuam sendo sempre E.
Um exemplo comum de escritório: você quer iniciar o fluxo de triagem só quando a mensagem vem de alguém que ainda não é cliente. Sem filtro, o fluxo de triagem dispararia para toda mensagem recebida — inclusive de clientes que já têm processo em andamento, que deveriam cair direto com o atendente responsável. Com um filtro Contato é cliente É igual a Não, só quem ainda não é cliente entra na triagem; quem já é cliente simplesmente não dispara esse fluxo (e pode ser tratado por outro Start, ou seguir para o atendimento humano).
Sem nenhum filtro configurado, o gatilho dispara para toda ocorrência do evento — sem restrição nenhuma.
Atenção
Uma condição deixada em branco (sem valor escolhido) é ignorada na avaliação. Em E isso é inofensivo — as outras condições continuam valendo. Em OU, porém, ela não passa a valer como "qualquer coisa": se ela valesse, bastaria uma linha vazia para o gatilho voltar a disparar para tudo. Preencha todas as condições que pretende usar.
Como montar uma condição
Cada linha se lê como uma frase: campo + operador + valor. Clicar em qualquer uma das três partes abre um seletor só para ela.
- No painel do Start, com um evento do sistema selecionado em "Quando iniciar", clique em **Adicionar** na seção Filtros.
- Clique no primeiro pedaço da frase ("Escolher campo…") para abrir a lista de campos, organizada por grupo (Mensagem, Negócio, Processo, Tarefa, Contato, Conversa, Canal, Campos personalizados — só aparecem os grupos que o evento carrega). Digite para buscar e escolha um.
- Clique no operador para trocá-lo — a lista de operadores muda de acordo com o campo escolhido (veja a tabela de operadores abaixo).
- Se o operador exigir um valor de comparação, clique na terceira parte da frase para preenchê-lo (texto, número, seleção ou tags, conforme o campo).
- Repita para adicionar quantas condições precisar. A partir da segunda, elas aparecem unidas por uma chave à esquerda com o badge **E** — clique nele para trocar para **OU**.
Dica
Trocar o campo de uma condição já preenchida tenta preservar o operador e o valor, quando eles ainda fazem sentido para o campo novo (ex.: trocar entre dois campos de texto mantém o operador "Contém"). Trocar para um campo de tipo diferente (ex.: de texto para número) limpa o valor, já que ele deixou de fazer sentido.
Campos disponíveis
A lista completa abaixo é a de Mensagem Recebida, o evento mais completo. Os campos são agrupados exatamente como aparecem no seletor.
Mensagem
| Campo | O que faz |
|---|---|
| Tipo da mensagem | Que tipo de conteúdo é: texto, imagem, vídeo, áudio, documento, figurinha, localização, enquete, Pix e outros — veja a lista completa no aviso sobre tipos legados abaixo |
| Conteúdo da mensagem | O texto/legenda da mensagem |
| Tipo da mídia | O formato do arquivo de mídia anexado (quando a mensagem tem mídia) |
| Remetente | Quem mandou a mensagem: Contato, Atendente, Bot ou Sistema |
| Tem mídia | Se a mensagem trouxe algum arquivo — imagem, áudio, vídeo, documento etc. |
| Texto recebido | Atalho para o texto da mensagem recebida (mesmo conteúdo de "Conteúdo da mensagem") |
| Id do botão/opção clicada | O identificador do botão ou item de lista interativa que o contato clicou, quando a mensagem for uma resposta desse tipo |
Contato
| Campo | O que faz |
|---|---|
| Nome do contato | O nome cadastrado do contato |
| Telefone do contato | O telefone cadastrado do contato |
| Tipo de pessoa | Se o contato é pessoa física ou jurídica |
| Origem do contato | De onde o cadastro do contato veio (ex.: importação, formulário, cadastro manual) |
| Cidade | A cidade cadastrada do contato |
| Estado | O estado cadastrado do contato |
| Contato é cliente | Se o contato já é um cliente do escritório |
| Contato é grupo do WhatsApp | Se a conversa é com um grupo do WhatsApp, e não uma pessoa |
| Tags do contato | As tags aplicadas ao contato |
| Atendente responsável pelo contato | Qual atendente do workspace está designado como responsável pelo contato |
| Sistema jurídico do contato | O sistema jurídico externo de onde o contato foi integrado (ex.: Advbox) |
Conversa
| Campo | O que faz |
|---|---|
| Status da conversa | Aberta, Pendente, Aguardando, Transferida, Em automação ou Encerrada |
| Mensagens não lidas | Quantas mensagens da conversa ainda estão sem leitura |
| Atendente responsável pela conversa | Qual atendente do workspace está designado para essa conversa |
| Departamento da conversa | Qual departamento a conversa está associada |
| Motivo da pausa de automação | Por que a automação da conversa está pausada (ex.: atendimento humano assumido, transferida, pausa manual, adiada) |
Canal
| Campo | O que faz |
|---|---|
| Provedor do canal | O provedor técnico por trás do canal (ex.: WhatsApp Cloud API, UAZAPI, WAHA) |
| Tipo do canal | O tipo do canal: WhatsApp, Webchat, Instagram, Messenger |
| Canal da conversa | Qual canal específico do workspace recebeu a mensagem |
Campos personalizados
Todo campo personalizado de contato do workspace também aparece na lista, num grupo próprio — os mesmos campos disponíveis nos filtros de contato de Data do Contato e Campo do Contato Alterado.
Dica
Os campos disponíveis mudam um pouco de evento para evento, porque nem todo evento carrega os mesmos dados:
- Mensagem Enviada tem todos os campos acima, exceto os de mídia de entrada (Tem mídia, Texto recebido e Id do botão/opção clicada) — mensagens enviadas pelo escritório não passam por essas etapas.
- Status de Entrega Atualizado não tem os campos de conteúdo da mensagem (Tipo da mensagem, Conteúdo da mensagem, Tipo da mídia, Remetente etc.) nem Provedor do canal — em compensação, ganha um campo próprio, Status de entrega, com os valores Pendente, Enviada, Entregue, Lida ou Falhou.
- Mensagem Recebida (fluxo inbound) tem uma lista mais enxuta: só os campos essenciais de mensagem, contato e conversa (sem campos personalizados, sem tags, sem atendente/departamento).
Eventos de negócio, processo, contato e conversa
Os demais eventos do sistema trazem os campos do próprio evento e os dados do registro envolvido:
| Evento | Campos do evento | Grupos de campos |
|---|---|---|
| Negócio criado | Funil | Negócio, Contato, Campos personalizados |
| Estágio do negócio alterado | Etapa de destino, Etapa de origem, Negócio ganho, Negócio perdido | Negócio, Contato, Campos personalizados |
| Nota / documento adicionado ao negócio | — | Negócio, Contato, Campos personalizados |
| Produto adicionado ao negócio | Produto | Negócio, Contato, Campos personalizados |
| Processo criado | Grupo e tribunal informados na criação | Processo |
| Processo atualizado | Campo alterado | Processo |
| Movimentação registrada | Tipo da movimentação | Processo |
| Publicação registrada | — | Processo |
| Lançamento financeiro registrado | Tipo do lançamento | Processo |
| Tarefa do processo criada | — | Tarefa, Processo |
| Tarefa do processo atualizada | Situação da tarefa (Pendente, Concluída) | Tarefa, Processo |
| Contato criado | Origem da criação | Contato, Campos personalizados |
| Contato atualizado | Campo alterado | Contato, Campos personalizados |
| Tag adicionada ao contato | Tag adicionada | Contato, Campos personalizados |
| Contato atribuído a agente | Atendente atribuído, Departamento | Contato, Campos personalizados |
| Campo do contato alterado | Campo alterado, Novo valor, Valor anterior | Contato, Campos personalizados |
| Nota adicionada ao contato | — | Contato, Campos personalizados |
| Negócio criado para o contato | Funil do negócio | Contato, Campos personalizados |
| Conversa aberta / transferida / encerrada / em automação | Status anterior, Novo status | Conversa, Contato, Canal, Campos personalizados |
| Status da sessão WhatsApp alterado | Status da sessão | — |
| Lead de anúncio (Click to WhatsApp) | Campanha, ID do anúncio, Plataforma | — |
| Lead de formulário (Lead Ads) | Campanha, ID do formulário, ID do anúncio, Plataforma | — |
| WhatsApp Flow respondido | Campanha | — |
O grupo Negócio tem funil, etapa (exibida como "Funil › Etapa", porque nomes de etapa se repetem entre funis), situação (Em aberto, Ganho, Perdido, Arquivado), prioridade, responsável e valor. O grupo Processo tem status (Ativo, Suspenso, Arquivado, Encerrado, Não informado), área, tribunal, grupo, tipo de ação, fase, etapa, responsável, sistema jurídico de origem e se o processo está parado. O grupo Tarefa tem descrição, urgente, importante e responsável.
Atenção
**Tag adicionada** compara pelo **nome** da tag. Filtros antigos que guardaram o identificador da tag no lugar do nome aparecem como valor desconhecido e nunca casam: escolha a tag de novo na lista.
Operadores por tipo de campo
Os operadores disponíveis para uma condição mudam conforme o tipo do campo escolhido:
| Tipo do campo | Operadores |
|---|---|
| Texto (nome, conteúdo da mensagem, cidade...) | É igual a, É diferente de, É um de, Não é nenhum de, Contém, Não contém, Começa com, Termina com, Está vazio, Não está vazio |
| Número (mensagens não lidas) | É igual a, É diferente de, Maior que, Maior ou igual a, Menor que, Menor ou igual a, Está vazio, Não está vazio |
| Sim/Não (tem mídia, é cliente, é grupo...) | É igual a, É diferente de |
| Seleção (tipo da mensagem, status da conversa, atendente, canal...) | É igual a, É diferente de, É um de, Não é nenhum de, Está vazio, Não está vazio |
| Tags do contato | Tem, Não tem, Não tem nenhuma, Tem alguma |
Está vazio e Não está vazio não pedem valor de comparação — perguntam só se o campo está preenchido, o mesmo comportamento já descrito para os filtros de contato.
Atenção
O Tipo da mensagem inclui dois valores marcados **(legado)**: **Texto (legado)** e **Áudio de voz (legado)**. São valores antigos, sem nenhum produtor ativo hoje — mensagens novas nunca chegam com esses tipos. Um filtro montado com eles tende a **nunca casar** com nada, sem erro nenhum: o fluxo simplesmente não dispara. Use os equivalentes normais, **Texto** e **Áudio**, ao montar um filtro novo.
Prova real
Nos eventos de mensagem (Mensagem Recebida, Mensagem Enviada, Status de Entrega Atualizado e Mensagem Recebida do fluxo inbound), assim que você tem pelo menos uma condição configurada, aparece uma faixa de marcas logo abaixo dos filtros: Prova real. Os demais eventos não têm Prova real, porque ela é montada a partir de mensagens reais. Cada marca representa uma mensagem real e recente do workspace que combina com o evento escolhido — marca preenchida significa que aquela mensagem passaria pelo filtro e disparia o fluxo; marca apagada significa que ela seria barrada. Passe o mouse sobre uma marca para ver o horário, um resumo da mensagem e, se ela não passou, em qual condição ela reprovou.
Use a Prova real para conferir o filtro antes de publicar o fluxo. Um filtro errado não gera nenhum erro visível — o fluxo simplesmente nunca dispara, silenciosamente, e isso costuma ser mais difícil de perceber e investigar do que um erro. Ver a faixa preenchida (ou vazia) enquanto você ainda está montando o filtro é a forma mais rápida de pegar esse tipo de engano cedo.
Eventos agrupados: Campanhas e Comentários
Além dos eventos de mensageria (Mensagem Recebida, Conversa Aberta, Novo Contato, etc.), o catálogo de eventos oferece dois grupos adicionais com filtros próprios:
| Grupo | Evento | Documentação |
|---|---|---|
| Campanhas | Lead de anúncio (Click to WhatsApp) | Gatilho por Lead de Anúncio |
| Campanhas | Lead de formulário (Lead Ads) | Gatilho por Formulário de Lead Ads Enviado |
| Campanhas | WhatsApp Flow respondido | Gatilho por WhatsApp Flow Concluído |
| Comentários | Comentário recebido | Gatilho por Comentário Recebido |
Cada evento dispõe de campos filtráveis específicos, descritos em detalhe na página dedicada de cada um.
Saiba mais
- Gatilho por Webhook — iniciar um fluxo a partir de um sistema externo
- Trigger Agenda (Agendamento) — iniciar um fluxo em um horário programado
- Gatilho por Data do Contato — iniciar um fluxo antes, depois ou na data de um campo do contato
- Gatilho por Campo do Contato Alterado — iniciar um fluxo quando um campo do contato muda
- Gatilho por Comentário Recebido — iniciar um fluxo quando alguém comenta uma publicação
- Gatilho por Lead de Anúncio (Click to WhatsApp) — iniciar um fluxo quando um lead chega por um anúncio CTWA
- Gatilho por Formulário de Lead Ads Enviado — iniciar um fluxo quando um formulário de anúncio é enviado
- Gatilho por WhatsApp Flow Concluído — iniciar um fluxo quando um contato conclui um WhatsApp Flow
- Enviar Mensagem — o próximo passo típico após o Start