Building Flows

Flows are the brains of your chatbots in Flow XO. A Flow is a series of sequential actions that a bot will perform whenever activated by a Trigger.

Anatomy of a Flow

A Trigger is some kind of input into the system. Most commonly this is a message arriving from a messaging platform, such as Facebook Messenger, but there are a lot of different kinds of triggers in Flow XO, including Webhooks, e-mail, new RSS feed items, and many more. You can read more about triggers here:

An Action is something that your bot does, such as sending a message to the chat, presenting the user with a series of choices, sending a video, etc. But as with triggers, there are many things your bot can do besides just send messages and gifs, such as sending e-mails, interacting with external systems, waiting for a future date or time, sending SMS messages, and much more. You can read more about actions here:


Every Trigger and Action can be selectively executed based on a wide variety of available data using Filters. Filters are simple rules that determine if a trigger should fire or an action should run given all the data we have at the current moment. For example, a trigger may have a filter that only allows it to fire between the hours of 9am and 5pm, or an action may have a filter that will only allow it to run if the user answered the previous question with "Yes". 

Filters on Triggers are primary means for determining which flows should execute and when.
Filters on Actions are the primary means for enabling conditional or branching logic within a single flow.

Filters Overview

You can read more about filters here:

A Simple Example

If you're completely new to Flow XO, it will be useful to walk through the process of building an actual flow before diving too much deeper into the art of flow-building. You can find just such an example here, where we will go a step by step through the process of building a very simple flow, like this one:

Simple Bot Flowchart

Structuring Your Bot

There are many different ways you can structure your chatbots in Flow XO. Which you choose will largely depend on the complexity of your conversation design, whether you will be building a keyword bot, an NLP bot, or a hybrid, and whether or not your bot is a single-purpose or a multi-purpose bot.

Single-Purpose vs Multi-Purpose Bots

One of the first things you will need to determine when designing your bot is whether or not it needs to perform a variety of tasks for end-users ( multi-purpose), or just facilitate a single, well defined linear task or process (single-purpose)?

Single Purpose Bots

If you are building a single-purpose bot you will likely have a central flow that runs the first time a user interacts or installs your bot, that introduces the bot to the user and guides them through whatever process or marketing sequence the bot exists to facilitate.

If your bot is also relatively simple in terms of the number of branche/filters required, you may get away with implementing your entire bot as a single flow. If, however, your bot does a lot of branching, you will probably want to split it up into multiple flows, where each flow represents any branch with more than a couple of messages in it.

Let's take an example of each.

Single-Purpose, Single-Flow

The classic case of a simple (but not necessarily small) single-flow bot is a traditional marketing sequence. In this type of bot, your users opt-in to hear your pitch, and over a series of hours or days your bot drip-feeds them messages that all lead towards some conversion goal, whether that goal is attending a webinar, buying your course, etc. 

This type of conversation isn't really a conversation, it's a funnel, and most of your users will receive most of the messages in the sequence (unless they bounce) and can easily be modeled in a single flow, even if that single flow is quite long and involves a variety of sophisticated elements such as integrations with CRM systems, Google Sheets, or even involves other messaging channels such as SMS or e-mail to engage your users.

Even if you have some light branching, you may still get away with a single-flow bot. For example, in the marketing sequence example, your bot may choose to send different messages if a user was a previous customer, or might collect different information from different users based on other data collected as part of the sequence. 

Still, you shouldn't be afraid to introduce multiple flows - if at any point you start to feel like the filtering and branching is getting cumbersome, it's time to split your single flow into two or more.

Single-Purpose, Multi-Flow

If your conversation design has a lot of branching you will almost certainly want to utilize multiple flows to implement your bot. This is because each major branch of your flow represents a mini-sequence, and it will be easier to think about and maintain your bot's logic if those sequences are self-contained and not one huge flow with a maze of filters everywhere. This kind of flow is built by using one flow to trigger another flow at specific points in the conversation. We have a walkthrough with samples and a video in this article.

An example of a single-purpose, multi-flow bot is a bot that assists your customers in making a decision, such as which of your products will best meet their needs.

You may need to ask a series of questions to determine the appropriate product or service  category, and then for each category ask an additional set of questions specific to that category to determine the specific product to recommend. Maybe it goes even further, and each product requires a series of messages and questions to demonstrate the value of that product to the customer in order to make a sale.

In a case like this, you should split the various branches of your conversation flow into individual flows and connect them via flow trigger actions.

