Let's Talk About Flows



Flows is a great new concept for Beach Core. In simple terms, it’s a GUI for building conversational journeys that use your API resources to bring your data to life.

In this topic I will add posts to introduce some of the key features of Flows, so you can start to think about how you’ll build conversations.

For the purpose of these posts, we will use a simple Customer Services Support assistant chatbot as an example application, though the possibilities a far greater, I think it’ll be helpful.

The GUI for Flows at the moment is integrated into our default Active Admin based administration area (so it isn’t the most pretty thing in the world), for use by the Platform Instance owners (admins, editors etc.). We’ll be adding a more public UI soon, but the premise will be the same.

Flows 101


Flows are an abstract concept that are made up of 1 or more Screens. How you choose to create your Flows and connect them together using the various features provided, is down to you - there are no strict rules, it’s designed to be flexible. We will however, share our experience and “best practises” with you as having all that freedom comes at price.

Flows are visible at /admin/flows

By default, you will see a Filesystem style layout, as Flows can be organised into Directories. This is particularly helpful as you find your conversations growing.

By default, you will have App.flow created - this is your Root Flow, and the default start point for a new conversation.

Clicking on this flow, will take us to the Flow detail view. There’s not much to see here currently, just some basic information.

Once you have added your first screen, then you’ll also be able to “Preview” your flows in the web viewer. This is just a simple representation of your conversation so you can get a feel for it, but isn’t intended to be a 100% pixel perfect recreation - that’s for you to enable in your own front end.


A flow is a series of Screens and ultimately, the most important part of building a conversation. Each Screen represents a momentary exchange, triggered ordinarily (but not always, more on User-triggered flows later) by our Bot.

Let’s take a look at the anatomy of a single Screen.

Which translates to this in the front end display of the conversation in our BeachChat widget.

We have 3 key areas, each highly configurable - Header, Bot Control, User Controls

1. Header

The Header is where we control the Screen Settings, including the Bot message text.


When the screen is created, it is assigned a unique ID. We can use this ID should we wish to use the GO_TO_SCREEN_BY_ID action at any point in the flow.

We can determine the primary template colour Main Color for the screen, using the colour picker provided.

A very important and regularly used option, is to mark this screen as a Rotator. This means that the screen will automatically transition to the next screen in the flow, without waiting for User input. This is very useful when our Bot is monologuing.

Even more important, when using the rotator option, is to consider the delay time, in ms, before the transition takes place. During this time, a typing indicator will be shown to visualise that the Bot is considering and enacting a further response. The psychology of messaging timing is a very important part of the UX of designing natural flowing conversational experiences.

Finally, we can determine the action to be triggered as the rotator function. The default action is move to the next screen, but this is a great opportunity to introduce the full list of action available.

Navigation Actions

GO_TO_SCREEN_BY_ID - will navigate to the Flow and then the specified screen with the given ID.
OPEN_FLOW - Will navigate to the first screen of the given Flow.
NEXT_SCREEN - Will navigate to the next screen in the current flow
PREVIOUS_SCREEN - Will navigate to the previously loaded screen
PUSH_MESSAGE - Will push a message to the Chat history for the given persona (Bot or User)
SUBMIT_ON_SERVER - Will trigger a handler for interacting with the server.
SOCIAL_NETWORKS_ACTION - Will trigger an action, such as following or sharing to a nominated social media account
OPEN_MENU - Will open the persistent Menu widget inside the Chat window
OPEN_MODAL - Will open a modal widget inside the chat window
OPEN_WEBVIEW - Will open a webview (mobile native) or URL in browser (web)
OPEN_CAMERA - Will open the camera app (mobile native) or file explorer / finder (web)
OPEN_GALLERY - Will open the image gallery (mobile native) or file explorer / finder (web)

Often, the selected Action will have further configuration options and we will visit these in more detail later.


This is where we can input our Bot Text messages, basically the words that the Bot says to our User.

The default behaviour is to input 1 (or ideally more) variants and the system will select randomly which message to show, in order to mix things up and keep conversations from getting stale and repetitive.

In addition we have a more advanced option, whereby we can use the State system for determining which message should be shown. We can write State Conditions in our State definitions that will check for a suitably matching state in order to show that message or series of messages.

Let’s take a quick segue into a couple of the more powerful and advanced topics that are related to this.

Template Variables

Sure we can add a simple text message like this "What brings you to us today?", that’s easy enough.

But what if we wanted to, instead of saying “today”, state the current day of the week. We could of course, just write it, but when the User visits tomorrow, it would be incorrect if this was hardcoded.

So to work this kind of dynamic data, we have a fully loaded JSON object containing all manner of helpers, data sources, system resources and a flexible Model object where we can put any data from the current state and access it in our screens.

