> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verbex.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Conversation Flow Builder User Guide
> Learn how to design a phone conversation visually with the Verbex Conversation Flow Builder — adding nodes, connecting them, configuring each step, and testing the flow before going live.
**What you'll learn**
* What the Conversation Flow Builder is and how to open it
* What each part of the builder interface does
* What every node type is for and how to configure it
* How to fix common errors and test your flow safely
## Introduction
The Verbex Conversation Flow Builder is a visual tool that helps you design how an AI voice agent will handle phone conversations. You build the call flow by adding blocks, connecting them with arrows, and configuring what the agent should say or do at each step.
A flow works like a conversation map. It shows where the call starts, what the agent says, what information the agent collects, which path the call should follow, when the call should transfer to a human, and when the call should end.
## Opening the Flow Builder
To open the Conversation Flow Builder:
Sign in to your Verbex account.
The list of your agents will appear.
The Flow Builder canvas appears for that agent. The agent name is visible at the top-left of the builder screen.
## Main Interface Overview
The Flow Builder screen is divided into five main areas: the **Left Sidebar**, **Add Nodes Panel**, **Canvas Area**, **Right Configuration Panel**, and **Top Toolbar**. Each area is used for a different part of building, configuring, saving, and testing the conversation flow.
### Left Sidebar
The dark sidebar on the far left is the main navigation area of the Verbex Customer Console. From this sidebar you can move between different sections of the platform, such as Dashboard, Agents, Knowledge Bases, Phone Numbers, Call Logs, Batch Call, Workspaces, Minute Allocation, and Settings.
### Canvas Area
The large white dotted area in the middle is called the canvas. This is where the conversation flow is built visually. On the canvas you can place nodes, connect nodes with arrows, move nodes around, zoom in and out, arrange the flow structure, and view the full conversation path.
### Canvas Controls
At the bottom-left of the canvas there are zoom and view controls. These help you navigate the flow when the canvas becomes large:
* **Zoom in** — makes the flow appear larger
* **Zoom out** — makes the flow appear smaller
* **Fit view / reset view** — brings the flow back into view if you have moved around the canvas
* **Auto Layout** — automatically arranges the nodes in a cleaner structure, useful when the flow has many nodes and becomes difficult to read
### Minimap
At the bottom-right of the canvas there is a small minimap. It gives an overview of the full flow, which helps you quickly understand where you are on the canvas when the flow becomes large.
## Add Nodes Panel
The **Add Nodes** panel appears on the left side of the canvas. This panel contains the building blocks used to create the conversation flow. Each node represents one action or step in the call. The available node types are Conversation, Collection, Extract Variables, Call API, Decision, Transfer, and End Call.
Use a **Conversation** node when the agent needs to speak with the caller. This node is commonly used for greeting the caller, asking a question, responding to the caller, giving information, and deciding what to do next based on the caller's reply.
For example, the agent may ask, "Hello, how can I help you today?" After the customer replies, the agent continues based on that answer.
Use a **Collection** node when the agent needs to collect specific information from the caller. This is useful when the agent must ask several questions one by one and save the answers, such as name, phone number, email address, address, appointment date, order details, and survey questions.
This node is helpful when the agent must make sure all required information is collected before moving forward.
Use an **Extract Variables** node when the agent needs to identify important information from the conversation without asking again. For example, if the caller already says, "I want to book an appointment tomorrow morning," the system can extract the intent as appointment booking, the date as tomorrow, and the time as morning.
This node works silently in the background. The caller does not hear anything from this node.
Use a **Call API** node when the agent needs to connect with an external system. This can be used to check customer information, fetch order details, submit a form, create a ticket, update a CRM, or verify data from another system.
For example, the agent may collect a phone number and then use an API to check whether that customer exists in the company database.
Use a **Decision** node when the flow needs to choose between different paths. This node does not speak to the caller. It only checks information and selects the next step.
For example, if the caller says they are interested, the flow can go to the sales path. If the caller says they are busy, the flow can go to the callback path. If the answer is unclear, the flow can go to a clarification path.
Use a **Transfer** node when the call needs to be transferred to a human agent or another phone number. This is useful for escalating to support, transferring to a sales representative, routing to a department, or handling urgent and complex cases.
Use an **End Call** node when the conversation should finish. Every flow should eventually reach an End Call node. This ensures the agent ends the call properly instead of leaving the caller in silence.
## Top Toolbar
The top toolbar contains important actions for editing, saving, and testing the flow. It includes the agent name, undo and redo buttons, reset button, save button, error indicator, and test call button.
### Agent Name
At the top-left you can see the agent name — in this guide the example agent name is **Sample Agent**. There is also a pencil icon beside the name. Click the pencil icon to rename or edit the agent name.
### Undo and Redo
The undo and redo arrow icons allow you to reverse or restore recent changes. These buttons are useful when you accidentally move, edit, or delete something.
### Reset
The **Reset** button is used to reset changes.
Use **Reset** carefully. It may remove unsaved edits depending on the current builder behavior.
### Save
The **Save** button saves the current flow configuration. Always click **Save** after making changes. If the screen shows **Unsaved**, it means there are changes that have not been saved yet.
### Error Indicator
The error indicator shows whether the flow has configuration issues. For example, if the top bar shows **1 error**, the flow has one issue that needs to be fixed.
Before testing or publishing a flow, make sure there are no errors. Common errors include an empty required field, an unconnected node, a branch with no ending, a missing variable, or an incomplete tool or API setup.
### Test Call
The **Test Call** button is used to test the agent. After configuring the flow, click **Test Call** to check how the agent behaves in a real or simulated call.
Testing helps confirm that the agent says the right message, the flow follows the correct path, the call ends properly, and any variables or tools are working as expected.
## Right-Side Quick Settings Menu
On the right side of the canvas there is a small vertical menu with flow-level options: **Agent Defaults**, **PCA**, **Variables**, **Prompt Presets**, **Export**, and **Import**.
### Agent Defaults
**Agent Defaults** are the main settings for the whole agent flow. These settings control the default behavior of the agent, including language, voice, speech-to-text model, LLM model, call behavior, interruption behavior, and general prompt or personality.
Individual nodes can use these default settings, or they can override them when needed.
Set good defaults once, and only change node-level settings when there is a specific reason.
### PCA
**PCA** refers to post-call analysis. This section is used to configure what should be analyzed or captured after a call ends. PCA may help identify the call summary, call outcome, customer intent, collected information, and whether the call was successful or not. The exact PCA setup depends on the agent's use case.
### Variables
The **Variables** section is used to manage information that the agent remembers during the call. Variables can store values such as customer name, phone number, order ID, appointment date, caller type, and call outcome.
Variables are written using the format `{{variable_name}}`. For example, if the variable is `{{customer_name}}` and the customer name is Rahim, the agent can say, "Thank you, Rahim."
### Prompt Presets
**Prompt Presets** are pre-configured behavior settings for the agent. They help control the agent's tone and behavior without writing everything manually. Prompt presets can help the agent sound more natural, more empathetic, and more professional, and can make it better at confirming information and staying within scope.
### Export
Use **Export** to download or export the flow configuration. This is useful when you want to share the flow, keep a backup, move it to another environment, or review the flow outside the builder.
### Import
Use **Import** to upload an existing flow configuration. This is useful when you want to restore a previous flow, use a template, move a flow from another workspace, or reuse a flow structure.
## Start Node Settings
When you click the **Start** node, the right panel shows the Start node settings. The visible fields are **Label**, **User Away Timeout Seconds**, and **Max Tool Steps Per Turn**. The Start node is the beginning of every call flow, and it must be connected to the first working node of the conversation.
If the Start node is not connected to another node, the call will not know where to continue.
Keep **User Away Timeout** at a practical value such as 30 seconds, unless the caller needs more waiting time. Keep **Max Tool Steps Per Turn** at 3 unless the Verbex team suggests changing it.
**Use cases:** The Start node is required for every flow. It is used by all agent types, including customer support, survey, appointment booking, order confirmation, sales, and verification flows.
## Conversation Node Settings
When you click the **New Conversation** node, the right panel shows the Conversation node settings. This node controls what the agent says, how it responds, which model settings it uses, and whether it can use tools. The node has two tabs: **Behavior** and **Tools**.
If the Conversation node instructions are too vague, the agent may respond in a general or unexpected way. If the node is not connected to the next step, the flow may stop after the conversation.
Rename the label from a generic name like "New Conversation" to a clear name such as "Greeting" or "Ask Customer Need."
**Use cases:** Use this node whenever the agent needs to speak with the caller — greetings, asking questions, answering FAQs, explaining offers, confirming interest, and handling open-ended customer replies.
### Behavior Tab
The **Behavior** tab controls the main speaking behavior of the Conversation node. Here you can set the **Mode**, **Label**, **Instructions**, **Opening Message**, **Greeting Instructions**, **Knowledge Base**, **Model Configuration**, **Voice Settings**, **Allow Ending Call**, and **Global Node**.
Use **Static** mode when the agent must say an exact line. Use **Prompt** mode when the agent should respond naturally based on instructions.
If a Knowledge Base is needed but not selected, the agent may answer without using company-approved information.
**Use cases:** greetings, scripted questions, FAQ handling, product explanations, support conversations, policy responses, and natural customer interaction steps.
#### Model Configuration
The **Model Configuration** section allows you to control the node-level **LLM Model**, **STT Model**, **TTS Model**, and **Realtime Model**. By default these fields are set to **Use flow default**, which means the node follows the agent's default model settings.
For most flows, keep the model settings as **Use flow default**. Changing models unnecessarily may increase cost, latency, or inconsistency. Override a model only when a specific node needs better speech recognition, reasoning, or voice quality.
**Use cases:** a name collection step may need better STT, a complaint handling step may need stronger reasoning, and a multilingual flow may need a language-specific STT or TTS model.
#### Voice Settings
The **Voice Settings** section controls how the agent listens and responds. Here you can enable **Allow Interruptions**, set the **Pause Range**, allow the caller to end the call, add end-call guidance, and configure whether the node should act as a Global Node.
If Allow Interruptions is disabled during normal conversation, the caller may feel blocked. If it is enabled during legal or critical statements, the caller may interrupt before hearing the full message. The pause range should not be too short, or the agent may respond before the caller finishes speaking.
**Use cases:** interruptions are helpful for natural support calls, while disabling interruptions is useful for compliance statements, important instructions, payment warnings, or legal messages.
### Tools Tab
The **Tools** tab lets you add webhook tools inside a Conversation node. The tool is shown as **Webhook — new\_tool**. The available fields include **Name**, **Description**, **Method**, **URL**, **Wait Message**, **Timeout**, **Retry Count**, and **Parameters**.
The tool **Description** must clearly explain when the agent should use the tool and when it should not. If the URL, method, or parameters are incorrect, the tool may fail. If the **Wait Message** is empty, the caller may hear silence while the tool is running.
**Use cases:** checking order status, fetching customer details, creating a support ticket, booking an appointment, or sending data to another system.
## Collection Node Settings
The **Collection** node is used to collect specific information from the caller step by step. The node is shown as **New Collection** and includes fields such as **Label**, **Opening Message**, **Steps**, **Description**, **Instructions**, **Opening Static Message**, **Field Name**, **Field Type**, **Field Description**, **Model Configuration**, **Voice Settings**, and **Add Step**.
Do not leave the field name as `new_field`. Rename it to a meaningful name such as `customer_name` or `phone_number`.
Use **String** for phone numbers, IDs, and order numbers, because number fields may remove leading zeros or symbols. Ask one question per step for better accuracy.
**Use cases:** collecting customer name, phone number, email, address, order ID, appointment date, survey answers, complaint details, or any required form-style information.
## Extract Variables Node Settings
The **Extract Variables** node silently reads the previous conversation and saves useful information into variables. The node includes **Label**, **Fields**, **Name**, **Field Type**, **Description**, **Add Field**, **Fine-Tuning Examples**, and **Model Configuration**.
This node should be placed **after** a Conversation node, not before it. If the Description is unclear, the extracted value may be wrong.
Define the expected output clearly, such as `INTERESTED`, `BUSY`, `NOT_INTERESTED`, or `UNCLEAR`.
**Use cases:** classifying caller replies, detecting intent, identifying interest level, extracting appointment preference, detecting callback requests, or preparing values for a Decision node.
## API Call Node Settings
The **API Call** node connects the flow with an external system. The right panel includes **Label**, **Method**, **URL**, **Headers**, **Request Body JSON**, **Response Mapping**, **Speak While Waiting**, **Timeout**, and **Retry Count**.
The API node will not work if the URL is missing or incorrect. If it shows "No URL set," the node is incomplete. Make sure the request body uses the correct variables and the response mapping saves any value needed later in the flow.
**Use cases:** checking customer records, fetching order status, submitting lead information, creating tickets, verifying accounts, booking appointments, checking payment status, or updating a CRM.
## Decision Node Settings
The **Decision** node routes the call into different paths. In the example, the selected decision method is **LLM Condition (Natural Language)**, and the node has a condition named **Condition 1** plus a **Default (else)** branch.
Always connect the **Default** branch so unmatched cases do not get stuck.
Rename generic condition names like "Condition 1" to meaningful names, and make the prompt clearly describe when that condition should be selected.
**Use cases:** routing interested versus not interested callers, billing versus technical issues, eligible versus ineligible customers, successful versus failed API results, or transfer versus end-call outcomes.
## Transfer Node Settings
The **Transfer** node sends the call to a human agent, department, phone number, or SIP destination. The visible fields are **Label**, **Transfer Type**, and **Destination**. In the example, the selected transfer type is **Cold (SIP REFER)**.
The Transfer node will not work without a valid destination. If it shows "No destination," the node is incomplete. Enter a valid phone number or SIP address and make sure the node is connected from the correct previous branch.
**Use cases:** the caller asks for a human, the issue is urgent, the caller needs a specialist, the AI cannot complete the request, or the flow must hand off to sales, support, billing, or a manager.
## How These Nodes Fit Together
A complete flow can contain Conversation, Collection, Extract Variables, API Call, Decision, Transfer, and End Call nodes. A common working structure is:
```
Start → Conversation → Collection → API Call → Decision → Transfer or End Call
```
Placing nodes on the canvas is not enough. Each node must be configured **and** connected properly. If Collection saves the wrong field name, API Call may send the wrong data. If API response values are not mapped, Decision may not route correctly. Every path should end with either Transfer or End Call.
**Use cases:** complete customer journeys such as support calls, appointment booking, order checking, lead qualification, complaint collection, payment follow-up, verification, survey collection, and human escalation flows.
## Recommended Beginner Workflow
The safest way to start is with a simple structure and grow from there.
Create `Start → Conversation → End Call` and test the basic greeting.
If the agent needs to collect details, add a Collection node after the Conversation node.
If the collected information needs to be verified or submitted, add an API Call node after the Collection node.
If the API response or caller answer should decide the next step, add a Decision node.
If one branch needs human support, connect that branch to a Transfer node.
Make sure every branch eventually reaches an End Call node so the caller is not left in silence.
Do not build a complex flow all at once. If many nodes are added before testing, it becomes harder to find where the issue happened. Build the happy path first, save it, test it, and then add exception paths.
**Use cases:** first-time users, demo agents, support agents, appointment agents, survey agents, order confirmation agents, and lead qualification agents.
## Unsaved Changes and Errors
The top toolbar may show **Unsaved** and an error count such as **1 error**, **2 errors**, **3 errors**, or **4 errors**. This means the flow has changes that are not saved, or has configuration issues that must be fixed before testing.
Common causes include:
* Empty required fields
* Missing API URL
* Missing Transfer destination
* Incomplete Decision condition
* Unconnected branches or an unconnected Default branch
* A node that does not lead anywhere
* Placeholder field names like `new_field` still being used
Do not test the agent while the flow still shows errors.
Before running a test call, rename placeholder labels, replace placeholder field names, fill in all required fields, connect all nodes, connect all decision branches, make sure every path reaches an End Call node, click **Save**, and then click **Test Call**.
## Simple Example Flow
A simple customer support call can use this flow:
```
Start → Greeting → Collect Customer Info → Check Customer API → Decision → Transfer or End Call
```
In this example:
1. The call begins at **Start**.
2. The **Conversation** node greets the caller and asks how it can help.
3. The **Collection** node collects the caller's name and phone number.
4. The **API Call** node checks the customer details in the company system.
5. The **Decision** node checks the result and chooses the next path — if the customer is found, the flow continues support; if the customer is not found, the agent asks for clarification; if the caller asks for human help, the flow transfers the call.
6. The **Transfer** node sends the caller to a support representative.
7. The **End Call** node ends the call with a proper closing message.
## Best Practices
* Use clear node labels and keep each node focused on one job.
* Use **Static** mode for exact lines and **Prompt** mode for flexible responses.
* Keep Collection steps simple by asking one question per step. For example, ask "What is your phone number?" instead of "Please tell me your name, phone number, email, and address."
* Use clear field names, such as `customer_name` instead of `new_field`.
* Use API Call only when needed. Do not add API nodes unless the flow needs to check or send information to another system.
* Always add a **Default** branch in Decision so unclear or unexpected cases do not get stuck.
* Always configure the Transfer destination, because a Transfer node cannot work without a valid phone number or SIP address.
* Save before testing and fix all errors before running a test call.
* Make sure every path reaches an End Call node.
* Test every branch, not only the happy path — including cases where the caller is busy, gives an unclear answer, asks for human support, the API fails, the Transfer destination is unavailable, or the caller wants to end the call.
If a node contains too many instructions or too many scenarios, the agent may become inconsistent. If End Call nodes are missing, the caller may experience silence. If labels are unclear, the flow becomes difficult to review and debug.
**Use cases:** these best practices apply to all production flows, especially customer support, sales, complaint handling, survey, verification, and multi-branch call flows.