Implementing human takeover in Flow XO

John Jackson
Feb 12, 2017 · 8 min read

Important Note: This article will remain live for archive purposes, but note that Flow XO now has a full live chat feature, which should be used instead of the methods described here.

A lot of bots built on Flow XO need to be able to escalate a conversation to a real human when needed. Our users tend to be building serious bots to solve real customer service and marketing needs, and customers are increasingly replacing live chat with our web messenger. So an option to open a direct line of communication with sales/support is vital.

Messaging in Flow XO

Our messaging service is built for exactly this purpose. It makes it easy to route any message to an email address or helpdesk (such as Freshdesk, Help Scout or Zendesk). Once the message hits email/helpdesk, replying to the user via the bot is as simple as replying to the email or helpdesk ticket just as you would any other email.

It enables chat with bot users to blend in seamlessly with other channels. You don’t need to get your sales/support team to login to yet another inbox, and you can use all the same workflows, templates, and other tools you use for email. It’s great!

Read on to find out how to use this brilliant feature to build a human takeover mode for your bot…

Building blocks

The beauty of Flow XO is that you get the building blocks to build any business messaging application you need. There is pretty much no limit to what you can do. If you can dream it, you can build it.

Sometimes though, you need a little inspiration. That’s where our template flows come in. You can install them and get up and running with popular business messaging functionality in minutes.

Our Message a Human template has been around a while now, and shows you how to offer your users a way to send one-off messages via a bot.

But users have been asking us how to implement a ‘human takeover mode’, where the bot’s normal functions are suspended and all messages are routed back and forth between the bot user and a human, until the user ends the chat. So here we’ll explain how to do this with a Human Takeover flow.

You can install the shared flow now and start using it right away. Read on to learn how it works, step by step. There’s a lot you can learn about Flow XO by understanding it.

How human takeover works in Flow XO

The idea is that we use an attribute (named ‘human_takeover’) to flag whether the user is chatting to a human or not.

The phrase ‘start chat’ will set the human_takeover attribute to yes, with the phrase ‘end chat’ clearing it.

Finally, we need to route messages to our human takeover flow when this flag is set. We do this by adding a Trigger a Flow action as the first action in every other flow you have. This action needs a filter to make sure it only runs when the flag is set, and we tick the option to stop the rest of the flow. The effect is to divert the flow to human takeover when the flag is set.

If this seems a little complicated, don’t worry. It will all make sense as we walk through it in more detail now.

Our main flow

The main flow actually has 3 purposes:

  1. Allow the user to start a chat.
  2. Allow the user to end the chat.
  3. To receive a message that is meant for a human.

Once you’ve installed it, you’ll see that the flow has a New Message trigger that listens for 2 groups of phrases ([start] and [end]), and the phrase ‘takeover message’:

By using groups (in [square brackets] after a word/phrase), you can filter on the group instead of the word/phrase itself. No matter what phrase is used, or even slight variations of it, the group will always be exactly as you define it.

The phrase ‘takeover message’ is not meant for the user of the bot, it’s what we’ll use to call this flow from our other flows.

Now onto the actions within the flow. The first action is a Goto a Label action named Go to takeover. You’ll notice that further down the flow we’ve added a label (takeover) to define the start of the actions that handle receiving a human takeover message.

This action simply jumps down to that section, only if the flow is triggered with the phrase ‘takeover message’.

Starting and stopping human takeover

Our next 2 actions (Set human_takeover and Confirm start) will run only when the user has said ‘start chat’ and human takeover mode is not currently set. The actions set the attribute ‘human_takeover’ to ‘yes’ and tell the user that they can now send their message.

Because we’ve ticked the ‘stop rest of flow’ option on the filter step, the flow ends here once we’ve run these 2 actions.

Our next 2 actions (Delete human_takeover and Confirm end) work in a similar way but handle the ‘end chat’ scenario. This time we unset the attribute, tell the user, and end the flow.

The actions Tried to start again and Tried to end but not started give the user a friendly heads up if they try to start a chat if already in human takeover mode, or try to end a chat if there isn’t one to end.

Receiving a message

You’ll remember a moment ago I said that if the flow is triggered with the message ‘takeover message’, we jump down to the takeover label.

The message ‘takeover message’ will be triggered by other flows which send the message the user sent as metadata (more on this later).

Here are the actions we’re talking about now:

So the first action (Tell user message will be sent in 1 minute) is an informational message to the user, to acknowledge their message.

Straight after that, we use the Wait Service to wait for exactly 1 minute.

The idea here is that we want to give the user a short window in which to cancel human takeover mode, and stop the message being passed along. That way, if the user comes back to the bot after a few days and says ‘hello’ whilst still in human takeover, the user can exit the mode without the erroneous message being sent.

Our next action (Get human_takeover state) gets the latest setting for the ‘human_takeover’ attribute. If it changed in the last 60 seconds, we need to know.

And finally, the message itself is sent (Send to your email or helpdesk), but only if ‘human_takeover’ is still set.

Directing messages into the flow

So the flow handles ‘start chat’ and ‘end chat’ commands directly, like any other flow. But how does ‘takeover message’ get triggered?

Let’s suppose we have 3 other flows in our bot - ‘opening times’, ‘join’ and a catch-all.

Whilst we’re in human takeover mode, you may not want these flows to trigger. Instead, we need to redirect any messages into our human takeover flow.

You can do that by adding a Trigger a Flow action (Human takeover) into ‘opening times’, ‘join’ and the catch-all, that only runs if the ‘human_takeover’ attribute is set, sends across the received message in metadata, and stops the rest of the flow. In short, we’re passing control over to the human takeover flow.

The action is set up like this:

Don’t type in {{catchall.message}} directly, click the icon in the field to open the selector, and find the message output from the trigger.

And we also need to filter it so it only runs when the ‘human_takeover’ attribute is set:

You need to use the icon in the field again here, find the attributes output from the trigger, and type ‘human_takeover’ when asked for the name.

So to finish things up, make sure you add an action like this into all of your flows that you want to override when the user is in human takeover mode.

Here’s a shared flow with the action included (so you can see exactly how it’s set up):

Depending on your preference, you might choose to only redirect messages from your catch-all flow (so bot commands such as ‘opening times’ will still work but other messages go to a human), or redirect messages from all flows, so even bot commands go to a human.

Testing it out

Let’s run a test to make sure everything fits together. First we start the chat:

Now we can test a human takeover message:

And one minute later, we see the message come through to our inbox:

If you check the logs for your catch-all flow, you’ll see that the message is received by the catch-all and then sent across to your human takeover flow by the filtered action you added into it. Check the logs for the human takeover flow to see the message land there.

We can then reply to this message and it comes back to the bot:

Finally we’ll try ending the chat:

Recapping key concepts

By learning how the Human Takeover template works, you’ve also learnt how to:

  • Group words/phrases to make logic easier to implement inside flows.
  • Set attributes, and use attribute values provided with the trigger and through Get an Attribute.
  • Use Trigger a Flow and metadata to switch from one flow to another.

In fact, this flow touches on pretty much all the concepts you’ll need to know to build really powerful messaging applications in Flow XO.

Further reading

Visit the homepage to see the full list of articles we have available, including more tutorials like this.

Our community is also a great place to learn more about Flow XO.

Flow XO

Smart chatbots made simple.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store