> ## Documentation Index
> Fetch the complete documentation index at: https://dialnexa.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Conversational Flow Agents in DialNexa
> Build DialNexa Conversational Flow Agents with visual nodes, explicit branches, transfer paths, and controlled call outcomes.
A Conversational Flow Agent in DialNexa uses a visual node-based canvas instead of a single system prompt. Each node is a conversation state with its own prompt, branching conditions, and optional actions. The agent moves from node to node based on what the caller says, following the explicit path you designed.
A flow agent is a map. If the map has a road to nowhere, the caller will eventually find it.
## When To Use DialNexa Conversational Flow Agents
Choosing between a single prompt agent and a flow agent depends on how much structure your use case requires.
| Factor | Single Prompt Agent | Conversational Flow Agent |
| ------------------------ | ----------------------------------------- | -------------------------------------------- |
| Branching complexity | Low to medium (handled in prompt logic) | High (explicit branches per node) |
| Script compliance | Enforced by prompt instructions | Enforced by node structure |
| Conversation flexibility | High (agent can handle unexpected topics) | Lower (paths must be defined in advance) |
| Visual auditability | None (logic lives in text) | High (canvas shows the full path) |
| Ease of setup | Faster for simple use cases | More upfront work, but clearer at scale |
| Transfer handoffs | Configured in prompt | Configured per-node with explicit parameters |
Use a flow agent when:
* The call has multiple clearly separated stages (greeting, qualification, objection handling, close)
* Compliance requires specific disclosures at specific moments
* Transfer handoffs need different context collection depending on the caller's answers
* Your team needs to review and approve the call logic visually before publishing
* The conversation is long enough that a single prompt becomes hard to reason about
Use a single prompt agent when:
* The call is focused and linear (reminder, survey, simple qualification)
* You need fast iteration and the prompt is short enough to reason about easily
* Callers may go off-script in ways that are hard to anticipate and define as branches
## Canvas and Visual Builder
The flow builder opens a canvas where you place and connect nodes. The canvas is a directed graph: nodes are states, edges are transitions triggered by branch conditions.
**Canvas controls:**
* Drag nodes to reposition them on the canvas (positioning is cosmetic and does not affect logic)
* Click a node to open its configuration panel on the right
* Draw an edge from one node's output port to another node's input to connect them
* Zoom and pan with trackpad gestures or the canvas controls
Arrange the canvas so the happy path flows left to right or top to bottom. This makes the flow easier to trace during reviews and debugging.
## Node Types
The entry point of every flow. Every flow has exactly one start node. It defines the agent's initial prompt and welcome message -- what the agent says the moment the call connects.
The start node's output connects to the next node the agent should move to once the opening exchange is complete.
The primary building block. A conversation node holds:
* A node-specific prompt telling the agent what to say and ask at this stage
* One or more branches defining the conditions that move the caller to the next node
* Optional transfer settings if this node can hand off to a human
* An end-call flag if the call should end after this node
The agent stays in a conversation node until one of its branch conditions is satisfied.
Calls an external API mid-conversation. Use function nodes to look up data (customer record, availability, balance) or write data (log outcome, create ticket) before the flow continues to the next node.
The function node does not speak to the caller. It executes silently and then the flow proceeds to the connected next node based on the function's success or failure.
Transfers the call to a human agent or external number. Configure:
* Transfer destination (phone number or SIP address)
* Hunt mode (try multiple destinations in order)
* Representative brief (text the agent speaks to the human before transferring)
* Timeout behavior (what happens if no one picks up)
A transfer node ends the flow for the AI agent. The caller is handed off to the destination.
Terminates the call. Every flow must have at least one end node reachable from every possible path. Connect end nodes at the conclusion of each conversation outcome (confirmed, declined, transferred, timed out).
A routing node with no spoken content. It evaluates a condition against variable values or prior responses and directs the flow to different next nodes based on the result. Use logic splits to route based on data (e.g., account balance above a threshold goes one way, below another).
A node that can be reached from any other node in the flow without an explicit edge. Use global nodes for universal behaviors: for example, a "speak to a human" request that can happen at any point, or a compliance disclosure that must be delivered regardless of conversation state.
Global nodes reduce the need to duplicate branches across every node.
## How Flow Execution Works
When a call starts:
1. The flow enters the **Start Node** and the agent speaks the welcome message.
2. The caller responds. The transcriber converts speech to text. The LLM evaluates the response against the current node's branch conditions.
3. The matching branch condition is triggered, and the flow moves to the connected next node.
4. The process repeats until the flow reaches an **End Node** or **Transfer Node**.
If no branch condition matches, the agent stays in the current node and prompts the caller again. Configure a fallback branch ("none of the above" condition) to handle unexpected responses and prevent the caller from being stuck.
## How to Start Building a Flow Agent
On the Agents tab, click **Create agent** and select **Conversational Flow Agent**. Name the agent.
Set language, voice, LLM, and transcriber in the Stack tab before opening the canvas. These settings apply to the entire flow.
Click the **Flow** tab. The canvas opens with a Start Node already placed.
Click the Start Node. Write the opening prompt and welcome message for the agent's first turn.
Drag a Conversation Node from the node palette onto the canvas. Connect the Start Node's output to this node. Write the prompt for this conversation stage and define branch conditions.
Add nodes for each stage of the conversation. Connect them with edges. Add End Nodes at every terminal state.
Add a Global Node for "caller asks to speak to a human" or any other response that should be handled regardless of the current node.
Click through every path on the canvas. Confirm every branch leads somewhere and every path eventually reaches an End or Transfer node.
When the flow is complete and tested, click Publish. Enter a descriptive version title.
## Review a Flow Before Publishing
Follow every branch path from the Start Node to its terminal. Every path must reach an End Node, Transfer Node, or a Global Node that handles the call.
Branch conditions are evaluated by the LLM. Ambiguous conditions ("caller seems interested" vs. "caller explicitly said yes") produce ambiguous routing. Make conditions specific.
If any Transfer Node is in the flow, confirm: destination number, hunt mode settings, representative brief text, and timeout behavior.
For each Function Node, check what happens if the API call fails. The flow should have a failure branch that handles the error gracefully.
Do not only test the expected caller behavior. Test what happens when the caller goes off-script, says something unexpected, or asks for a human.
## Limitations of Flow Agents
Compared to single prompt agents, flow agents have constraints you should plan for:
* **Every path must be defined.** Callers can only go where the flow allows. Unexpected conversation turns require adding branches, not just editing a prompt.
* **Higher setup time.** Building a well-tested flow takes more initial effort than writing a prompt.
* **No global memory across nodes by default.** Each node prompt operates in the context of the conversation so far, but the LLM does not automatically carry forward information from one node unless it is designed into the branch conditions or variable passing.
* **Canvas complexity grows quickly.** Large flows with many branches become hard to audit. Use Global Nodes to avoid repetition and keep the canvas manageable.
## Flow-Specific Pitfalls
Visual node placement does not fix branch condition accuracy. A flow where every node connects to the next node in the right visual direction can still route incorrectly if branch conditions are ambiguous or missing. Read the node configuration, not just the canvas.
If a node has no fallback branch for unexpected responses, the caller can get stuck. Every conversation node should have a catch-all branch that either re-prompts or moves to a defined state.
Flow transfer nodes can use dynamic variables for destination numbers. If the variable has no value, the transfer fails. Set fallback defaults or test with explicit values before publishing.
A node with no end-call flag and no connected next node leaves the caller in an undefined state. Double-check that every terminal node either has `end call` enabled or connects to an End Node.
Draft edits to the flow are not live until published. If callers are experiencing old behavior, confirm the phone number or workflow is pointing to the latest published version, not an older one.
## Recap
Use a Conversational Flow Agent when the call needs explicit branches and controlled outcomes. Connect every node, define failure and transfer paths, review the graph, and test each important route before publishing.
## Related Reading
Understand all agent types and how to choose between them.
Configure transfer destinations and hunt mode.
Supply values to flow nodes using dynamic variables.
Understand draft and published state for flow agents.