Another reason you may need to split a larger logical flow into pieces is if you have parts of your bot that should be run in different scenarios. For example, you will probably have a 'Human Handover' segment of your bot that gathers some context from the user and starts a conversation with a live agent (this does not necessarily mean real-time chat, although it can mean that). 

You may want to be able to activate the human handover sequence from several places that a user might get stuck, and the best way to do that without a lot of repetition is to split the handover sequence into its own flow, and call it as needed from appropriate places within your conversation.

Multi-Purpose Bots

If you are building a multi-purpose bot, i.e. a bot that will be able to accomplish a variety of tasks for its users, even if it is a small variety of tasks, you will definitely want to split your bot into multiple flows. 

Unless your bot is purely language driven then your bot will present some kind of a 'main menu' to your users, certainly upon their first interaction, and frequently at the close of each task the bot performs (for example, if the bot answers a FAQ, in many cases it may re-display the main menu after providing the answer to the FAQ question).

There are really four main patterns we see used to create a main menu system for multi-purpose bots

  1. Creating a 'main menu' flow that presents the menu options and delegates the implementation of those functions to additional flows.
  2. Letting Flow XO construct the main menu automatically by specifying a Welcome Message for your bot and NOT having any flows with an un-filtered catch-all trigger. When Flow XO constructs the default welcome message, which it will show if no more specific flow is found to handle any given message, including the special 'start' message, it will create a shortcut button for every flow that has a New Message trigger to present along with the welcome message. Any given flow can opt-out of having it's New Message trigger participate in this process with a setting on the trigger.
  3. Pure Natural Language Processing (NLP) "menu". If you are using Dialogflow or to make a purely language-driven interface into your bot, i.e. you do not present pre-defined tasks but let users type what they want from the bot and the NLP/AI engine figures out their intent and responds accordingly, your 'menu' will be more of a prompt than a menu, something like 'Ask me anything. You might try asking questions like "What is your pricing" or "I need to cancel an order"' 

    Even here, however, the prompt may contain a few buttons for the most frequently used tasks even though your NLP model can identify when a user asks for that task using natural language purely for convenience or to give users a place to start. Even if there are no initial shortcut buttons, you will want to repeat the prompt from time to time, perhaps every time the bot fulfils an intent.

    In this case, you can still use either menu pattern #1 or #2 freely.
  4. Create a menu at the beginning of a single-flow bot, and use looping (via Label and Go To Label tasks OR by the flow re-triggering itself) to restart the flow once it has finished a task. We recommend against this approach specifically, and attempting to use a single-flow pattern with multi-purpose bots in general, and so will not discuss this pattern further.

Pros/Cons of each style

Of the two recommend approaches to creating a main menu, which you choose is a matter of preference.

Menu Flow
The 'menu flow' pattern is the most flexible. It can include initial tasks to gather basic information about the user, such as their language or their contact information, and store that information in use attributes so those questions only get asked once. This method also allows a greater deal of control over the shortcut buttons.

Automatic Menu
This pattern, has the advantage that it takes very little effort to create, and doesn't cost an extra interaction to display the main menu and delegate to the specific 'task' flow. The downside is you have much less control over the menu, including the order of the shortcuts.

Still, this is a perfectly viable option if your bot volume is very high and you want to minimize interactions or you just want to give the users all available options and don't really care how the menu is constructed.

If you are building an internal set of 'utility' flows to help staff complete processes, for example, this method can be an ideal choice.

NLP  "Menu"
Even if you are building a pure NLP bot, you will need a prompt. This can follow either of the above styles, with the same set of tradeoffs/benefits. In this case, however, the 'Automatic Menu' is more attractive, because your bot isn't relying on the careful presentation of options to direct the bot what to do.

Your user's first interaction with your bot

The first time a user interacts with your bot, a special 'start' message is sent to Flow XO for Facebook Messenger, Telegram and the Web Messenger. 

Facebook Messenger: start is sent when the user taps or clicks 'Get Started' on your page
Telegram: /start is sent when the user taps or clicks 'start bot' or 'restart bot' in Telegram
Web: start is sent when the user opens the chat window for the first time, or clicks 'reset' on the chat widget
SMS: There is no start message for Twilio SMS
Slack: There is no start message for Slack

You can take advantage of this fact in your trigger filters (or anywhere else in your flow) to respond differently to users who are interacting with your bot for the first time. A common usage of this start message is to define a flow with a New Message trigger that matches either 'start' or '/start' and welcomes first-time users to the bot.

After the initial 'start' message, the only messages Flow XO will receive are ones directly sent by your end-users in their chat windows. When testing, it is often convenient to reset the conversation in your messenger and simulate first-time use of your chatbot.

