Extrair variavel

A caixa Extrair variável é uma etapa de processamento. Ela não faz uma pergunta e não envia uma mensagem ao cliente. Ao ser executada, ela:

1. lê a variável de origem;
2. extrai o valor solicitado, de acordo com o formato escolhido;
3. grava o resultado em outra variável da sessão;
4. segue para a próxima etapa configurada.

Os dois formatos disponíveis têm finalidades diferentes:

Um uso comum do formato JSON é tratar a resposta de uma integração antes de apresentar o resultado, tomar uma decisão ou continuar o fluxo.

Importante: a caixa não chama uma API, não transforma uma imagem em texto e não interpreta um documento. Ela somente lê uma variável que já foi preenchida por uma etapa anterior.

Onde encontrar

1. Acesse Configuração > Fluxos.
2. Crie um fluxo ou abra uma versão existente no editor visual.
3. Na barra de ferramentas, abra o grupo Variáveis.
4. Adicione a caixa Extrair variável ao diagrama.
5. Selecione a caixa para abrir o painel de configuração.
6. Preencha os campos de acordo com o formato escolhido e clique em Aplicar.
7. Salve a versão do fluxo e publique ou ative a versão conforme o processo da organização.

Como a caixa funciona

O fluxo básico é:

Etapa que gera ou recebe um JSON
              │
              ▼
       Extrair variável
              │
              ▼
Usar o valor em uma mensagem, decisão ou integração

No formato JSON, a caixa tenta interpretar a variável de origem como JSON, percorre o caminho informado e copia o valor encontrado. Se o JSON não puder ser lido ou o caminho não existir, o destino recebe null; a caixa não possui uma saída de erro separada. O fluxo pode continuar para a etapa seguinte, e uma Decisão posterior pode verificar se o valor foi encontrado.

No formato Template WhatsApp, a caixa localiza os parâmetros numerados do template e grava cada parâmetro na variável indicada na tabela. Se um parâmetro não estiver disponível, a variável correspondente fica vazia.

A variável de origem não é alterada. O resultado é salvo nas variáveis de destino informadas no painel.

Campos comuns

Nome do elemento

Identifica a caixa no diagrama. Use um nome que explique o que está sendo extraído, por exemplo:

• Extrair token da resposta;
• Ler dados do cliente;
• Separar parâmetros do template.

Esse nome facilita a leitura do fluxo e a seleção da caixa como destino em outras configurações. Ele não é o nome da variável que receberá o resultado.

Nome da variável de origem

Informe o nome da variável da sessão que contém o conteúdo a ser lido.

A etapa que preenche essa variável precisa ser executada antes da caixa Extrair variável. Exemplos de nomes:

• respostaApi;
• dadosCliente;
• mensagemTemplate.

Confira a grafia e o uso de maiúsculas e minúsculas. O nome deve ser exatamente igual ao usado pela etapa anterior.

Formatação da variável de origem

Escolha uma das opções:

• JSON — para buscar um campo dentro de um objeto JSON;
• Template WhatsApp — para separar parâmetros numerados de um template WhatsApp.

Os campos exibidos abaixo dessa opção mudam conforme a escolha. Não misture a configuração de um formato com o outro.

Após realizar a extração, vai para:

Selecione a caixa que deverá ser executada depois da extração. Exemplos:

• uma Mensagem simples que apresenta o resultado;
• uma Decisão que verifica o valor;
• outra integração que usa a variável extraída;
• uma etapa de encerramento.

A opção Nenhum deixa esse destino sem uma seleção explícita no painel. Quando a continuidade for importante, configure uma próxima caixa ou uma conexão clara no diagrama e teste o caminho completo.

Formato JSON

Selecione JSON quando a variável de origem contiver um conteúdo JSON (normalmente armazenado como texto), produzido por uma integração, um comando externo ou um formulário.

Caminho da variável de origem

Informe o caminho do campo que deve ser retirado. Use a notação por pontos, sem colocar um ponto no início.

O caminho diferencia letras maiúsculas e minúsculas. Digite somente o caminho, por exemplo body.token, e não $.body.token nem .body.token.

O tipo do valor é preservado quando possível. Um número continua sendo número, um booleano continua sendo booleano e um objeto ou lista pode ser gravado como o resultado correspondente.

Nova variável que recebe o valor de origem

Informe o nome da variável da sessão que receberá o resultado extraído. Use um nome simples e descritivo, por exemplo:

• token;
• nomeCliente;
• numeroPedido.

Essa variável poderá ser usada pelas caixas seguintes. Se outra etapa gravar novamente o mesmo nome, o valor anterior será substituído.

Exemplo — extrair um token

