Build a flow
Plan a flow, place and connect nodes, store and reuse values, and test it, with the differences between USSD, chatbot, voice and automation projects.
This page walks through building a flow by hand on the canvas. The steps are the same for every project type; the entry point and the nodes you reach for differ, and the tabs below show how. If you would rather describe the flow and have it built for you, see Build with Buni.
Before you start
You need a project. See Create a project if you have not made one yet, and The canvas for the parts of the editor.
Plan the flow
Sketch the journey before you place anything. Answer four questions:
- What does the user see or hear first?
- What do you need to collect from them, and in what order?
- Where does the flow branch, and on what?
- What happens when input is invalid or a service fails?
A plan for a mobile money menu might look like this:
Main menu
1 Send money -> recipient -> amount -> confirm -> call payments API -> done
2 Balance -> call balance API -> show balance
3 Help -> show help text
anything else -> error message -> back to main menuBuild it
Start from the entry point
Every flow starts at one node. Which one depends on the project type:
A Menu whose Menu Type is Main. It is the first screen a user sees after dialling your code. Screens in the middle of the flow are Intermediary menus, and a Last menu shows its text and ends the session.
Add the next nodes
Open Show Nodes Library, then drag a node onto the canvas or double-click it. Faster still, drag from a node's output handle onto empty canvas and pick the next node from Add Node; it arrives already connected.
Configure each node
Double-click a node to open its settings. Give it a clear name, fill in its fields, and set Output variable if a later node needs its result. Select Save in the panel when you are done.
Branch
Use a Router to send the flow down different paths based on input or state. Add one condition per path and a default for everything else. Menus and voice menus also branch on their own, with one output handle per option.
Handle the unhappy paths
Connect every failure handle on API and Integration nodes, and route a Router's default to an Error node or a helpful reply. See Error handling.
Changes save automatically. When the flow works, publish it so real users get the new version.
Which nodes to reach for
Menus do most of the work: they show text, collect a choice or typed value, and branch on the option. Add API for live data, Data Store for your own records, Collect Payment for mobile money, and Messaging to send an SMS receipt after the session. Keep screens short: users read them on a feature phone. See USSD menus and sessions.
Store and reuse values
Set Output variable on a node and its result is saved to state under that name. Read it anywhere later in the flow with a template:
You are sending {{state.transfer_amount}} to {{state.recipient_phone}}.
Reply 1 to confirm.Type {{ in a field to open the variable picker. Store API keys as credentials and reference them as ${CREDENTIALS.NAME}, never as plain text. Full details are in Variables and templating.
Common patterns
| Pattern | Shape |
|---|---|
| Menu and branch | Menu or Intent, then Router, then one path per choice |
| Collect, validate, act | Ask, check with a Router or Function, then call the API; invalid input goes to Error and back to the question |
| Fetch and show | API with its response captured into variables, then a Menu or Reply that shows them |
| Confirm before acting | Show a summary, branch on yes or no, and only then call the API that changes something |
| Loop back | A Back or Main menu option connected to an earlier node |
Keep large flows readable
- Name nodes after what they do, such as "Get balance", not "API 3".
- Group each part of the journey in a frame (⌘G / Ctrl + G) and label it.
- Leave sticky notes where a decision is not obvious.
- Replace long crossing lines with jump links. See Connections.