Gatilhos da automação

O gatilho define quando e por onde uma automação começa. Ele precisa ser o primeiro passo de cada caminho; um fluxo sem gatilho ou com gatilho sem saída não salva.

Na aba Gatilhos da paleta há sete tipos:

Seção	Gatilho	Inicia quando	Contexto entregue ao caminho
Conversas	Evento da conversa	um dos sete eventos escolhidos acontece	conversa e contato
Conversas	Conversa sem resposta	uma conversa elegível ultrapassa o tempo de silêncio	conversa e contato
Conversas	Comando	alguém da equipe aperta o botão no painel da conversa	conversa, contato e quem apertou
Contatos	Tag do contato	uma tag é adicionada ou removida	contato
Contatos	Contato adicionado à lista	a inscrição passa para o estado inscrito	contato e dados da lista
Agenda	Agendar	chega uma ocorrência única ou recorrente	dados do horário; nenhum contato ou conversa
Campanhas	Audiência	chega o horário de percorrer uma lista	um contato por execução; nenhuma conversa

Não confunda esses pontos de entrada com os gatilhos de canal, que criam caixas por onde mensagens chegam ao SquadOS.

Evento da conversa

Selecione um ou mais acontecimentos. Cada ocorrência compatível pode iniciar uma execução:

Evento na interface	O que representa
é criada	o registro da conversa foi criado
é atribuída a alguém	uma pessoa da equipe tornou-se responsável
é transferida	o atendimento mudou de responsável
é passada para um agente	um agente de IA assumiu
é concluída	o atendimento foi encerrado
é reaberta	uma conversa concluída voltou a ficar ativa
tem a IA ligada ou desligada	o modo de atendimento por IA mudou

Os filtros são avaliados com o estado disponível no instante do evento. Por exemplo, uma tag aplicada depois da criação não faz o evento é criada voltar a ser avaliado.

“Uma vez por conversa” não é uma propriedade deste gatilho: é o modo padrão de Reentrada da automação. Em Sempre, cada novo evento compatível pode gerar outra execução e voltar a consumir créditos nos passos de IA. Veja Criando uma automação.

Conversa sem resposta

Use este gatilho para follow-up. Ele considera conversas externas ativas em que:

a última mensagem foi enviada pela sua equipe e o contato ainda não respondeu;
o tempo desde essa mensagem ultrapassou Tempo sem resposta;
ninguém da equipe assumiu a conversa sem ter respondido ainda — quem assume pela tela fica com a vez de falar, e a conversa só volta a contar depois que essa pessoa responder;
a conversa não está excluída nem adiada para uma data futura;
o contato não recusou comunicações de saída;
não há outra execução ativa desta automação para a mesma conversa;
todos os filtros configurados são verdadeiros.

Mensagens do agente de IA, de pessoas da equipe e de automações contam igualmente como “sua equipe”. A própria mensagem que esta automação enviou não abre um novo ciclo: a conversa só volta a entrar depois que o contato responder, alguém da equipe falar de novo e o silêncio recomeçar.

O valor inicial visível é 2 horas. A varredura acontece em ciclos de aproximadamente 15 minutos, portanto o início não é garantido no segundo exato em que o limite é alcançado. Logo antes do primeiro passo, a conversa é conferida outra vez; se deixou de se qualificar nesse intervalo (o contato respondeu, alguém assumiu, um filtro deixou de valer), a execução termina como Cancelada e o gatilho aparece como Pulado em Atividade.

Em Proteções, você pode ligar:

Desistir depois de um tempo — define a idade máxima do silêncio. Se o mínimo for 2 horas e o máximo 7 dias, entram conversas entre esses dois limites; histórico mais antigo fica de fora.
Esperar antes de entrar de novo — impede nova entrada durante o intervalo contado desde o fim da execução anterior, inclusive se ela falhou ou foi cancelada.

