Builder · Atualizado em 06/10/2026
Como usar variáveis no Builder
Entenda as variáveis do Builder, consulte a Biblioteca de variáveis e use dados do contato e do fluxo em mensagens, condições e ações.
Uma variável é um nome que guarda um valor durante a conversa: o nome do contato, a última mensagem, uma escolha de menu, o resultado de uma consulta. Você usa o nome entre chaves duplas e o Pipe troca pelo valor na hora de executar.
Quando usar
Use variáveis para personalizar mensagens ("Oi, {{contact.name}}!"), para decidir caminhos nas condições de saída e para passar dados entre blocos e ações. Quanto mais dados do contato o fluxo reaproveita, menos o contato precisa repetir.
Pré-requisitos
- Permissão para editar o fluxo no Builder.
- Para variáveis que o próprio fluxo cria, um bloco ou ação que guarde o valor, como Definir variável ou uma resposta do contato guardada em variável.
Passo a passo
- Abra o fluxo na aba Builder.
- Clique em Biblioteca de variáveis na barra de ferramentas. O painel abre no lado esquerdo.
- Na aba Biblioteca de variáveis, use o campo de busca para procurar por nome ou tema. A busca olha o nome e a descrição.
- Leia a descrição. Se aparecer a observação Não disponível no Pipe, não use essa variável.
- Clique no ícone de copiar ao lado do nome. O Pipe copia só o nome e mostra Copiado! por um instante.
- Cole o nome no campo desejado e coloque entre chaves duplas, como
{{contact.name}}. - Para ver as variáveis do seu fluxo, abra a aba Minhas variáveis.
- Teste o fluxo. No painel de teste, a seção Variáveis mostra o valor de cada variável criada durante a conversa.
Famílias de variáveis
Os nomes seguem um prefixo que mostra de onde vem o valor.
| Prefixo | O que traz |
|---|---|
| contact | Dados do contato, como contact.name, contact.email, contact.city, contact.phoneNumber e contact.identity. Campos extras ficam em contact.extras.nome. |
| input | A mensagem atual do contato. input.content é o texto recebido e input.type é o tipo da mensagem. |
| context | Variáveis criadas pelo seu fluxo, como context.assunto. |
| calendar | Data e hora, em GMT-0: calendar.date, calendar.time, calendar.dayOfWeek, além de versões de ontem (calendar.yesterday.*) e amanhã (calendar.tomorrow.*). |
| state | Bloco atual e anterior: state.id, state.name, state.previous.id, state.previous.name. |
| random | Valores aleatórios: random.guid, random.integer, random.string. |
| config | Variáveis de configuração do fluxo, como config.nome. |
| secret | Variáveis sensíveis, que só têm valor dentro de requisições HTTP. Veja variáveis sensíveis. |
| aiAgent e aiAnswers | Dados do bloco Agente de IA e da ação AI Answers, como aiAgent.parameters, aiAgent.errorCode e aiAnswers.response. |
| resource | Recursos do fluxo, listados em Minhas variáveis. |
Algumas variáveis da biblioteca aparecem com Não disponível no Pipe, entre elas as do grupo agent (dados do atendente) e input.message.pp e input.message.ppidentity.
Como o fluxo cria variáveis
- A ação Definir variável cria ou muda uma variável pelo nome. Depois use
{{context.nome}}. - Ações como Requisição HTTP, Executar script, Executar template e Função da biblioteca guardam o resultado no nome que você informar nos campos de retorno.
- Um bloco que espera a resposta do contato pode guardar a resposta em uma variável.
- Nas condições de saída, a fonte Variável compara o valor de uma variável criada pelo fluxo.
O nome de uma variável criada em Definir variável aceita letras, números e pontos.
Exemplo na Loja Girassol
A Loja Girassol quer cumprimentar o cliente e lembrar o assunto escolhido.
- No bloco Início, a mensagem é "Oi, {{contact.name}}! Como posso ajudar?".
- No bloco Pedidos, a ação Definir variável guarda
assuntocom o valorpedido. - No bloco Atendimento humano, a mensagem é "Vou chamar uma pessoa para ajudar com {{context.assunto}}."
- No teste, a seção Variáveis mostra
assunto: pedido.
Resultado esperado
A mensagem enviada no teste mostra os valores no lugar das variáveis. A seção Variáveis do painel de teste lista as variáveis criadas, e a aba Minhas variáveis inclui os nomes novos.
Boas práticas
- Teste com contatos que não têm todos os dados. Se
contact.emailestiver vazio, a mensagem precisa continuar fazendo sentido. - Não coloque dados sensíveis em variáveis comuns que aparecem em mensagens.
- Para variáveis de teste, use Adicionar variável de teste no painel de teste, assim você simula valores sem editar o fluxo.
Limitações
- A biblioteca lista variáveis do sistema que o Pipe não preenche. Elas trazem a observação Não disponível no Pipe.
- A aba Minhas variáveis mostra o que o desenho do fluxo cria ou lê. Uma variável criada só em tempo de execução, por exemplo dentro de um script, pode não aparecer ali.
- As variáveis de data e hora usam o horário de Greenwich (GMT-0).
Problemas comuns
- A mensagem mostra as chaves em vez do valor: confira a grafia, os dois pares de chaves e o prefixo (
context.para variáveis do fluxo). - O valor vem vazio: a variável não foi criada antes do ponto de uso, ou o contato não tem aquele dado. Confira a seção Variáveis no teste.
- Não encontro uma variável na biblioteca: a busca é sensível a acentos. Tente outro termo ou procure pelo nome em inglês.
- A variável existe, mas a condição não funciona: use a fonte Variável e o nome sem chaves nas condições de saída.
Próximos passos
Perguntas frequentes
Como escrevo uma variável em uma mensagem?
Entre chaves duplas, como {{contact.name}} para o nome do contato ou {{context.assunto}} para uma variável que o seu fluxo criou.
O botão de copiar inclui as chaves?
Não. Ele copia só o nome, por exemplo contact.name. Digite as chaves duplas ao colar no texto.
O que significa Não disponível no Pipe?
Que o Pipe não preenche essa variável. Ela aparece na biblioteca, mas não deve ser usada no fluxo.
Onde vejo as variáveis que criei?
Na aba Minhas variáveis da Biblioteca de variáveis. Ela lista o que o seu fluxo cria ou lê, mais as variáveis de configuração e os recursos do fluxo.
As variáveis duram para sempre?
Não necessariamente. Definir variável aceita um prazo de expiração em segundos, e a sessão do contato pode expirar conforme a configuração do fluxo.
Esse artigo foi útil?
Obrigado pelo retorno!