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

# Conceitos Principais

> Entenda os blocos fundamentais do whatabot: fluxos, nós, arestas, variáveis e sessões.

## Fluxos

Um **fluxo** é um modelo conversacional. Ele define todo o caminho de conversa que um usuário pode seguir, desde a primeira saudação até a ação final. Fluxos são construídos visualmente no editor usando nós conectados por arestas.

Cada fluxo pertence a um **espaço de trabalho** e é armazenado como uma estrutura JSON contendo:

* **Nós** (nodes) — as etapas individuais
* **Arestas** (edges) — as conexões entre nós
* **Variáveis** — containers de dados usados ao longo do fluxo

## Nós

Nós são as unidades de construção de um fluxo. Cada nó tem um tipo e comportamento específico. O whatabot oferece 18+ tipos de nós organizados em categorias:

| Categoria              | Nós                                                | Comportamento                                                   |
| ---------------------- | -------------------------------------------------- | --------------------------------------------------------------- |
| **Mensagens**          | Mensagem, Mídia, PIX                               | Enviam conteúdo ao usuário e continuam                          |
| **Entrada do Usuário** | Botão, Lista, Menu de Mensagem                     | Enviam conteúdo interativo e **aguardam** a resposta do usuário |
| **Lógica**             | Condição, Ir Para, Definir Variável, Formatar      | Avaliam condições, definem valores, direcionam o fluxo          |
| **Integrações**        | Requisição API, Agente OpenAI                      | Chamam serviços externos                                        |
| **Dados**              | Parser de Objeto, Parser de Filtro, Executor de JS | Transformam e extraem dados                                     |
| **Ações**              | Transferir, Finalizar                              | Encerram o fluxo ou transferem para um humano                   |

### Tipos de execução

Os nós se comportam de uma destas formas:

* **Continuar** — Executa e imediatamente avança para o próximo nó (ex: Mensagem, Mídia)
* **Aguardar** — Envia conteúdo e pausa até o usuário responder (ex: Botão, Lista, Menu de Mensagem)
* **Transferir** — Encaminha a conversa para um agente humano e mantém a sessão ativa
* **Finalizar** — Encerra a sessão

## Arestas

Arestas são as conexões entre nós. Elas definem o fluxo da conversa. Existem dois tipos:

* **Arestas simples** — Conectam um nó ao próximo (usadas por Message, Media, etc.)
* **Arestas de opção** — Conectam um ponto de saída específico a outro nó (usadas por Button, List, Condition, API Request)

<Callout type="info">
  Nós como Button, List e Condition possuem **múltiplos pontos de saída** — um
  por opção/ramificação mais um ponto de fallback para seleções inválidas.
</Callout>

## Variáveis

Variáveis armazenam dados durante uma sessão de conversa. Existem dois tipos:

* **Variáveis de sistema** — disponíveis automaticamente em todo fluxo (ex: `system.last_message.text`, `system.request.response`, `system.dateHour`)
* **Variáveis do usuário** — criadas por você no editor para armazenar dados coletados (nomes, emails, IDs, etc.)

Referencie variáveis em campos de texto usando a sintaxe `{{variableName}}`.

<Callout type="tip">
  Consulte o [Guia de Variáveis](/editor/variables) para a lista completa de
  variáveis de sistema, sintaxe de template, operadores e funções de
  transformação.
</Callout>

## Sessões

Uma **sessão** representa uma conversa ativa entre um contato e um fluxo. Sessões são:

* Criadas via API quando um usuário inicia uma conversa
* Armazenadas no **Redis** com um TTL de 24 horas (renovado a cada interação)
* Identificadas por um `sessionId` único
* Vinculadas a um fluxo e contato específicos

A sessão rastreia a posição atual no fluxo e todos os valores das variáveis.

## Espaços de Trabalho

Espaços de trabalho são containers organizacionais. Cada espaço de trabalho tem seus próprios:

* Fluxos
* Chaves de API
* Clientes OAuth
* Agentes de IA
* Setores

Uma única **conta** pode ter múltiplos espaços de trabalho, e usuários podem acessar espaços de trabalho com base em seu **papel**.