Variáveis

Uma variável é um pedaço de texto que o SquadOS troca pelo valor real na hora de executar. É o que transforma “Oi!” em “Oi, Marina!” sem você escrever uma automação por pessoa.

A escrita é sempre a mesma: o caminho entre chaves duplas, como {{contact.first_name}}.

Onde elas funcionam

Em todo campo de texto que mostre o botão Inserir variável: a mensagem enviada ao cliente, o assunto e o corpo do e-mail, o valor gravado no contato, a instrução do passo de IA, a URL e o corpo de um webhook, os dois lados de uma condição.

Use o botão em vez de digitar de cabeça — ele mostra só o que vale naquele ponto do fluxo:

Variáveis válidas aparecem destacadas no campo; um caminho que não existe fica marcado em vermelho, antes de você salvar.

O que existe

Conversa

Disponível quando o fluxo tem uma conversa naquele ponto.

Variável	O que traz
conversation.transcript	todo o histórico da conversa, em texto
conversation.status	se a conversa está aberta, pendente ou resolvida
conversation.inbox_id	identificador da caixa de entrada
conversation.agent_id	identificador do agente que atende
conversation.assigned_to	identificador da pessoa responsável
conversation.channel_source	canal por onde a conversa chegou

Contato

Variável	O que traz
contact.first_name	só o primeiro nome — o melhor para saudação
contact.display_name	nome completo, como foi recebido
contact.identity_value	telefone, e-mail ou usuário do contato
contact.metadata	campos extras do cadastro

Para chegar a um campo extra específico, use ponto: contact.metadata.cidade.

Prefira contact.first_name em saudação. O display_name costuma trazer o nome inteiro como o canal mandou — e “Oi, Marina Souza Albuquerque!” não soa como gente.

Dados recebidos

Só no gatilho Contato adicionado à lista:

Variável	O que traz
trigger.payload.list_name	nome da lista em que o contato entrou
trigger.payload.list_id	identificador da lista, para comparar em condições
trigger.payload.consent_source	onde o contato deu permissão para receber mensagens

Saída de um passo de IA

Cada campo declarado nos campos de saída de um passo Analisar com IA vira uma variável, com o caminho formado pelo identificador do passo e o nome do campo — por exemplo, n5.intencao_de_compra.

Elas só valem abaixo do passo que as criou.

A regra que explica tudo: o que chega até aqui

A pergunta que o SquadOS faz para decidir se uma variável vale num passo não é “qual é o gatilho?”, e sim “o que todo caminho até aqui entrega?”.

Cada gatilho entrega um conjunto diferente:

Gatilho	Entrega conversa	Entrega contato	Entrega dados recebidos
Evento da conversa	sim	sim	—
Conversa sem resposta	sim	sim	—
Tag do contato	—	sim	—
Contato adicionado à lista	—	sim	sim
Audiência	—	sim	—

Disso saem as duas situações que mais confundem:

1. Fluxo que começa por contato não tem conversa. Numa automação que começa por tag, por lista ou por audiência, conversation.transcript não existe — e passos como Enviar mensagem também não têm onde escrever. A solução é o passo Obter conversa do contato: dali para baixo, o fluxo passa a ter conversa, e as variáveis de conversa voltam a valer.

2. Com vários gatilhos, vale só o que todos entregam. Se Evento da conversa e Tag do contato levam ao mesmo passo, o que sobra é o contato: um dos caminhos não tem conversa, então nenhuma variável de conversa vale ali. Ou você dá um caminho próprio a um dos gatilhos, ou põe Obter conversa do contato antes.

O SquadOS recusa salvar um fluxo que use variável indisponível, dizendo qual variável e por quê. É de propósito: uma variável que não resolve viraria um espaço em branco — ou as próprias chaves — na mensagem que chega ao cliente.

Quando a mensagem fica vazia

Uma variável pode existir e ainda assim não ter valor: um contato sem primeiro nome cadastrado, um campo extra que aquela pessoa não tem.

Se a mensagem inteira ficar vazia depois de montada, o SquadOS desativa a automação e avisa que “a mensagem ficou vazia ao ser montada: o texto usa uma informação que este contato não tem”. Vale escrever mensagens que continuem fazendo sentido quando a variável não tem valor — começar por “Oi!” em vez de só {{contact.first_name}}, por exemplo.