Skip to main content
The flow builder is where you draw a flow agent: steps on a canvas, connected by their transitions. This page covers the canvas itself: adding and connecting steps, keeping a large flow readable, and fixing what the builder flags. What each step does is on the step type pages.

Before you start

  • To edit, your role must allow editing agents. Without it the builder opens with View only: “You do not have permission to edit this agent. Changes you make here will not be saved.” See Roles and permissions.
  • The canvas can’t be edited on a phone. On a small screen you get an overview of the agent and can test it, but not change it.

Find your way around

The flow builder with the Order Support flow: the header with Test, the tool rail on the left, the canvas toolbar at the bottom, and the Verify the order step's settings panel open on the rightThe flow builder with the Order Support flow: the header with Test, the tool rail on the left, the canvas toolbar at the bottom, and the Verify the order step's settings panel open on the right
The Start step has its own colour, a lime frame and a solid lime tab, so you can find where calls begin at a glance. No other step uses it. The app calls steps “nodes” on some buttons and labels, such as Add node. These docs say “step”.

Add a step

1

Open the step list

Click Add node in the tool rail.
2

Pick a type

Type in Search node types or scroll the list, then click the type. Hover a type to read what it does.
The Add node list open next to the tool rail, with Search node types and the step types Conversation to Change agent settingsThe Add node list open next to the tool rail, with Search node types and the step types Conversation to Change agent settings
3

Set it up

The step appears in the middle of the canvas and its settings panel opens. Give it a label (up to 100 characters) so you can tell it apart on the canvas and in call logs.
You can also add a step from a transition: drag from a transition’s handle on a step card and drop it on an empty part of the canvas. The step list opens, and the step you pick is connected to that transition. This works while the transition isn’t connected to anything yet. Every flow has exactly one Start step. It isn’t in the list, and you can’t delete or copy it.

Connect steps

Steps are connected through their transitions. Each transition on a step card has a handle; the connection from that handle to another step says “when this transition is taken, go there”.
1

Add a transition

On the step card, click Add (“Add new transition”) and choose a type, such as Prompt. The types a step offers depend on the step. See Transitions.
The Add menu on the Start step card, offering Prompt, When a live variable matches, DTMF input and After user repliesThe Add menu on the Start step card, offering Prompt, When a live variable matches, DTMF input and After user replies
2

Set it up in the settings panel

Click anywhere on the transition on the card. The step’s settings panel opens on that transition’s settings. Fill in what it needs there, such as When to take this path for a Prompt transition or the Keypad key for a DTMF input transition. Changes save as you make them.
The Verify the order step on the canvas, with its second Prompt transition tagged Conditioned, and the settings panel open on that transition: When to take this path, Offer it only when with one rule, Extractions, and Delete transitionThe Verify the order step on the canvas, with its second Prompt transition tagged Conditioned, and the settings panel open on that transition: When to take this path, Offer it only when with one rule, Extractions, and Delete transition
3

Draw the connection

Drag from the transition’s handle to the step it should lead to.
The canvas enforces a few rules:
  • A step can’t connect to itself.
  • Two steps can be connected only once in the same direction.
  • Each transition handle has one connection.
  • A step set to return to the step that called it has no outgoing connections. See Global steps.
A transition with no connection does nothing on a call. To follow a connection on a large canvas, double-click it: the canvas moves to the step it leads to, and opens its group if it’s in one. To remove a connection, click it, then click the delete button that appears in its middle. To delete a transition, open its settings and click Delete transition at the bottom, or hover the transition on the card and click its ×. Its connection goes with it. A Prompt transition with Offer it only when rules shows a Conditioned tag on the card. See Transitions.

Select, copy and delete steps

  • Click a step to select it and open its settings. Hold Cmd (Mac) or Ctrl (Windows) and click to add more steps, or hold it and drag to select everything in a box.
  • Copy and paste the selection with Cmd+C and Cmd+V on Mac, Ctrl+C and Ctrl+V on Windows. The Start step is never copied.
  • Press Delete or Backspace to delete the selected step. The builder asks first, and deleting a step also removes its connections.

Move around the settings panel

The settings panel shows a step’s main fields, then a row for each section. Sections, and rows inside them, open one level down, with Back to return:
  • Transitions lists every transition of the step, in the order the card shows them. Click one to open its settings. Else, Auto, After user replies and a step’s fixed transitions (such as On Success) are listed but have nothing to set.
  • Variables lists the step’s variables. Click one to open its card.
  • Clicking a transition on the canvas opens the panel straight on that transition. Clicking the step itself, or its Node settings button, takes the panel back to the top of the step.
The settings panel of the Verify the order step one level down, on the order_id variable card, with Back at the topThe settings panel of the Verify the order step one level down, on the order_id variable card, with Back at the top

Group steps

Groups fold a part of the flow into one card, so a large flow stays readable.
1

Select the steps

Select two or more steps.
Three steps selected on the canvas, with the Group 3 items button at the top leftThree steps selected on the canvas, with the Group 3 items button at the top left
2

Create the group

