Variáveis

Uma variável é um caminho entre chaves duplas que o SquadOS substitui pelo valor da execução. Por exemplo, Oi, {{nome}}! pode virar Oi, Marina!.

O valor é resolvido quando o passo executa, não quando você salva o fluxo. Por isso, duas execuções da mesma versão podem produzir textos diferentes.

Onde usar

O editor oferece Inserir variável nos campos compatíveis. O seletor aparece em:

• instrução de Analisar com IA;
• texto de Enviar mensagem e valores de um modelo do WhatsApp;
• assunto e corpo de Enviar e-mail e de Disparar campanha;
• texto de Adicionar nota privada;
• título de Obter conversa do contato;
• instrução de Passar para agente;
• valor de Gravar no contato;
• URL, valores dos cabeçalhos e corpo de Chamar webhook;
• os dois lados de cada comparação em Condição.

Em Escolher contato por identidade, o valor também é interpolado no runtime, mas esse campo não mostra o seletor. Se precisar, digite um caminho válido completo, como {{contact.identity_value}}.

O seletor é contextual: ele mostra a lista recomendada para aquele ponto do fluxo. Variáveis reconhecidas ficam destacadas; uma variável que o editor não reconhece fica vermelha. O vermelho é um alerta importante, mas hoje não é uma garantia de que a publicação será bloqueada: um campo desconhecido dentro de um namespace disponível pode passar e virar vazio na execução. Não publique enquanto houver marcação vermelha.

Variáveis de conversa

Elas aparecem quando todos os caminhos que chegam ao passo entregam uma conversa.

Variável	Valor
conversation.transcript	até as 50 mensagens mais recentes, em ordem cronológica, uma por linha no formato papel: conteúdo
conversation.status	estado técnico: active, completed ou failed
conversation.inbox_id	ID da caixa de entrada
conversation.agent_id	ID do agente de IA associado
conversation.assigned_to	ID da pessoa responsável
conversation.channel_source	origem técnica do canal

O histórico completo pode ter mais de 50 mensagens. conversation.transcript mantém apenas as 50 mais recentes; não o use como arquivo integral nem suponha que o começo da conversa estará presente.

O runtime também reconhece conversation.id e conversation.ai_enabled, embora eles não apareçam no seletor atual. Como essa diferença pode mudar, prefira os caminhos oferecidos pela interface e teste qualquer uso manual antes de ativar.

Variáveis de contato

Variável	Valor
nome	primeiro nome do contato, com maiúsculas e minúsculas ajustadas
nome_completo	nome inteiro do contato, com maiúsculas e minúsculas ajustadas
contact.phone	telefone do cadastro do contato
contact.email	e-mail do cadastro do contato
contact.identity_value	telefone, e-mail, usuário ou outro identificador, conforme o canal
contact.identity_type	canal da identidade do contato
contact.metadata	objeto JSON com os campos personalizados

Para ler um campo personalizado, acrescente sua chave: {{contact.metadata.cidade}}. metadata é um objeto aberto; a chave específica não aparece no seletor e precisa ser digitada.

{{nome}} e {{nome_completo}} são as únicas variáveis sem prefixo, feitas para entrar numa frase. {{nome}} é o primeiro trecho do nome do contato, separado por espaço. Nas duas, um nome escrito todo em maiúsculas ou todo em minúsculas, como MARIA DA SILVA, sai como Maria da Silva; nomes com caixa mista, como McDonald, ficam como estão.

As formas antigas continuam valendo: {{contact.first_name}} equivale a {{nome}}, com o mesmo ajuste de caixa. {{contact.display_name}} traz o nome exatamente como foi gravado, sem ajuste — use-o em webhook, condição ou gravação de campo, onde o dado original importa.

Se o contato não tiver nome, o resultado pode ficar vazio; se o nome recebido for um telefone ou e-mail, esse próprio valor pode aparecer. Para uma saudação segura, mantenha texto fixo que ainda faça sentido sem a variável.

O runtime também reconhece contact.id e contact.outbound_opt_out_at, mas o seletor não os oferece.

Dados do gatilho

O namespace é trigger.payload.

No gatilho Contato adicionado à lista, o seletor oferece:

Variável	Valor
trigger.payload.list_name	nome da lista
trigger.payload.list_id	ID da lista
trigger.payload.consent_source	origem do consentimento recebida no evento

No gatilho Agendar, o seletor oferece trigger.payload.scheduled_for (horário planejado) e trigger.payload.fired_at (horário em que o motor iniciou a ocorrência). No gatilho Comando, oferece trigger.payload.invoked_by_name (quem apertou o botão) e trigger.payload.label (nome do botão). Quando dois gatilhos chegam ao mesmo passo, o seletor soma os campos de cada um. Os demais gatilhos não prometem campos próprios de payload.