Here’s an example of this Object.

    "loaded": true,
    "date": 10,
    "hours": 22,
    "minutes": 40,
    "seconds": 49,
    "month": "August",
    "dayOfWeek": "Friday",
    "Model": {},
    "DataSource": {}

To use it in our Bot text, our Header variant, we can use {{}} to inject the variable into the text.

For example, "What brings you to us on this glorious {{dayOfWeek}}?

This is just a taste of how to expose and use live data from our Beach Core instance, from either our Beach Core Engine or other custom Engines we may have developed.


On the basis that we have this JSON data object available, we have a really great way to create much more variability in our conversational logic. We can achieve this with States.

As an example, let’s say that we will likely answer this message on a weekend, but we want a different response depending on whether it is Friday or Saturday.

We can implement this using States and associated State Conditions, like these examples.

That’s just a taster, more on these another time.

Back to Header

Wrapping up the Header Section, you can optionally choose to display a progress bar widget - useful for flows that have a set number of steps to complete, such as a conversational webform or survey, and it’s important for the User to know where they are in the process.

The Rating widget is an arbitrary numeric badge - could be used to display Points from a reward system, a counter for unread messages, anything you can think of.


You can specify a background image to use as a wallpaper for the BeachChat widget.


Decide if you wish to explicitly hide the User actions section of the Screen elements.

Bot Control

In the centre of the Screen we have the ability to add rich controls, or components, to our conversation. Our Bot has the ability to do way more than just send a text message and this is how it is brought to life.

By clicking the plus icon, you will be presented with a directory of the available Control types that ship with Beach Core.

These generic controls are also extendable - you can create your own unique controls in your custom Engines.

Control Types

  • HTML
  • Metrics
  • Card
  • Items in a Row
  • Combination Control
  • Checkbox List
  • Radio List
  • Input
  • Button
  • Select
  • Video
  • Image
  • Chart
  • Profile

I will go through each of the Controls in detail in another topic, but let’s take a simple and common one - the Video control.

Simply select the control from the Controls directory and then enter your Youtube or Vimeo URL. Optionally, you can upload a custom Preview image.

As you can also see, we have access to States and State Conditions in here too, meaning we could show different videos to different people based on different conditions being present.

You can add any number of Controls in this section and they’ll be stacked as separate messages for the purpose of the conversation. They will be sent as a cluster of messages, starting with the Bot Text message then the controls, in the order that they are presented in the Screen. To reorder, you can drag and drop the controls to suit.

User Contol

The footer section of the Screen is dedicated to User Control or User Actions.

This is assuming that the Screen is not a Rotator and the Footer is visible.

Similarly to Bot controls, we click the “+” icon to bring up the User Controls directory. Currently there are only a few options.

  • Button
  • Input
  • Select

Each of these controls can be used individually, but most often they are used in combination.

The simplest use case is the Button control. We typically use these as “Quick Replies” - a set of pre-defined User responses.

Again, Buttons (and all User Controls) have full access to States and State conditions.

You can define a Model name against which data can be stored and accessed.

You can define a Value, which is optional, should you wish the data that’s stored based on User Action to be different to the Button Label text.

You can define the width of the button, which is very useful when using multiple buttons together or buttons in conjunction with other User Control types.

Finally, you can instruct the Action type to be taken when the button is clicked or pressed, we already covered the available action types earlier.

Further to this, another popular combination would be to combine an Input or Select type control with a button. Let’s expand the example.

Let’s say we want to present a list of options to the User, in order to ascertain the reason for their visit today, I’ve decided to use a Select Control for this, and a button for the submit action. Here’s how it would look.


Let’s jump into setting up the Select control first.

I’m not using States or State conditions in here, this is a generic case.

I have declared a new Model, called visitReason which is where I want to store the User’s selection.

I have decided that this Select control should be 80% of the available width of the widget, allowing enough room for my submit button.

Finally, I add the Select options, declaring an Id for each and it’s label text.

Now let’s jump into the submit Button control.

As you can see, since I want to navigate the User through the logic tree based on their response, I am using separate States for each of the Select options, which are controlled by the State Condition check I have declared.

So, for example, in the first State named Product, I am checking if the Select box has set the visitReason model to the Id of the Product option, product.

If that is found to be true then it will present this button state and when the User clicks it, will trigger the OPEN_FLOW action which directs the user to my flow dedicated to handling Product information.

You can also see that I have used an Icon in the button label text, which you have access to the full material icons set.

All in all that was a fairly brief but also quite thorough introduction to the Flows feature inside of Beach Core engine.

It works with our BeachChat.js javascript library and we’re working on native libraries for mobile devices for presenting the Conversation to your users easily with a few lines of code. Otherwise, all the API’s are there for you to make your own Messenger interface.

There’s a lot more to show you on this already and we’ve barely scraped the surface of the roadmap, watch this space!!!

Beach Core Engine Changelog
Project Vulcan - Bot Module