Variáveis

Uma variável é um caminho entre chaves duplas que o SquadOS substitui pelo valor da execução. Por exemplo, Oi, {{contact.first_name}}! 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;
• título de Obter conversa do contato;
• instrução de Transferir 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
contact.first_name	primeiro trecho de display_name, separado por espaço
contact.display_name	nome como foi recebido do canal ou cadastro
contact.identity_value	telefone, e-mail, usuário ou outro identificador 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.

contact.first_name não é um campo cadastrado separadamente. Ele é derivado do primeiro trecho de display_name. 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, contact.identity_type 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 payload real contém trigger.payload.scheduled_for e trigger.payload.fired_at. O seletor mostra indevidamente os três campos de lista; digite os caminhos de agenda manualmente se precisar deles. 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 campo declarado em Analisar com IA vira uma variável depois que o passo termina. O caminho combina o ID do nó com o nome do campo, por exemplo {{n5.intencao_de_compra}}.

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.

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
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
Público	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. Porém, ela valida a disponibilidade do namespace, não o catálogo de campos internos. Assim, {{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 {{contact.first_name}} 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, digite scheduled_for ou fired_at 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.