Click the group button that appears (for three steps it reads Group 3 items), or press Cmd+G on Mac, Ctrl+G on Windows. In New group, enter a Group name, for example “Book appointment”, and click Group.
The New group dialog with the group name Order help and the Group buttonThe New group dialog with the group name Order help and the Group button
Once you have groups:
  • Switch Show between By groups (each group is one card) and All steps (every step, as if there were no groups).
  • Click Open group on a group card to open it. The path at the top (Where you are) shows how deep you are; click Flow to go back to the top.
  • A group card shows how many steps it holds and how many need attention. During a test call, the group the call is in shows In progress.
  • Use the card’s Group actions menu (the … button) to Rename or Ungroup.
  • Use a step’s menu to Add to group, Move to group, start a New group… or Remove from group.
Groups only change how the canvas looks. They don’t change how a call moves.
The canvas shown By groups, with the Order help group card listing its three steps and Open groupThe canvas shown By groups, with the Order help group card listing its three steps and Open group
The Order help group card with its Group actions menu open, offering Rename and UngroupThe Order help group card with its Group actions menu open, offering Rename and Ungroup

Connections into and out of a group

Shown By groups, connections still show where a call can go:
  • A closed group. Connections into or out of a group card are drawn as lines to and from the card. When one line stands for several connections, hover it to see how many (“3 connections”). Double-click a line into a closed group to open the group.
  • An open group. Inside a group, a connection to or from a step outside it ends in a dashed label, such as From Order status or To Anything else?. Click the label to go to that step. When several steps are involved, the label reads, for example, From 3 steps: click it and choose one under Go to a step. A “×2” on a label means that step has two connections here.
Inside the Order help group: its three steps, with dashed labels From Order status leading in and To Anything else? leading outInside the Order help group: its three steps, with dashed labels From Order status leading in and To Anything else? leading out

Find a step

Press Cmd+F on Mac or Ctrl+F on Windows, or click Find node. Type in Find in nodes and notes. The search looks in step labels, step types, messages, transfer messages, phone numbers, descriptions and transition conditions.
The Find box with the search order showing match 1 of 7, and the matching Greeting step selectedThe Find box with the search order showing match 1 of 7, and the matching Greeting step selected
  • Press Enter for the next match and Shift+Enter for the previous one. Each match is selected and centered.
  • Use Filter by type (the button next to the search box) to search only some step types. The list shows how many steps of each type the flow has. Tick one or more types, or choose All types to clear the filter. Steps that don’t match fade out.
The Find box searching for order, with the Filter by type list open: Conversation ticked with 5 matches, then Start, Tool, End call, Transfer call and RouterThe Find box searching for order, with the Filter by type list open: Conversation ticked with 5 matches, then Start, Tool, End call, Transfer call and Router

Tidy the canvas with auto layout

Click Auto-layout nodes in the canvas toolbar and pick a layout:
The Auto-layout nodes menu above the canvas toolbar, with Vertical, Horizontal and MetroThe Auto-layout nodes menu above the canvas toolbar, with Vertical, Horizontal and Metro
The Start step always comes first. In a flow with groups, each group is laid out on its own.

Keyboard shortcuts

Press ? to see every shortcut. On the canvas: In the whole editor:
The Keyboard shortcuts panel listing the flow canvas shortcutsThe Keyboard shortcuts panel listing the flow canvas shortcuts

Save and fix issues

Your changes save to your draft automatically as you work, even while the flow has issues. Cmd+S (Ctrl+S on Windows) saves right away. Testing waits until changes are saved: “Please save changes before testing”. See Drafts and versions. When something in the flow is incomplete, a red issue button with a count appears in the header. Click it to open Configuration issues: it lists each problem by step, and Focus takes you to that step. Common ones:
  • “System instructions are required”: the System prompt in Global settings is empty.
  • “All transitions must have descriptions”: a transition hasn’t been filled in, for example a Prompt transition with no condition.
  • “Please select a tool for this node to use”: a Tool step has no tool.
  • “Trigger condition is required for global nodes”: a global step has no trigger condition.
The Configuration issues list open from the red issue button, showing a Tool step with 'Please select a tool for this node to use' and a Focus buttonThe Configuration issues list open from the red issue button, showing a Tool step with 'Please select a tool for this node to use' and a Focus button
A variable a step uses but the agent doesn’t define gets an amber chip that says it isn’t defined in this agent, with Add as dynamic variable. That is a hint, not an error. Add as dynamic variable opens your dynamic variables with the name filled in. See Test values and the undefined variable chip. Deleting a variable that steps still use asks first, whatever its kind (a step’s own variable, a live variable, a local or dynamic variable). The dialog lists the steps that use it; click one to go to it. Delete anyway removes the variable, and those steps then show it as not defined. See Variables.
The Delete variable dialog: order_id is used in 2 steps, with links to Share delivery update and Start a return, and the Delete anyway buttonThe Delete variable dialog: order_id is used in 2 steps, with links to Share delivery update and Start a return, and the Delete anyway button

Good to know

  • There is no undo on the canvas. To go back to an earlier state, use a saved version. See Drafts and versions.
  • When you view an older version, every panel is read-only.
  • While a test call runs, the step the call is in gets a moving ring, and Live call logs show what happens step by step. See Test your agent.

Transitions

Each transition type and how the next step is chosen.

Step types

What every step does and which transitions it has.

Flow settings

The Global settings panel.

Test your agent

Browser call, phone call and chat.