At any time, however, if you want to see how your bot will respond to a first time user, in the test console (or any of the platform Messenger applications) you can simply type 'start' (or '/start') and the result will be the same as if you were interacting with your bot for the first time.

Flow Building Blocks - Trigger s & Actions

As discussed, the brains of your Flow XO chatbots are made out of flows, and flows are sequences of actions (kicked off by a trigger). Flow XO offers a wide variety of actions. There are the obvious ones, that let you send messages, images, etc. There are also more advanced actions that can help you make your bots more sophisticated - such as actions that allow you to accept payments, integrate with other systems using REST, create time-delayed sequences and much more.

You can read about all the different types of actions and what they do here.
You can read about different triggers and their outputs here.

The Message Lifecycle

When building flows in Flow XO, it's important that you understand what happens when a message is received from a user. When Flow XO receives a message from a user, it follows the following procedure:

  1. Check to see if there is a flow waiting on a response from this user.
    This will happen if the previous action was an Ask a Question or a Wait for a Response task. If there IS a flow waiting on a response, the message will be processed as a reply and advance the flow to the next action. (No interaction is charged to your account for this message). Message processing will stop.
  2. Check to see if there are any 'New Message' triggers in your account that expect a keyword phrase that matches the message.
    When you set up a 'New Message' trigger, you have to specify one or more keyword phrases that the trigger should match. If the message matches any 'New Message' triggers, If any of the triggers have filters defined, the filters will be evaluated and any triggers whose filters succeed will be fired and flows will start for each of these triggers. (One interaction per non-filtered matching New Message trigger will be charged to your account). Message processing will stop.
  3. Check to see if there are any 'Intent Detection' triggers in your account.
    NOTE: Unless you are using our Dialogflow or integrations, you can ignore Intent Detection triggers.
    Intent Detection triggers are a special kind of trigger used by our Natural Language Processing (NLP) integrations. If you create a flow with a trigger from our Dialogflow or integrations, these will be intent detection triggers. The incoming message is sent to the appropriate NLP engine for each of this type of trigger. Once the intent is returned from the NLP engine, any filters associated with the triggers are evaluated. A flow will be started for any trigger that has no filters or the filters pass. (One interaction per non-filtered matching Intent Detection trigger will be charged to your account). Messaging processing will stop.
  4. Check to see if there are any 'Catch-All' triggers defined in your account
    Catch-All triggers, as the name implies, will be run for any message that isn't handled by one of the trigger checks above. As with all triggers, only catch-all triggers that pass any filters defined on the trigger will be fired. (One interaction per non-filtered Catch-All trigger will be charged to your account). Unless the 'Send welcome message even if a catch-all trigger is found' setting is configured on the current bot definition, message processing will stop.
  5. Check to see if there is a Welcome Message defined for the current bot
    When you set up a bot (a connection to a messaging platform) you have the option to configure a 'Welcome Message'. If the current bot has a Welcome Message defined, it will now be sent to the user.

If none of the above steps result in a trigger firing or the Welcome Message being sent, the message will be logged as unhandled and the user will not get any response.

Message Lifecycle

When Things Go Wrong - Errors & Error Handling

Inevitably, at some point, your flows will experience some errors. Part of building a high quality bot is planning for this in advance. Flow XO provides some tools that can help you manage errors as gracefully and professionally as possible. Please read all about Flow XO's error notification & management tools here:

Using Outputs

Most triggers and actions give outputs. An output is some data that can be used in subsequent actions or in filters.

For example, the New Message trigger has a Message output, which contains the full text of the message that is received. You can then use this output with a webhook action to post the message to another app, or use it as a filter so that an action is ignored if the message contains a certain word.

To use an output in an input field (when setting up an action), either type {{ or click the Flow XO icon inside the input field. You'll then see all the outputs available to you.

By linking your trigger/actions with outputs, and using filters to add logic, you can create complex behaviours without needing to use any code.

Other Actions & Integrations

As well as our core services, we have over 90 other services and integrations you can use in your flows, such as for sending email, manipulating spreadsheets, and fetching data from your CRM.

See our full list of integrations

Digging Deeper

There are also some other important core services for building bot flows:

  • Attributes: Store details about your bot users that you can retrieve again later. 
  • Messaging: Receive and reply to messages from your bot users.
  • Code: Execute custom JavaScript and output the result.
  • Webhook & HTTP: Get data from or post data to, external API's.
  • Flow: Control flows, such as going back/forward (goto), or triggering other flows.

Let us know how we can improve Flow XO (or this documentation) by sending an email to

Still need help? Contact Us Contact Us