Essas proteções começam desligadas. O gatilho ainda impede duas execuções simultâneas na mesma conversa e usa um ciclo novo quando a equipe fala novamente e o contato volta a ficar em silêncio.

Follow-up para um agente específico

O follow-up é uma automação da organização, não uma configuração do agente de IA. Sem filtros, o Tempo sem resposta vale para toda conversa externa que cumprir as regras acima, qualquer que seja o agente ou a pessoa que atende. Para limitar o follow-up às conversas de um agente:

Abra o gatilho Conversa sem resposta (ou crie a automação pelo modelo Follow-up de conversa parada).
Em Filtros, clique em Adicionar filtro e escolha Dono da conversa.
Mantenha o verbo é e, em quem?, escolha o agente no grupo Agentes. Para cobrir mais de um agente na mesma regra, selecione vários: eles são unidos por ou.
Se precisar, combine com Caixa de entrada, Canal, Tag da conversa ou Tag do contato; todos os filtros precisam ser verdadeiros.
Salve e ative a automação.

Dono da conversa considera quem está no comando agora. A conversa só conta como do agente enquanto a IA estiver ligada nela; se uma pessoa da equipe assumir, a conversa deixa de corresponder ao filtro, mesmo que o agente continue associado a ela.

Esse filtro é conferido na varredura e de novo antes do primeiro passo, mas não depois de um Aguardar. Se o fluxo tem vários envios separados por esperas e alguém assumir a conversa durante a espera sem que o contato responda, os envios seguintes continuam. Para evitar isso, coloque uma Condição antes de cada envio posterior, comparando {{conversation.assigned_to}} com o operador está vazio, e ligue a saída Nenhum a Encerrar.

Quando cada agente precisa de outro texto ou de outro tempo, crie uma automação por agente, cada uma com seu filtro. A mensagem sai pela caixa de entrada da conversa, como as demais mensagens automáticas, e a conversa continua com o agente: quando o contato responde, o agente atende normalmente, e as esperas com O contato responder encerram o follow-up.

Filtros de conversa

Evento da conversa e Conversa sem resposta compartilham Adicionar filtro. Os seis critérios oferecidos para novas condições são:

Critério	O que verifica
Caixa de entrada	a caixa atual
Dono da conversa	uma pessoa, um agente de IA ou Ninguém; considera quem está no comando agora
Tag da conversa	tags daquele atendimento específico
Tag do contato	tags do cadastro, compartilhadas entre conversas
Canal	família API, E-mail, Instagram, Telegram ou WhatsApp
IA da conversa	Ligada ou Desligada

As regras de combinação são:

condições diferentes são unidas por E: todas precisam ser verdadeiras;
dentro de uma condição positiva, vários valores são unidos por OU;
uma condição negativa exclui qualquer item selecionado;
cada critério pode aparecer apenas uma vez;
uma condição sem valor impede o salvamento;
sem filtros, qualquer conversa que cumpra as demais regras do gatilho é elegível.

Automações antigas podem exibir os critérios legados Agente ou Responsável. Eles continuam sendo lidos, mas novas condições usam Dono da conversa, que reúne pessoa e agente sem confundir um agente anterior com o responsável atual.

Comando

Comando transforma a automação num botão que a equipe aperta dentro de uma conversa. O botão aparece na seção Comandos da aba Conversa, no painel Contexto, somente enquanto a automação estiver ativa. Mudanças no gatilho passam a valer depois que você salva a versão.

Em O botão, preencha:

Nome do botão — obrigatório; escreva o que ele faz, como Consultar matrícula, e não o nome da automação;
Explicação do botão — linha opcional exibida embaixo do nome;
Confirmação antes de executar — Sempre pedir (padrão) ou Só quando a conversa tiver aviso.

A confirmação mostra, em Este comando vai executar:, a sequência de passos, com destaque para os que agem fora da conversa, e avisa quando uma Condição pode levar a outros caminhos. Abaixo vêm os efeitos: enviar mensagem ou e-mail, chamar um sistema externo ou usar IA, que consome créditos. Confirme em Executar.

