Step design best practices

[RRW Notes] Here are the thoughts on step design… Need an opening here
Step naming and iconography

General tips on step naming and iconography:

  • Step icons and shapes should be clear and concise, with few details – think traffic signs
  • Organize step shapes by intent, not by channel. For example, Say message (Phone) and Hang up call (Phone) steps will have different shapes because they carry different intents, even though they are both related to Phone.
  • In step templates, both name and description fields are mandatory to fill in
  • Aim to make custom API steps serving as data sources for each of the API call types used in the flow (more details on this below).
  • Include default No reply and Error paths wherever relevant in steps so that the flow encourages the user to cover the unhappy flow paths as well.


Step names

Name the steps by their intent, preferably with verbs, and put the channel in brackets at the end of the name. For example: Send message (SMS); Hang up call (Phone). Use sentence case.

Step shapes
Shape Name Description Examples
Arrow right Steps that imply either leaving the flow for a third party service or addressing such a service without leaving the flow. API steps; Asynchronous flow triggers (from a flow); Read from database
Arrow down Steps that imply the current flow continuation or execution. Trigger steps; GoTo steps
Bubble left Steps that address a message from the bot to the end user. SMS, Voice prompt, choices, etc.
Circle Steps that end the flow Hang up, End flow, Get result
Diamond Condition / Logic steps Condition, Javascript


Step icons


Icon Name Description Examples
OneReach Steps that leverage OneReach services for number provisioning and setup SMS / Voice flow triggers (through OneReach services)


General step UX


The contents of each step can be divided into the ‘core’ part and ‘advanced’ part. Everything the user has to necessarily fill in and see is considered ‘core’ and needs to be placed on top of the step settings sidebar. Everything that can be handled by system pre-fills or defaults and would not greatly affect the flow is considered ‘Advanced’ and needs to be placed under the ‘Advanced’ collapsible group, collapsed by default.



For a Send message (SMS) step, the only ‘core’ part is the message text. The rest of the step settings are ‘advanced’, because the Bot number and End user number fields can be pre-filled by the system, and the ‘Send immediately’ option defaulting to ON is a suitable setting for most of the step users.


Input fields

The label of the input field, its placeholder text and help text should use sentence case, i.e. the first letter of the sentence should be capitalized.




Label: Result variable name

Placeholder text: Flow variable name to set the step result to

Help text: Specify a name of the flow variable where the user’s response text will be stored.

Bot phone number and End user phone number fields

Bot phone number and End user number fields should be present in any SMS step. In all SMS steps excluding Triggers, they should be placed into the Advanced collapsible group (collapsed by default). Both of these fields should be pre-filled by the variable names from the flow trigger step so that a beginner user does not have to even see these fields for the flow to work.

Data out fields

Label and Placeholder text for the data out field should be the same in all steps in Flowbuilder. Help text can change from step to step to explain what will be stored in the Data out field for this particular step. The recommended format is ‘Specify the name of the merge field where … will be stored and can be reused later in the flow.’




Label: Merge field

Placeholder text: Merge field name

Help text: Specify the name of the merge field where the step’s result will be stored and can be reused later in the flow.


Show error

Show error should be ON by default in most steps.