> ## 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.

# Variables

> Store and reference data throughout your conversation flows.

## Overview

Variables let you capture, store, and reuse data during a conversation. Use them to personalize messages, make decisions based on user input, and pass data between nodes.

## Types of Variables

### System Variables

Pre-loaded automatically in every session. You don't need to declare them.

| Variable                      | Description                                        |
| ----------------------------- | -------------------------------------------------- |
| `system.last_message.text`    | Text content of the user's last message.           |
| `system.last_message.caption` | Caption of a media message from the user.          |
| `system.last_message.url`     | Media URL from the user's message.                 |
| `system.request.status`       | HTTP status code from the last API Request node.   |
| `system.request.body`         | Full response body from the last API Request node. |
| `system.numberOfAttempts`     | Number of retries on the current wait node.        |
| `system.dateHour`             | Current system date/time.                          |

### User Variables

Variables you create in the flow editor to store custom data. Each variable has a **name** (used in templates) and a **unique ID** (used internally).

## Template Syntax `{{variableName}}`

Use double curly braces to reference variables in text fields — message bodies, API URLs, headers, conditions, etc.

### Primitive Values

Variables that hold strings, numbers, or booleans are replaced directly:

| Template               | Variable Value     | Result          |
| ---------------------- | ------------------ | --------------- |
| `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`    |

### Object Values

When a variable holds an object, the result is its JSON representation:

| Template         | Variable Value                    | Result                          |
| ---------------- | --------------------------------- | ------------------------------- |
| `Info: {{data}}` | `data = { name: "Ana", age: 30 }` | `Info: {"name":"Ana","age":30}` |

### Accessing Object Properties

Use dot notation to access nested properties:

| Template                      | Variable Value                       | Result          |
| ----------------------------- | ------------------------------------ | --------------- |
| `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`      |

Deep nesting works at any level:

| Template               | Variable Value                         | Result         |
| ---------------------- | -------------------------------------- | -------------- |
| `Name: {{a.b.c.name}}` | `a = { b: { c: { name: "Carlos" } } }` | `Name: Carlos` |

### Array Access

When a variable is an array, it returns the JSON array:

| Template          | Variable Value                  | Result                       |
| ----------------- | ------------------------------- | ---------------------------- |
| `Items: {{list}}` | `list = [1, 2, 3]`              | `Items: [1,2,3]`             |
| `Tags: {{tags}}`  | `tags = ["node", "nest", "ts"]` | `Tags: ["node","nest","ts"]` |

When accessing a property on an array, it maps and extracts that property from each item:

| Template                   | Variable Value                                                             | Result                         |
| -------------------------- | -------------------------------------------------------------------------- | ------------------------------ |
| `{{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"]`                |

### System Variables in Templates

System variables use the `system.` prefix:

| Template                                     | Result                      |
| -------------------------------------------- | --------------------------- |
| `Last message: {{system.last_message.text}}` | `Last message: Hello world` |
| `Status: {{system.request.status}}`          | `Status: 200`               |
| `Body: {{system.request.body}}`              | `Body: {"ok":true}`         |
| `Body ok: {{system.request.body.ok}}`        | `Body ok: true`             |
| `Date: {{system.dateHour}}`                  | `Date: 2025-01-15T10:30:00` |

### Multiple Variables

You can use multiple variables in the same string:

| Template                                 | Variables                                      | Result                            |
| ---------------------------------------- | ---------------------------------------------- | --------------------------------- |
| `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`             |

### Variable Not Found

When a variable doesn't exist, is `null`, or is `undefined`, the original template is kept:

| Template               | Variable Value   | Result                 |
| ---------------------- | ---------------- | ---------------------- |
| `Hello {{name}}`       | *(not defined)*  | `Hello {{name}}`       |
| `Val: {{obj.missing}}` | `obj = { a: 1 }` | `Val: {{obj.missing}}` |
| `Hello {{name}}`       | `name = null`    | `Hello {{name}}`       |

### Chained Variables

If a variable's value contains another variable reference, it is resolved recursively:

| Template | Variables                                  | Result  |
| -------- | ------------------------------------------ | ------- |
| `{{a}}`  | `a = "{{b}}"`, `b = "final"`               | `final` |
| `{{a}}`  | `a = "{{b}}"`, `b = "{{c}}"`, `c = "deep"` | `deep`  |
| `{{a}}`  | `a = "{{b}}"`, *(b not defined)*           | `{{b}}` |

## Common Patterns

### Capture User Input

After a wait node (Button, List, Message Menu), the user's response is in `system.last_message.text`. Use a **Set Variable** node to persist it:

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

### Parse API Responses

After an **API Request** node, use an **Object Parser** node to extract fields from `system.request.body`:

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

### Interpolate in Messages

Reference any variable in a **Message** node:

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

## Naming Rules

* Use **camelCase**: `userName`, `orderTotal`, `cpfNumber`
* No spaces or special characters — only letters, numbers, and underscores
* Names are **case-sensitive**: `userName` ≠ `username`
* Never use the `system.` prefix for user variables

## Comparison Operators

When using variables in **Condition** nodes:

| Operator         | Description           | Value required? |
| ---------------- | --------------------- | --------------- |
| `equals`         | Exact match           | Yes             |
| `notEquals`      | Does not match        | Yes             |
| `contains`       | Includes substring    | Yes             |
| `notContains`    | Does not include      | Yes             |
| `greaterThan`    | Numerically greater   | Yes             |
| `lessThan`       | Numerically less      | Yes             |
| `greaterOrEqual` | Greater or equal      | Yes             |
| `lessOrEqual`    | Less or equal         | Yes             |
| `isSet`          | Has a non-empty value | No              |
| `isEmpty`        | Empty or undefined    | No              |
| `startsWith`     | Begins with string    | Yes             |
| `endsWith`       | Ends with string      | Yes             |
| `matchesRegex`   | Matches regex pattern | Yes             |

## Transform Functions

Optional transformations applied to variables before comparing in conditions:

| Function       | Effect                                          |
| -------------- | ----------------------------------------------- |
| `length`       | Uses string length instead of the string itself |
| `trim`         | Removes leading/trailing whitespace             |
| `lowercase`    | Converts to lowercase                           |
| `uppercase`    | Converts to uppercase                           |
| `toNumber`     | Converts to number                              |
| `normalize`    | Removes accents and diacritics                  |
| `removeSpaces` | Removes all spaces                              |