Quando decidir se pede confirmação, o SquadOS separa dois tipos de fluxo:

Fluxo que fala com o cliente (Enviar mensagem, Enviar e-mail ou Disparar campanha) — sempre pede confirmação, mesmo com Só quando a conversa tiver aviso. Só nesse caso os avisos da conversa são consultados: conversa adiada, cliente esperando resposta e limite diário de mensagens automáticas atingido aparecem na confirmação e são dispensados por quem confirma.
Fluxo que não fala com o cliente — com Sempre pedir, a confirmação aparece se houver webhook ou IA; com Só quando a conversa tiver aviso, executa direto. Um fluxo sem nenhum efeito externo executa direto nos dois modos.

Descadastro do contato e janela de 24 horas da Meta não aparecem na confirmação e não podem ser dispensados. Se bloquearem um envio, a execução do comando falha nesse passo, em vez de pular o envio.

Quem vê

Em Quem vê, marque os Departamentos que podem ver o botão.

Sem nenhum departamento marcado, o botão aparece para todos que têm Usar comandos; a faixa fechada mostra Todos que usam comandos.
Com departamentos marcados, só quem está em um deles vê o botão. Um departamento arquivado deixa de contar.
O Proprietário vê todos os botões.

Usar comandos é uma permissão geral, dada a um departamento ou a uma pessoa. Em qualquer caso, a pessoa também precisa de Atender na caixa daquela conversa. Veja Departamentos e acessos.

Onde aparece

Adicionar filtro usa os mesmos critérios de Filtros de conversa, mas aqui eles decidem em que conversas o botão aparece, não quando algo dispara. Sem filtros, ele aparece em qualquer conversa das caixas externas.

Ao apertar

Enquanto um comando roda, o botão mostra Executando… no lugar da explicação, os demais botões da conversa ficam indisponíveis, e o mesmo comando não pode ser disparado de novo na conversa até terminar. Ao final, um aviso informa se ele terminou, se continua rodando ou se falhou; nesse caso, confira a aba Atividade.

O comando ignora o modo de Reentrada: cada clique pode gerar uma nova execução. Além de conversation e contact, o caminho recebe {{trigger.payload.invoked_by_name}} (quem apertou) e {{trigger.payload.label}} (nome do botão), úteis, por exemplo, numa nota interna.

Tag do contato

Escolha Adicionada ou Removida e, opcionalmente, uma ou mais tags. Sem tag selecionada, o gatilho vale para qualquer tag daquela operação.

Uma alteração feita pelo passo Aplicar tag também conta. Isso permite encadear automações, mas revise a Reentrada antes de criar fluxos que adicionam, removem e reaplicam as tags usadas como gatilho: em Sempre, uma cadeia pode voltar a disparar e consumir créditos repetidamente.

Este gatilho entrega contact, mas não conversation. Para usar Enviar mensagem, Atribuir, Concluir, Transferir para agente ou Tag da conversa, adicione antes Obter conversa do contato e escolha a caixa correta.

Contato adicionado à lista

O gatilho dispara quando uma associação com a lista entra no estado subscribed: numa inclusão nova ou numa atualização que sai de outro estado. Um contato que já estava inscrito e continua inscrito não dispara novamente.

Você pode escolher uma lista específica ou deixar qualquer lista. Inclusão manual, importação, formulário e API pública de listas passam pelo mesmo evento quando produzem uma inscrição válida.

Além de contact, o caminho recebe:

{{trigger.payload.list_name}} — nome da lista;
{{trigger.payload.list_id}} — identificador da lista;
{{trigger.payload.consent_source}} — origem registrada do consentimento.

Assim como Tag do contato, este gatilho não entrega conversa. Use Obter conversa do contato antes de passos que exigem atendimento.

Agendar

