Ações

As ações alteram dados, enviam conteúdo ou integram o fluxo a outro sistema. Elas ficam na aba Ações da paleta.

Grupo	Ação	O que faz
Inteligência artificial	Analisar com IA	classifica texto ou conversa e extrai dados
Mensagens	Enviar mensagem	envia texto pelo canal da conversa
Mensagens	Enviar e-mail	envia uma campanha para uma lista de contatos
Contatos	Aplicar tag	adiciona ou remove tags do contato
Contatos	Escolher contato	coloca um contato fixo ou encontrado por identidade no contexto do fluxo
Contatos	Gravar no contato	grava um valor em um campo personalizado
Conversas	Aplicar tag na conversa	adiciona ou remove tags do atendimento
Conversas	Obter conversa do contato	localiza ou cria uma conversa em uma caixa de entrada
Atendimento	Atribuir	entrega a conversa a uma pessoa ou à fila
Atendimento	Passar para agente	troca o agente de IA da conversa
Atendimento	Concluir	encerra o atendimento e define quem assume depois
Sistemas externos	Chamar webhook	faz uma requisição HTTP para outro sistema

Entenda o contexto antes da ação

Cada execução carrega um contexto. Dependendo do gatilho e dos passos anteriores, ele pode conter contato, conversa ou ambos.

• Enviar mensagem, Aplicar tag na conversa, Atribuir, Passar para agente e Concluir exigem uma conversa.
• Aplicar tag, Gravar no contato e Obter conversa do contato exigem um contato.
• Escolher contato adiciona ou troca o contato do contexto. Ao trocar de contato, remove do contexto a conversa antiga.
• Obter conversa do contato adiciona uma conversa ao contexto.

Se uma ação obrigatória não tiver esse contexto, a execução falha nesse passo. Use Escolher contato ou Obter conversa do contato antes dela quando o gatilho não fornecer os dados necessários.

Enviar mensagem

Envia texto pelo canal da conversa atual. Não há canal para escolher. O conteúdo aceita variáveis.

Antes do envio, o SquadOS verifica:

• descadastro do contato;
• conversa adiada;
• cliente aguardando resposta humana;
• limite de mensagens automáticas por contato em 24 horas — por padrão, três;
• janela de 24 horas dos canais da Meta.

Uma etapa Aguardar imediatamente anterior pode liberar o envio quando o cliente falou por último. Se uma proteção bloquear a mensagem, o passo fica como ignorado, não como falha.

Modelo fora da janela de 24 horas

No WhatsApp Oficial, escolha um modelo aprovado como alternativa para quando a janela estiver fechada. Sem alternativa válida, a mensagem não é enviada. O Instagram Direct não usa esse modelo alternativo.

O envio é de tentativa única: a ação não repete automaticamente uma chamada que pode já ter sido entregue.

Enviar e-mail

Envia para todos os destinatários elegíveis da lista configurada cada vez que o passo é executado. Ele não envia apenas para o contato atual do fluxo.

Configure:

• Lista;
• Tags, se quiser filtrar a lista — o contato precisa ter ao menos uma das tags escolhidas;
• Assunto, com ou sem variáveis;
• Formato: texto simples ou HTML;
• Corpo, escrito no passo ou vindo de conteúdo já preparado.

O envio também exige o módulo de e-mail habilitado, remetente padrão, créditos e ao menos um destinatário inscrito, com identidade de e-mail e sem supressão de e-mail.

Para uma campanha única, use Agendamento → Enviar e-mail. Não conecte Público → Enviar e-mail: Público abre uma execução filha por contato, enquanto Enviar e-mail percorre a lista inteira em cada execução.

Descadastro e limite por contato das mensagens de automação não substituem a lista de supressão de e-mail. Mantenha as supressões de e-mail corretas antes de disparar.

Aplicar tag

Aplicar tag altera as tags do contato. Aplicar tag na conversa altera apenas as tags daquele atendimento. Em ambos os passos, selecione tags para adicionar e para remover.

Adicionar ou remover uma tag do contato também pode disparar o gatilho Tag do contato de outra automação. Planeje a saída do fluxo para não criar um ciclo.

Escolher contato

