--- title: "Extrair variavel" slug: "extrair-variavel" updated: 2026-10-23T17:17:32Z published: 2026-10-23T17:17:32Z canonical: "docs.omnisiga.ai/extrair-variavel" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.omnisiga.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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: | Formato | Use quando | Resultado | | --- | --- | --- | | **JSON** | A variável contém um conteúdo JSON e você precisa de um campo interno. | Um caminho do JSON é gravado em uma variável de destino. | | **Template WhatsApp** | A variável contém os parâmetros de um template WhatsApp. | Cada parâmetro numerado pode ser gravado em uma variável diferente. | 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. | Conteúdo da variável de origem | Caminho | Valor extraído | | --- | --- | --- | | `{"token":"abc123"}` | `token` | `abc123` | | `{"body":{"token":"abc123"}}` | `body.token` | `abc123` | | `{"cliente":{"nome":"Ana"}}` | `cliente.nome` | `Ana` | | `{"pedido":{"numero":15482}}` | `pedido.numero` | `15482` | 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: | Campo | Valor | | --- | --- | | **Nome do elemento** | `Extrair token da resposta` | | **Nome da variável de origem** | `respostaApi` | | **Formatação da variável de origem** | `JSON` | | **Caminho da variável de origem** | `body.token` | | **Nova variável que recebe o valor de origem** | `token` | | **Após realizar a extração, vai para:** | `Continuar atendimento` | 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: | Campo | Valor | | --- | --- | | **Nome do elemento** | `Separar parâmetros do template` | | **Nome da variável de origem** | `mensagemTemplate` | | **Formatação da variável de origem** | `Template WhatsApp` | | **Parâmetro 1 — Variável** | `nomeCliente` | | **Parâmetro 2 — Variável** | `resumoPedido` | | **Após realizar a extração, vai para:** | `Confirmar dados` | 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 | Recurso | Função | | --- | --- | | **Extrair variável** | Lê um JSON ou parâmetros de template já armazenados e grava o resultado em variáveis da sessão. | | **Definir variáveis** | Cria ou atualiza valores de sessão definidos diretamente na configuração da caixa. | | **Requisição REST** | Consulta um serviço externo e pode produzir a resposta que será tratada pela extração. | | **Análise de imagem** | Analisa uma imagem e grava respostas extraídas; não é substituída por um caminho JSON. | | **Caixa de código** | Permite tratar estruturas ou regras que não são atendidas pelos formatos visuais da caixa. |