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

# Flows

> Design conversational trees with boxes and connections. Create visual interaction flows to guide your AI agent's conversations.

The **Flows** module lets you build **conversational flows** visually — think of it as a canvas where you design the exact path your AI agent should follow during a conversation. Instead of relying solely on the AI's free-form responses, Flows give you granular control over how interactions unfold step by step.

Use Flows when you need:

* **Structured conversations:** Guide the user through a specific sequence (e.g. onboarding, troubleshooting, data collection).
* **Human escalation paths:** Define clear rules for when and how a conversation should be transferred to a human agent.
* **API integrations:** Call external services at specific points in the conversation to fetch or send data.
* **Lovi Tools:** Leverage built-in Lovi capabilities within the flow for advanced actions.

***

## Getting Started

When you open the Flows section for the first time, you'll see an empty state inviting you to create your first flow.

Click the **+ New flow** button in the top-right corner (or the **+ Create my first flow** button in the centre) to get started.

***

## Creating a New Flow

A dialog will appear asking you to configure the basics of your flow:

| Field                        | Description                                                                        |
| :--------------------------- | :--------------------------------------------------------------------------------- |
| **Flow name** *(required)*   | A descriptive name for your flow (e.g. `Greeting and policies`, `Order tracking`). |
| **Description** *(optional)* | A brief explanation of what this flow does. Useful for keeping your team aligned.  |
| **AI agent** *(required)*    | The AI agent this flow will be linked to. Select one from the dropdown.            |
| **Flow type**                | Choose how you want to start building.                                             |

### Flow Types

| Type                 | Description                                                                                                                       |
| :------------------- | :-------------------------------------------------------------------------------------------------------------------------------- |
| **Custom (empty)**   | Start from scratch with just a trigger node. Full creative freedom to build your own flow.                                        |
| **Human escalation** | A pre-configured template designed for handing off conversations from the AI agent to a human agent. Ideal for support workflows. |

Once you've filled in the details, click **Create flow** to enter the flow editor.

***

## The Flow Editor (Canvas)

After creating a flow, you'll be taken to the **flow editor** — an interactive canvas where you design your conversational tree using drag-and-drop nodes and connections.

At the top of the editor you'll see:

* The **flow name** and the **linked AI agent**.
* A toolbar with the available node types.
* A **Save** button to persist your changes.

At the bottom-left, you'll find canvas controls: **zoom in**, **zoom out**, **fit to screen**, and **lock/unlock** the canvas.

***

## Node Types

Nodes are the building blocks of your flow. Each node represents a step in the conversation. You add them from the toolbar at the top of the editor and connect them to define the conversation path.

### 1. Agent Node

The **Agent node** represents a point where the AI agent speaks or performs an action. Use it to:

* Send a message to the user.
* Process information using the AI engine.
* Make decisions based on the conversation context.

This is the most common node — it's the AI doing its job within the flow.

### 2. User Node

The **User node** represents a point where the system waits for user input. Use it to:

* Capture a specific response from the user.
* Branch the flow based on what the user says or selects.
* Collect data (names, emails, preferences, etc.).

Think of it as a "pause and listen" step in the conversation.

### 3. API Node

The **API node** lets you integrate external services directly into the flow. Use it to:

* Fetch data from a third-party system (e.g. order status, account info).
* Send data to an external service (e.g. create a ticket, update a CRM).
* Trigger webhooks at specific conversation points.

This is how your flow connects to the outside world.

### 4. Lovi Tools Node

The **Lovi Tools node** gives you access to Lovi's built-in capabilities within the flow. Use it to:

* Perform platform-specific actions (e.g. tag a conversation, assign to a department).
* Use advanced Lovi features that go beyond simple text responses.
* Automate internal operations as part of the conversational flow.

***

## Building a Flow

Here's the general workflow for building a conversational flow:

1. **Start with the trigger:** Every flow begins with a trigger node that defines when the flow starts.
2. **Add nodes:** Drag nodes from the toolbar onto the canvas.
3. **Connect nodes:** Draw connections between nodes to define the conversation path. Simply click on a node's output port and drag to another node's input port.
4. **Configure each node:** Click on a node to open its settings panel and define what it does (messages, conditions, API calls, etc.).
5. **Save:** Click the **Save** button to persist your flow.

### Tips for Effective Flows

* **Keep it simple:** Start with a minimal flow and expand as needed. Overly complex trees are hard to maintain.
* **Test frequently:** After saving, test the flow through your linked AI agent to make sure the conversation feels natural.
* **Use branching wisely:** User nodes can branch into multiple paths — use this to handle different user intents without making the flow too deep.
* **Combine with AI:** Flows don't replace the AI — they guide it. The AI agent still handles the nuance; the flow provides the structure.

***

## Best Practices

* **Name your flows clearly:** Use descriptive names so your team knows what each flow handles at a glance.
* **One flow per objective:** Instead of building one massive flow, create separate flows for distinct goals (e.g. one for onboarding, another for support escalation).
* **Document with descriptions:** Use the description field when creating a flow — your future self (and your colleagues) will thank you.
* **Review and iterate:** Flows are living documents. Check your analytics to see where users drop off and refine the paths accordingly.

***

## Quick Reference

| Action            | How                                               |
| :---------------- | :------------------------------------------------ |
| Create a new flow | Click **+ New flow** in the top-right corner      |
| Add a node        | Click the node type button in the toolbar         |
| Connect nodes     | Drag from one node's output to another's input    |
| Configure a node  | Click on the node in the canvas                   |
| Save changes      | Click the **Save** button                         |
| Zoom in/out       | Use the controls at the bottom-left of the canvas |
| Fit to screen     | Click the fit-to-screen icon at the bottom-left   |