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	produz um resultado estruturado e escolhe a saída do fluxo conforme o tipo
Mensagens	Enviar mensagem	envia texto pelo canal da conversa
Mensagens	Enviar e-mail	envia um e-mail ao contato do fluxo
Campanhas	Disparar campanha	envia um e-mail para uma lista inteira
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	Adicionar nota privada	grava na conversa uma nota que só a equipe vê
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, Adicionar nota privada, Atribuir, Passar para agente e Concluir exigem uma conversa.
Enviar e-mail, 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.

A publicação recusa o fluxo quando nenhum caminho entrega uma conversa aos passos que a exigem, ou um contato a Enviar e-mail e Obter conversa do contato. Nos demais casos, se o contexto faltar durante a execução, ela 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. Se o cadastro do contato não puder ser consultado nessa verificação, a mensagem não sai e o passo falha: sem confirmar o descadastro, o SquadOS não envia.

O número de destino vem da conversa; se a conversa não tiver o endereço do canal, o SquadOS usa o telefone do cadastro do contato.

Modelo fora da janela de 24 horas

No WhatsApp Oficial, escolha um modelo aprovado em Modelo aprovado, na faixa Fora da janela de 24h, como alternativa para quando a janela estiver fechada. O campo tem busca por nome ou pelo texto do modelo, e cada item mostra o idioma. A primeira opção, Não enviar nada, é o padrão. 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 um e-mail somente ao contato do fluxo, para o endereço do cadastro dele. Configure:

Assunto, com ou sem variáveis;
Formato: texto simples ou HTML;
Corpo, escrito no passo ou vindo de conteúdo já preparado.

O passo exige um contato no contexto e o módulo de e-mail habilitado, com remetente padrão. Se o contato não tiver e-mail cadastrado, o passo falha. O contato não precisa estar inscrito em uma lista, mas descadastro, limite de mensagens automáticas por contato e supressões de e-mail continuam valendo. A janela de 24 horas da Meta não se aplica a e-mail.

Disparar campanha

Fica na seção Campanhas da paleta. Envia para todos os destinatários elegíveis da lista configurada cada vez que o passo é executado — não 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; vazio envia para a lista inteira;
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.

Disparar campanha só publica quando o único gatilho que chega até ele é Agendar. Qualquer outro gatilho — inclusive Audiência, que abre uma execução por contato — roda várias vezes e faria a lista inteira receber o e-mail a cada execução; a publicação recusa o fluxo e aponta o gatilho em questão. Para escrever a quem entrou no fluxo, use Enviar e-mail.

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.

Quando precisa criar a conversa e existe um Enviar mensagem depois dele, em qualquer ramo, o passo confere antes se a mensagem terá para onde ir. Ele falha, sem criar nada, em dois casos:

o contato não tem telefone cadastrado, e é por ele que a mensagem sairia no canal;
a caixa é de um canal, como Telegram ou Instagram, em que a automação só alcança quem já enviou mensagem antes — escolha uma caixa de WhatsApp.

Reaproveitar uma conversa existente, ou criar uma para atribuir, marcar ou transferir sem enviar mensagem, não passa por essa verificação.

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.

Adicionar nota privada

Grava na conversa uma nota privada para a equipe. Preencha Nota; o texto aceita variáveis dos passos anteriores e é cortado em 4.000 caracteres.

A nota aparece na linha do tempo da conversa com o cadeado Só sua equipe vê e o nome da automação que a escreveu.
O cliente nunca recebe a nota, e ela não entra nas mensagens da conversa que o agente de IA lê.
Se o texto ficar vazio depois de preencher as variáveis, o passo falha.
O passo exige uma conversa no contexto; a publicação recusa o fluxo quando nenhum caminho entrega uma.

Nos passos seguintes, {{<id do passo>.note_id}} e {{<id do passo>.length}} trazem o identificador da nota e o tamanho do texto gravado.

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.