Objetos dentro de trigger.payload também podem ser acessados por pontos, desde que o evento realmente entregue aquela estrutura.

Saída de Analisar com IA

Cada nova Analisar com IA devolve uma única variável depois do sucesso. O caminho combina o ID do nó com o Nome da variável, por exemplo {{n5.intencao_de_compra}}. O formato de resultado único está publicado em Dev; sua publicação em produção ainda está pendente. Nós antigos mantêm seus campos e variáveis existentes.

O valor pode ser texto, o nome de uma opção, verdadeiro/falso ou uma pontuação. Na pontuação, a variável mantém a fração mesmo quando a saída do canvas é arredondada: {{n5.nota}} pode conter 7,3 enquanto o fluxo segue pela saída 7. O caminho escolhido e os detalhes de modelo/consumo mostrados em Atividade não criam variáveis adicionais.

A saída não existe no próprio passo que a produz nem acima dele. Ela só aparece nos passos a jusante pelos quais a análise necessariamente passou.

Resposta de Chamar webhook

Depois de um Chamar webhook, os passos seguintes recebem {{<id do passo>.status}} (código HTTP), {{<id do passo>.body}} (texto da resposta, até 4.000 caracteres) e {{<id do passo>.json}}. Para ler um campo da resposta JSON, desça com pontos, inclusive em índices de lista: {{n5.json.cliente.nome}}, {{n5.json.itens.0.id}}.

json é um objeto aberto: o editor não marca em vermelho um campo que não conhece, e um campo ausente vira vazio. Depois de um Testar chamada bem-sucedido, o seletor lista os campos da resposta real com os valores recebidos, o que evita digitar caminhos errados.

O que cada caminho entrega

Gatilho	Conversa	Contato	trigger.payload útil
Evento da conversa	sim	sim	não documentado
Conversa sem resposta	sim	sim	não documentado
Comando	sim	sim	quem apertou e nome do botão
Tag do contato	não	sim	não documentado
Contato adicionado à lista	não	sim	lista e consentimento
Agendar	não	não	horários da execução
Audiência	não	sim	não documentado

Escolher contato passa a entregar contato somente para os passos abaixo dele. Obter conversa do contato exige um contato e passa a entregar conversa somente abaixo dele.

Quando caminhos convergem, vale a interseção: o passo recebe apenas o que todos os caminhos anteriores garantem. Se Evento da conversa e Tag do contato chegam ao mesmo passo, ambos entregam contato, mas só um entrega conversa; portanto, variáveis de conversa não estão disponíveis depois da junção. Coloque Obter conversa do contato no caminho que começa sem conversa ou separe os ramos.

A publicação bloqueia um namespace ausente ou uma saída de IA que não esteja a montante. Para análises com resultado único, também exige o nome exato da variável configurada: ao renomeá-la, atualize as referências nos passos seguintes. Os campos internos de outros grupos não têm essa mesma validação: {{conversation.status}} é recusada onde não há conversa, mas {{conversation.campo_inexistente}} pode ser aceita onde há conversa e resolver como vazio.

Valores vazios, objetos e sintaxe

• valor ausente ou nulo vira texto vazio;
• número e booleano viram texto;
• objeto ou lista vira JSON;
• espaços dentro das chaves são aceitos, como {{ contact.display_name }};
• o caminho aceita letras, números, sublinhado e pontos;
• chave incompleta, hífen no caminho ou outra sintaxe não reconhecida pode permanecer literalmente no texto.

Se a mensagem inteira ou o assunto do e-mail ficar vazio depois da interpolação, aquele run falha com um alerta de configuração. Cinco falhas consecutivas do mesmo tipo no mesmo passo desativam a automação; uma execução bem-sucedida antes disso encerra a sequência. Corrija o valor, salve e reative a automação quando necessário.

Prefira um fallback textual: Olá! é seguro; apenas {{nome}} não é. Para lógica condicional, teste a variável com está vazio antes do envio.

Verifique antes de ativar

1. Use o seletor sempre que ele oferecer o caminho.
2. Elimine toda marcação vermelha, mesmo que o fluxo ainda permita salvar.
3. Confirme que todos os caminhos até o passo entregam o mesmo contexto.
4. Teste contato sem nome e metadado ausente.
5. Em agenda, use scheduled_for ou fired_at pelo seletor, com o prefixo trigger.payload.
6. Confira a aba Atividade depois das primeiras execuções reais.

O teste usa a execução real dos passos, com as limitações descritas em cada ação. Em particular, o teste de Contato adicionado à lista não preenche hoje os dados de lista do gatilho. Não trate um campo vazio nessa simulação como prova de que a entrada real também virá vazia.