> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whatabot.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Variáveis

> Armazene e referencie dados ao longo dos seus fluxos de conversa.

## Visão geral

Variáveis permitem capturar, armazenar e reutilizar dados durante uma conversa. Use-as para personalizar mensagens, tomar decisões com base na entrada do usuário e passar dados entre nós.

## Tipos de Variáveis

### Variáveis de Sistema

Carregadas automaticamente em toda sessão. Você não precisa declará-las.

| Variável                      | Descrição                                                           |
| ----------------------------- | ------------------------------------------------------------------- |
| `system.last_message.text`    | Conteúdo de texto da última mensagem do usuário.                    |
| `system.last_message.caption` | Legenda de uma mensagem de mídia do usuário.                        |
| `system.last_message.url`     | URL de mídia da mensagem do usuário.                                |
| `system.last_message.type`    | Tipo da última mensagem (text, image, video, audio, document, etc). |
| `system.request.statusCode`   | Código de status HTTP do último nó API Request.                     |
| `system.request.response`     | Corpo completo da resposta do último nó API Request.                |
| `system.numberOfAttempts`     | Número de tentativas no nó de espera atual.                         |
| `system.dateHour`             | Data/hora atual do sistema.                                         |

### Variáveis do Usuário

Variáveis que você cria no editor de fluxos para armazenar dados personalizados. Cada variável tem um **nome** (usado em templates) e um **ID único** (usado internamente).

## Sintaxe de Template `{{variableName}}`

Use chaves duplas para referenciar variáveis em campos de texto — corpos de mensagem, URLs de API, cabeçalhos, condições, etc.

### Valores Primitivos

Variáveis que armazenam strings, números ou booleanos são substituídas diretamente:

| Template               | Valor da Variável  | Resultado       |
| ---------------------- | ------------------ | --------------- |
| `Hello {{name}}`       | `name = "Claudio"` | `Hello Claudio` |
| `Total: {{amount}}`    | `amount = 42.5`    | `Total: 42.5`   |
| `Active: {{active}}`   | `active = true`    | `Active: true`  |
| `Balance: {{balance}}` | `balance = 0`      | `Balance: 0`    |

### Valores de Objeto

Quando uma variável contém um objeto, o resultado é sua representação JSON:

| Template         | Valor da Variável                 | Resultado                       |
| ---------------- | --------------------------------- | ------------------------------- |
| `Info: {{data}}` | `data = { name: "Ana", age: 30 }` | `Info: {"name":"Ana","age":30}` |

### Acessando Propriedades de Objetos

Use notação de ponto para acessar propriedades aninhadas:

| Template                      | Valor da Variável                    | Resultado       |
| ----------------------------- | ------------------------------------ | --------------- |
| `Hello {{user.name}}`         | `user = { name: "Claudio" }`         | `Hello Claudio` |
| `Total: {{order.total}}`      | `order = { total: 150.99 }`          | `Total: 150.99` |
| `City: {{data.address.city}}` | `data = { address: { city: "SP" } }` | `City: SP`      |

Aninhamento profundo funciona em qualquer nível:

| Template               | Valor da Variável                      | Resultado      |
| ---------------------- | -------------------------------------- | -------------- |
| `Name: {{a.b.c.name}}` | `a = { b: { c: { name: "Carlos" } } }` | `Name: Carlos` |

### Acesso a Arrays

Quando uma variável é um array, retorna o JSON do array:

| Template          | Valor da Variável               | Resultado                    |
| ----------------- | ------------------------------- | ---------------------------- |
| `Items: {{list}}` | `list = [1, 2, 3]`              | `Items: [1,2,3]`             |
| `Tags: {{tags}}`  | `tags = ["node", "nest", "ts"]` | `Tags: ["node","nest","ts"]` |

Ao acessar uma propriedade em um array, ele mapeia e extrai essa propriedade de cada item:

| Template                   | Valor da Variável                                                          | Resultado                      |
| -------------------------- | -------------------------------------------------------------------------- | ------------------------------ |
| `{{products.price}}`       | `products = [{ name: "Shirt", price: 50 }, { name: "Pants", price: 120 }]` | `[{"price":50},{"price":120}]` |
| `{{orders.customer.name}}` | `orders = [{ customer: { name: "Ana" } }, { customer: { name: "Bob" } }]`  | `["Ana","Bob"]`                |

### Variáveis de Sistema em Templates

Variáveis de sistema usam o prefixo `system.`:

| Template                                      | Resultado                   |
| --------------------------------------------- | --------------------------- |
| `Last message: {{system.last_message.text}}`  | `Last message: Hello world` |
| `Status: {{system.request.statusCode}}`       | `Status: 200`               |
| `Response: {{system.request.response}}`       | `Response: {"ok":true}`     |
| `Response ok: {{system.request.response.ok}}` | `Response ok: true`         |
| `Date: {{system.dateHour}}`                   | `Date: 2025-01-15T10:30:00` |

### Múltiplas Variáveis

Você pode usar múltiplas variáveis na mesma string:

| Template                                 | Variáveis                                      | Resultado                         |
| ---------------------------------------- | ---------------------------------------------- | --------------------------------- |
| `Due date {{dueDate}} amount {{amount}}` | `dueDate = "03/15"`, `amount = "R$ 150,00"`    | `Due date 03/15 amount R$ 150,00` |
| `{{name}} bought {{qty}}x {{product}}`   | `name = "Ana"`, `qty = 3`, `product = "Shirt"` | `Ana bought 3x Shirt`             |

### Variável Não Encontrada

Quando uma variável não existe, é `null` ou `undefined`, o template original é mantido:

| Template               | Valor da Variável | Resultado              |
| ---------------------- | ----------------- | ---------------------- |
| `Hello {{name}}`       | *(não definida)*  | `Hello {{name}}`       |
| `Val: {{obj.missing}}` | `obj = { a: 1 }`  | `Val: {{obj.missing}}` |
| `Hello {{name}}`       | `name = null`     | `Hello {{name}}`       |

### Variáveis Encadeadas

Se o valor de uma variável contém outra referência de variável, ela é resolvida recursivamente:

| Template | Variáveis                                  | Resultado |
| -------- | ------------------------------------------ | --------- |
| `{{a}}`  | `a = "{{b}}"`, `b = "final"`               | `final`   |
| `{{a}}`  | `a = "{{b}}"`, `b = "{{c}}"`, `c = "deep"` | `deep`    |
| `{{a}}`  | `a = "{{b}}"`, *(b não definida)*          | `{{b}}`   |

## Padrões Comuns

### Capturar Entrada do Usuário

Após um nó de espera (Botão, Lista, Menu de Mensagem), a resposta do usuário está em `system.last_message.text`. Use um nó **Definir Variável** para persisti-la:

```
{{system.last_message.text}} → userName
```

### Analisar Respostas de API

Após um nó **Requisição API**, use um nó **Parser de Objeto** para extrair campos de `system.request.response`:

```
data.order.id     → orderId
data.order.status → orderStatus
data.customer.name → customerName
```

### Interpolar em Mensagens

Referencie qualquer variável em um nó **Mensagem**:

```
Hello, {{userName}}! Your order #{{orderId}} is {{orderStatus}}.
```

## Regras de Nomenclatura

* Use **camelCase**: `userName`, `orderTotal`, `cpfNumber`
* Sem espaços ou caracteres especiais — apenas letras, números e underscores
* Nomes são **case-sensitive**: `userName` ≠ `username`
* Nunca use o prefixo `system.` para variáveis do usuário

## Operadores de Comparação

Ao usar variáveis em nós **Condição**:

| Operador         | Descrição                   | Valor obrigatório? |
| ---------------- | --------------------------- | ------------------ |
| `equals`         | Correspondência exata       | Sim                |
| `notEquals`      | Não corresponde             | Sim                |
| `contains`       | Contém substring            | Sim                |
| `notContains`    | Não contém                  | Sim                |
| `greaterThan`    | Numericamente maior         | Sim                |
| `lessThan`       | Numericamente menor         | Sim                |
| `greaterOrEqual` | Maior ou igual              | Sim                |
| `lessOrEqual`    | Menor ou igual              | Sim                |
| `isSet`          | Possui valor não vazio      | Não                |
| `isEmpty`        | Vazio ou indefinido         | Não                |
| `startsWith`     | Começa com a string         | Sim                |
| `endsWith`       | Termina com a string        | Sim                |
| `matchesRegex`   | Corresponde ao padrão regex | Sim                |

## Funções de Transformação

Transformações opcionais aplicadas a variáveis antes de comparar em condições:

| Função         | Efeito                                             |
| -------------- | -------------------------------------------------- |
| `length`       | Usa o comprimento da string em vez da string em si |
| `trim`         | Remove espaços em branco no início e fim           |
| `lowercase`    | Converte para minúsculas                           |
| `uppercase`    | Converte para maiúsculas                           |
| `toNumber`     | Converte para número                               |
| `normalize`    | Remove acentos e diacríticos                       |
| `removeSpaces` | Remove todos os espaços                            |