Colar cURL

Se o sistema de destino documenta a chamada como um comando curl, use Colar cURL, acima dos campos. O SquadOS lê o comando no próprio navegador, mostra uma prévia do que vai entrar e preenche URL, método, cabeçalhos e corpo. Se o passo já tiver valores, ele pede confirmação antes de substituir todos.

O método vem de -X/--request; sem ele, um comando com corpo vira POST e um sem corpo vira GET.
Cabeçalhos vêm de -H; o corpo, de -d, --data, --data-raw, --data-binary ou --json; -u usuário:senha vira um cabeçalho Authorization: Basic.
Opções sem equivalente no passo — cookies, proxy, certificados, tempo limite, -F/--form (multipart) e opções como -s, -k ou -L — são ignoradas e listadas na prévia.
Variáveis de shell, como $TOKEN, entram como texto literal. Troque-as pelo valor ou por uma variável do SquadOS.

Corpo em Campos ou JSON

O corpo tem dois modos:

Campos (padrão em passos novos) — cada linha é um par de chave e valor, e o SquadOS monta o JSON com aspas e escape corretos. Um valor que é só uma variável, como {{analise.idade}}, mantém o tipo dela: número, verdadeiro/falso, objeto, lista ou nulo; uma variável sem valor vira null. Qualquer outro valor, inclusive um número digitado, segue como texto.
JSON — você escreve o corpo inteiro. As variáveis são inseridas como texto, então as aspas ficam por sua conta.

Ao trocar de modo, o conteúdo é convertido. Um JSON com níveis aninhados não volta para Campos. Cabeçalhos e corpo ficam gravados na configuração do passo como texto; use uma credencial com escopo mínimo e que possa ser revogada.

Testar chamada

A faixa Testar chamada, no painel do passo, faz uma requisição real, a partir do servidor do SquadOS, só deste passo e com a configuração que está no painel — sem salvar a automação e sem executar os outros passos. Escolha a conversa, o contato ou o payload de teste conforme o gatilho; eles preenchem {{contact.*}}, {{conversation.*}} e {{trigger.payload.*}}, mas variáveis de passos anteriores ficam vazias.

O resultado mostra o status HTTP (ou Sem resposta), o tempo, a resposta formatada quando é JSON e, em Requisição enviada, o método, a URL, os cabeçalhos e o corpo exatamente como saíram. O último teste de cada passo fica guardado, com valores de cabeçalhos sensíveis (como Authorization, chaves de API e tokens) mascarados, e serve de amostra para o seletor de variáveis.

Usar a resposta nos passos seguintes

Depois do webhook, os passos seguintes podem usar:

{{<id do passo>.status}} — o código HTTP;
{{<id do passo>.body}} — o texto da resposta, até 4.000 caracteres;
{{<id do passo>.json.campo}} — um campo da resposta JSON; use ponto para descer níveis e para índices de lista, como {{n5.json.itens.0.nome}}.

json só é preenchido quando a resposta declara Content-Type JSON e cabe em 16 KB. Depois de um Testar chamada bem-sucedido, o seletor de variáveis lista os campos da resposta real com os valores recebidos.

Segurança e limites

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; numa resposta de erro, o passo falha, mas status e resposta ficam registrados. Não há nova tentativa automática. O cabeçalho Content-Type: application/json é enviado por padrão e pode ser substituído nos Cabeçalhos; em GET, nenhum corpo é enviado.

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 e Disparar campanha não enviam, não materializam destinatários nem verificam corpo, remetente, créditos ou supressões.
Adicionar nota privada não grava a nota; o resultado mostra o texto que seria gravado.
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 é exceção: a requisição é feita de verdade, tanto no teste da automação quanto em Testar chamada. Aponte para um destino de teste ou garanta que o sistema externo tolere a chamada.

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?
Disparar campanha parte só de Agendar, e o e-mail para uma pessoa usa Enviar e-mail?
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?