Use esta ação quando o gatilho não identifica uma pessoa ou quando o fluxo precisa continuar com outro contato. Há duas formas:

• escolher um contato fixo;
• procurar uma identidade exata de WhatsApp, Telegram, Instagram, API, web ou e-mail.

A ação não cria contatos. Se não encontrar correspondência exata, ela falha. Ao escolher um contato diferente, a conversa anterior sai do contexto; use Obter conversa do contato em seguida se as próximas ações dependerem de conversa.

Para Instagram, o valor técnico da identidade pode ser o identificador do remetente fornecido pela Meta, e não o nome de usuário visível. Confirme o valor no cadastro do contato.

Obter conversa do contato

Escolha uma caixa de entrada. O passo procura a conversa mais recente desse contato naquela caixa. Se a conversa mais recente estiver arquivada, ou se nenhuma existir, cria uma nova.

Você pode informar um título. Sem título, o sistema usa um valor padrão. A conversa nova começa com o agente ativo da caixa; se não houver um agente disponível, começa em atendimento humano.

Depois desse passo, as ações seguintes recebem a conversa e suas variáveis no contexto.

Gravar no contato

Grava um texto em um campo personalizado dentro dos metadados do contato. Por exemplo: campo cidade, valor {{analise.cidade}}.

Isso não altera campos nativos como nome, e-mail ou identidade do canal. O nome do campo é fixo; o valor aceita variáveis. É comum usar esta ação depois de Analisar com IA.

Atribuir, Passar para agente e Concluir

• Atribuir define uma pessoa responsável. Escolher Ninguém devolve a conversa à fila.
• Passar para agente ativa a IA, troca o agente associado, remove a atribuição humana e reabre uma conversa resolvida. A ação não gera uma resposta imediata. O campo Instrução para o agente não é mostrado ao cliente.
• Concluir resolve a conversa. Em Voltar para a IA, o sistema só mantém esse modo se houver um agente apto; caso contrário, preserva o atendimento humano. Veja Estados de conversa.

Chamar webhook

Faz uma requisição para um sistema externo. Configure:

• URL, com protocolo http ou https e suporte a variáveis;
• Método: GET, POST, PUT, PATCH ou DELETE — o padrão é POST;
• Cabeçalhos em pares de chave e valor;
• Corpo da requisição, com suporte a variáveis.

Por segurança, o SquadOS resolve o endereço antes da chamada e bloqueia destinos locais, privados, reservados e o próprio projeto. Redirecionamentos não são seguidos. A chamada expira após 15 segundos, só considera respostas 2xx bem-sucedidas e registra no máximo 4.000 caracteres da resposta. Não há nova tentativa automática.

Nunca coloque segredos diretamente no texto da documentação ou em exemplos compartilhados. Prefira uma credencial com escopo mínimo e possibilidade de revogação.

O que o teste comprova

No modo de teste, a maioria das ações de escrita ou envio é simulada para não alterar dados nem contatar clientes. O resultado indica o que seria feito, mas não comprova entrega externa.

Limites importantes:

• Enviar mensagem não faz o envio nem percorre todas as proteções de produção.
• Enviar e-mail não materializa destinatários nem verifica corpo, remetente, créditos ou supressões.
• Escolher contato faz a busca, mas o contato encontrado não segue para os próximos passos do teste.
• Obter conversa do contato propaga uma conversa já existente; uma conversa que seria criada não segue para o próximo passo do teste.
• Chamar webhook não valida o destino por DNS e não faz a requisição.

Depois de validar a lógica, acompanhe uma execução real controlada em Execuções e testes.

Encerrar não é uma ação

Encerrar fica na aba Regras. Ele apenas termina aquele ramo do fluxo. Veja Regras: condição, espera e encerramento.

Checklist antes de publicar

• O gatilho fornece o contato e a conversa exigidos pelas ações?
• Alguma ação troca o contato e invalida a conversa anterior?
• A lista, o remetente e as supressões de e-mail estão corretos?
• O modelo de WhatsApp cobre envios fora da janela de 24 horas?
• Tags de contato podem iniciar outro fluxo e formar um ciclo?
• O webhook aponta para um destino público permitido e trata chamadas duplicadas fora do SquadOS?
• Você validou uma execução real controlada, além da simulação?