Suponha que uma etapa anterior tenha preenchido respostaApi com este conteúdo:

{
  "status": 200,
  "body": {
    "token": "abc123",
    "expiresIn": 3600
  }
}

Configure a caixa assim:

Depois da execução, a variável token conterá abc123. A variável respostaApi continuará disponível com o conteúdo original.

Exemplo — preparar uma decisão

Para direcionar o atendimento conforme o status retornado por uma integração:

Requisição REST
      │  guarda o JSON em respostaApi
      ▼
Extrair variável
      │  caminho: status → variável: statusPedido
      ▼
Decisão
      ├── statusPedido = aprovado → Confirmar pedido
      └── outro valor            → Tratar pendência

A decisão deve usar o mesmo nome informado em Nova variável que recebe o valor de origem.

Quando o formato JSON não encontra o valor

A caixa grava null no destino quando:

• a variável de origem não está preenchida;
• o conteúdo não é um JSON válido;
• o caminho foi digitado incorretamente;
• alguma parte do caminho não existe no conteúdo recebido.

Não há um caminho de erro específico nessa caixa. Se o valor for obrigatório, coloque uma Decisão depois da extração para tratar o caso de null antes de seguir para a etapa que depende do dado.

Formato Template WhatsApp

Selecione Template WhatsApp quando a variável de origem contém os parâmetros de uma mensagem de template WhatsApp. Nesse modo, a caixa não usa um caminho com pontos. Em vez disso, ela apresenta a tabela Parâmetros do template que viram variáveis do fluxo.

Cada linha da tabela relaciona:

• Número — número do parâmetro no template;
• Variável — nome da variável da sessão que receberá o valor desse parâmetro.

Use o botão + para adicionar uma linha. Para remover uma linha, use o ícone de exclusão da própria linha.

Exemplo — separar parâmetros do template

Considere uma mensagem de template com estes parâmetros:

Parâmetro 1: Ana
Parâmetro 2: Pedido 15482

Configure a caixa assim:

Resultado:

• nomeCliente recebe Ana;
• resumoPedido recebe Pedido 15482.

Se o valor de um parâmetro contiver uma referência no formato {{nomeDaVariavel}}, essa referência pode ser resolvida usando o valor existente na sessão. Garanta que a variável referenciada esteja preenchida antes da extração.

Cuidados com os números dos parâmetros

• Use o número que corresponde à posição do parâmetro no template.
• Não troque a ordem por causa do nome da variável de destino.
• Use uma variável de destino diferente quando precisar manter mais de um parâmetro.
• Se um número não existir no template, a variável correspondente ficará vazia.
• Não use o formato Template WhatsApp para extrair campos de um JSON comum; nesse caso, selecione JSON.

Como configurar passo a passo

1. Prepare a etapa de origem

Antes de usar Extrair variável, configure a etapa que preencherá a variável de origem. Por exemplo:

• uma Requisição REST que recebe uma resposta;
• um comando externo que devolve um JSON;
• um formulário que guarda dados estruturados;
• uma etapa que recebe os dados de um template WhatsApp.

Confirme qual variável essa etapa grava e qual é o formato do conteúdo.

2. Adicione e configure a caixa

1. Abra o grupo Variáveis e adicione Extrair variável.
2. Preencha o Nome do elemento.
3. Informe o Nome da variável de origem.
4. Escolha JSON ou Template WhatsApp.
5. Preencha os campos específicos do formato escolhido.
6. Selecione o destino em Após realizar a extração, vai para:.
7. Clique em Aplicar.
8. Salve a versão do fluxo.

3. Teste o caminho completo

1. Inicie uma nova sessão de teste.
2. Faça a etapa anterior preencher a variável de origem.
3. Confirme se o fluxo chega à caixa Extrair variável.
4. Verifique o valor produzido na etapa seguinte.
5. Teste também um conteúdo sem o campo esperado para confirmar o tratamento de null ou vazio.
6. Publique a versão correta depois de concluir a validação.

Boas práticas

• Use nomes de variáveis claros e consistentes, sem espaços ou caracteres especiais.
• Coloque a caixa imediatamente depois da etapa que produz o JSON ou os parâmetros do template.
• Mantenha o caminho JSON curto, preciso e igual à estrutura real recebida.
• Não reutilize uma variável de destino quando precisar preservar resultados diferentes.
• Trate null e valores vazios antes de usar o resultado em uma chamada externa ou em uma mensagem.
• No formato Template WhatsApp, documente no próprio fluxo o significado de cada número de parâmetro.
• Teste o caminho normal e pelo menos um caso em que o campo não exista.
• Salve e publique a versão correta antes de validar o comportamento no canal de atendimento.

Diferença entre recursos relacionados