Agendar executa o mesmo caminho em horários definidos, sem selecionar público. O nó nasce como recorrente, todo dia às 09:00, e aceita:

Uma vez — data e hora futuras;
a cada N minutos ou horas, com intervalo mínimo de 15 minutos;
todo dia, toda semana ou todo mês, no horário escolhido;
recorrência mensal do dia 1 ao 31; em mês sem o dia escolhido, usa o último dia.

O relógio continua criando ocorrências sem esperar o fluxo anterior terminar. Portanto, uma frequência curta pode manter várias execuções simultâneas se o caminho contiver uma espera longa. O modo de reentrada não deduplica ocorrências da agenda.

Este gatilho não entrega contato nem conversa. Para executar algo sobre uma pessoa, adicione Escolher contato; para passos de atendimento, acrescente depois Obter conversa do contato.

O runtime fornece {{trigger.payload.scheduled_for}} (horário planejado) e {{trigger.payload.fired_at}} (horário em que o motor iniciou a ocorrência). As duas aparecem em Inserir variável nos passos seguintes.

Audiência

Audiência percorre os contatos de uma lista na data marcada. Diferentemente de Agendar, ela cria uma execução filha para cada contato elegível.

A lista é obrigatória.
Tags são opcionais; com várias, basta o contato ter uma delas.
O público é lido quando cada rodada começa, não quando a automação é configurada.
Só entram associações subscribed, contatos sem opt-out de saída e registros que não foram absorvidos por uma mesclagem.
Públicos grandes são processados em lotes de até 500 contatos.

A agenda aceita os mesmos modos e o mesmo piso de 15 minutos de Agendar. Na recorrência, a próxima campanha é marcada depois que o fan-out da rodada atual termina. O problema de fuso do navegador descrito acima também se aplica ao modo Uma vez.

Cada execução filha recebe contact, mas não conversation. Um envio de e-mail pode trabalhar com contato/lista; passos do canal de atendimento precisam de Obter conversa do contato.

Mais de um gatilho

Tipos diferentes podem iniciar caminhos diferentes e depois convergir. Quando caminhos convergem, um passo só pode usar símbolos disponíveis em todos eles. Por exemplo, um caminho de conversa e outro de contato perdem conversation na convergência até que todos passem por Obter conversa do contato. Consulte Variáveis.

Gatilhos do mesmo tipo têm restrições para evitar duas execuções para o mesmo acontecimento:

dois Eventos da conversa podem coexistir quando não compartilham eventos. Se compartilham um evento e qualquer um usa os filtros atuais, o salvamento recusa mesmo que as condições pareçam diferentes;
duas Tags do contato precisam de operações ou conjuntos de tags que não se cruzem; “qualquer tag” se sobrepõe a todas;
dois Contatos adicionados à lista precisam apontar para listas específicas diferentes; “qualquer lista” se sobrepõe a todas;
só pode haver um Conversa sem resposta, um Agendar e um Audiência na mesma automação.

Cada gatilho precisa de uma saída. No teste de uma automação com vários gatilhos, selecione Qual gatilho simular e forneça uma conversa, contato ou payload compatível. O teste ignora a reentrada e simula ações de envio, mas executa IA de verdade, podendo consumir créditos, e faz as chamadas de webhook de verdade.

Checklist do gatilho

O tipo corresponde ao acontecimento real, e Agendar não foi confundido com Audiência.
Em Comando, Quem vê e os filtros de Onde aparece mostram o botão só para quem deve usá-lo.
Eventos, tempo mínimo, lista e data obrigatórios estão preenchidos.
Filtros usam o estado que existirá no instante do disparo.
O contexto entregue pelo gatilho sustenta todos os passos seguintes.
A reentrada não transforma eventos repetidos em execuções indesejadas.
Agendas e audiências foram conferidas no fuso correto e com frequência segura.
Cada gatilho foi testado pelo seu próprio caminho e o resultado foi revisado em Atividade.