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

# Key Concepts

> Understand the core building nodes of whatabot: flows, nodes, edges, variables, and sessions.

## Flows

A **flow** is a conversational blueprint. It defines the entire conversation path a user can take, from the first greeting to the final action. Flows are built visually in the editor using nodes connected by edges.

Each flow belongs to a **workspace** and is stored as a JSON structure containing:

* **Nodes** (nodes) — the individual steps
* **Edges** — the connections between nodes
* **Variables** — data containers used throughout the flow

## Nodes

Nodes are the building units of a flow. Each node has a specific type and behavior. whatabot provides 18+ node types organized into categories:

| Category         | Nodes                                        | Behavior                                                      |
| ---------------- | -------------------------------------------- | ------------------------------------------------------------- |
| **Messages**     | Message, Media, PIX                          | Send content to the user, then continue                       |
| **User Input**   | Button, List, Message Menu                   | Send interactive content and **wait** for the user to respond |
| **Logic**        | Condition, Jump To, Set Variable, Format     | Evaluate conditions, set values, route the flow               |
| **Integrations** | API Request, OpenAI Agent                    | Call external services                                        |
| **Data**         | Object Parser, Filter Parser, JS Code Runner | Transform and extract data                                    |
| **Actions**      | Transfer, Finish                             | End the flow or hand off to a human                           |

### Execution types

Nodes behave in one of these ways:

* **Continue** — Executes and immediately moves to the next node (e.g., Message, Media)
* **Wait** — Sends content and pauses until the user replies (e.g., Button, List, Message Menu)
* **Transfer** — Hands the conversation to a human agent and keeps the session alive
* **Finish** — Ends the session

## Edges

Edges are the connections between nodes. They define the flow of the conversation. There are two types:

* **Simple edges** — Connect one node to the next (used by Message, Media, etc.)
* **Option edges** — Connect a specific output handle to another node (used by Button, List, Condition, API Request)

<Callout type="info">
  Nodes like Button, List, and Condition have **multiple output handles** — one
  per option/branch plus a fallback handle for invalid selections.
</Callout>

## Variables

Variables store data during a conversation session. There are two types:

* **System variables** — available automatically in every flow (e.g., `system.last_message.text`, `system.request.response`, `system.dateHour`)
* **User variables** — created by you in the editor to store collected data (names, emails, IDs, etc.)

Reference variables in text fields using the `{{variableName}}` syntax.

<Callout type="tip">
  See the [Variables guide](/en/editor/variables) for the full list of system
  variables, template syntax, operators, and transformation functions.
</Callout>

## Sessions

A **session** represents an active conversation between a contact and a flow. Sessions are:

* Created via the API when a user starts a conversation
* Stored in **Redis** with a 24-hour TTL (refreshed on each interaction)
* Identified by a unique `sessionId`
* Linked to a specific flow and contact

The session tracks the current position in the flow and all variable values.

## Workspaces

Workspaces are organizational containers. Each workspace has its own:

* Flows
* API keys
* OAuth clients
* AI agents
* Sectors

A single **account** can have multiple workspaces, and users can access workspaces based on their **role**.