How I Design AND BUILD Chatbots with Vulcan
A couple of years ago, I wrote an article here for Chatbot Magazine about how I designed chatbots, and inherently “conversations”, using a visual collaboration and white-boarding tool called Mural.
I wrote this article at a time when I was building Facebook Messenger bots, using a node.js application and callbacks to the Messenger platform, alongside integration with API.ai (now Dialogue Flow) for the Natural Language Understanding.
In this case I was building a bot that had a number of different skills, that was able to connect to and integrate with a handful of web services & APIs through which the Bot could complete actions.
When you’re writing your Bot logic in code form, whilst being ultimately the most flexible way to achieve advanced functionality, it becomes tricky to organise your code effectively and in particular, to manage conversational concepts such as Context.
It’s also difficult when you consider that the code implementation of the chatbot is normally the last piece of the conversation design challenge. Conversational design requires collaboration and input from across the business and therefore collaboration with people with differing levels of technical skill and technical competence is a challenge and can easily become a barrier to progress.
I developed a “design process” out of necessity. It was iterative and experimental and I used Mural as the best tool to achieve the visualisation of the conversational flows that made technical sense, whilst collaborating with other team members from across the business and project team.
This methodology served us well for a while, with Mural and the Node.js app working in parallel.
But over time, we would discover areas that things didn’t work as effectively as we needed.
Firstly, maintaining the discipline of parallel tools is a challenge. It’s all too easy, as the developer, to shortcut the design process when the flow is (in your mind at least) simple and well known. I often found myself “just quickly” adding a new intent, new message sends and new API methods because well, I could. But later it would always hurt when other members of the team wanted to improve upon the language or the flow, since it wasn’t documented aside from being “in the code”.
Since the Mural acts as a form of living, collaborative documentation of the Conversation Flow Map, the disconnect of having flows existing only in code form serves to alienate the team from owning the content, language and tone of voice, especially when the developer has decided the conversational language, that may not be in-keeping with the Persona of the Chatbot.
Developer disengagement is also an issue. At the end of the day, building 90% of what the bot does is fairly trivial. It’s simply message handling. We receive a request, we parse it, call some methods and wait for the next response.
API integrations with third party services tend to be fairly simplistic. We define libraries of method calls, hopefully organised in some sensible structure to organise the Bot’s skills.
At the end of the day though, there’s not enough here to really engage a talented developer long term.
The app becomes unloved and maintenance drops. Bot platforms are still very new, their APIs change regularly and therefore the Bot breaks, sooner rather than later when your app isn’t maintained.
There are areas where highly technical skills can be put to great use, in the context of Bot building. These tend to exist in the areas of data querying, statistics and data analysis, data visualisation, machine learning and building specific micro-services that enhance and enrich the Bot’s skills and capabilities.
Creating these additional micro-services that become the Bot Superpowers, is where developer’s time and energy is best spent. These services FEED our Bot.
So, over time, we found that Mural was not the optimal tool for us (though I still use it daily for all sorts of other creative reasons), we needed a better solution that served to bridge the gap between collaborative conversational design and the implementation, without restrictions on the opportunities for advanced technical developments in the user interface or underlying micro-services that would serve as skills for the Bot.
So, we applied that experience and knowledge to developing a new tool — Vulcan.
Vulcan is a powerful visual tool. In much the same way as with our previous Mural example, I can quickly sketch and iterate ideas for conversational flows.
Overview of How Vulcan Works
Vulcan Projects
All of your work in Vulcan is organised into PROJECTS. Each project can have multiple team members that can access your CHARTS. Charts contain all of your conversational FLOWS. Flows are connected using the various Chat Module COMPONENTS that we’ve provided you to power your conversations.
Vulcan Charts
A simple Chatbot could easily fit into as single Chart, as you layout your Flows. As your Project grows, you will inevitably need to organise your Flows. How (and when) you do this is very much up to you, but between the components we provide and the Chart-to-Chart structure, you have the tools to organise your Project as it suits you in a very flexible and scalable way.
Vulcan Flows
A Flow is a series of connected Components that create a conversational journey, involving messages from both our Bot(s) and the User, to create a dialogue — a two-way exchange. Flows could be short and consist of a single Bot message and a User response. They can also be vast and complex, with multiple conditional pathways, joined up Flows and interconnected Charts. Finding the right balance is again, up to you — but Flow structure and size is an important factor in conversation design that you need to keep in mind.
Vulcan Components
Now we get into the nitty-gritty. The details of our Flows are determined by how we use Components and the relationships between them, which we call Connections.
Component Picker
Click the + button or dbl-click anywhere in the chart and you’ll first create a Component Picker instance. This is effectively a menu or library of the available components (we’ll talk about each of them next).
The Component Picker is separated into modules, mostly for organisation reasons. You can see we have two tabs currently, “Chatbot” and “Analysis Tools”, which are the first two core-modules we’ve brought to Vulcan so far.
A quick look at the Analysis Tools options…
General Notes
One of the most useful Components is one that isn’t actually used to build our conversations, not exactly.
General Notes is, as the name suggests, a component that holds notes — text, images, links to research articles and even dynamic content, such as twitter feeds, youtube videos and reddit topics. Notes are great for sketching out new ideas, placeholders for other components, contextually relevant background information or documentation relating to your conversation design.
Person & Organisation
These Components are very similar to Notes, except they are visually slightly different and are supposed to represent either people or companies, kind of like an address book.
The address book concept is neat, since these objects can also be Symbolised, in that once created, you can add instances of them to different Charts and even different Projects, without needing to replicate them each time.
And now, on to the Bot Module… we’ll start with the two types of Components that are needed to conduct a conversation.
User Message
The User Message represents the output display of the User input. This is optional, but works well in chat apps to show a timeline of messages.
The standard User message is only text, though I’ll show you shortly how we can represent richer media messages.
User messages have access to the State Machine and can display data from here into the template, using {{ }} syntax.
Bot Message
The Bot Message is a component that, you guessed it, represents our Bot.
This is a particularly rich component. It includes a Text Message section, whereby you can define your message and any number of variants of that message — so as to provide some variety.
You can also, optionally, present a control, such as this Radio List. Other options include Video, Image, Checkbox List, Map or your own custom controls, which we’ll discover later.
The Bot that sends the message is inherited from the Chatbot Entry component, which we will take a look at now.
Chatbot Entry
This is a very simple but useful component. It declares an entry point to a Flow.
A couple of the most powerful aspects of this component are that
a) it makes for a great way to jump-in to any part of your Chatbot design very easily, using the Entry ID — incredibly useful for development, testing and debugging, so you don’t have to constantly go through the step-by-step back-and-forth chat to get to the point that you need and
b) This is where we declare which Bot persona is handling the next part of the conversation. So, it’s very simple to change Bot personas and have different Bot agents owning different flows.
Router
In the same way that we use the Chatbot Entry as a gateway to a new flow, a Router component is generally used a jump-off point.
The Router is designed to enable us to connect different Flows, whereby you could navigate to a selected Chatbot Entry point.
The Router is also quite powerful, in that it also possesses some additional options.
‘Continue to Parent Flow’ is very useful when you temporarily navigate to a Flow and then want to rejoin the original source flow once it is completed.
‘Send Bot Message’ can trigger any of your existing Bot messages from anywhere in your Flows.
‘Emit Signal’ can pass some temporary state information to the next part of the Flow.
‘Submit on Server’ is normally an action tasked with sending some data to a pre-determined API endpoint for storage in the backend database.
‘Open Gallery’ will trigger the opening of the filepicker or mobile photo gallery feature (native).
‘Open Camera’ will trigger the opening of the webcam or mobile camera feature (native).
‘Open Page’ will open a web page to the target URL in the web browser.
Filter
The Filter component enables us to add conditional logic to our Flows.
It has access to the State Machine (more on this to later) which it can use to construct and execute simple expressions, that will determine how our conversation will flow.
It also has a little IntelliSense-style auto-suggest feature to let you know what variables are held in state that you can use, as well as some validation to check your expression is valid — notice how the input turns from red to white when I complete the expression.
Endpoint
If you didn’t think that everything that came before was exciting, then (aside me not believing you… 😆) let’s get into the really fun stuff.
The Endpoint component is essentially a REST client, enabling us to integrate with any REST API’s. We can handle the responses and put the data we receive into our State Machine.
In your Project Settings, you can define your endpoint request templates.
These requests are then available to instances of your Endpoint components inside your Flows.
There’s a lot that we can do with the Endpoint component and how the data we receive gets managed in the State Machine, so we’ll save that for a deep dive another day.
Dialogue Flow
Up until now, we’ve essentially been working with examples that are based on managing the state and variables provided through what are essentially “Quick Replies” (in Facebook Messenger parlance) — pre-defined User input options in the form of buttons, checklists and radio buttons. The Dialogue Flow component gives us the power of handling free-text natural language input from the User.
We can store the DialogueFlow response in our signal to the next step of the flow or pluck specific fields from the DialogueFlow response and store them in our State Machine Model.
Render Template
Render Template component provides access to our library of templated Components.
For more advanced Components or to customise the style or functionality existing Components (if you know a little Vue.js), you can use the Custom Component builder.
Components that you build can be saved and reused from your Components Library and instances further modified using the component props.
State Machine
The Vulcan State Machine provides a flexible way to manage the state of our conversation. The context, or Scope of a conversation is closely tied to the current State, a critical piece of information that we discussed in my first article, and provides the tools we need for building awareness and relevancy into the conversation.
In addition to Context, we have access to broader data sets, including Entities and variables that we can set and fetch on the fly as the conversation naturally progresses.
By default, we have the following data structure available to us.
"scope": {
"signal": {},
"Model": {}
}Signal data has a short lifespan, typically it is killed off after next iteration in the Flow.
If you want your data to persist longer, you can store it in the Model.
"scope": {
"signal": {
"user": { "name" : "Steve" }
},
"Model": {}
}You can access your data in Condition fields, Filter components — there’s lots of opportunities to apply simple and complex logic to your Bot from within Vulcan and without the need for much coding knowledge.
To access the data inside your scope you can use dot syntax. For example
signal.user.name == "Steve"
Conversation Preview
Vulcan provides a built-in Conversation Preview tool.
You can define the Entry point that you want to start from, as I’ve done in the sample above — very useful for testing and debugging as you can avoid going through the same repetitive steps in order to get to the exact part of the Flow you are working on.
In addition, you can provide initial signal and Model data, that may mimic the real data that would be obtained in the real-world production environment.
Not only do we build up our state machine as the conversation progresses, but we can also set an initial state. So, if you have contextually relevant information about the User that could be derived from your own database, for example, you can pre-load the state machine with information about the User, such as their name, email address or a session token.
Here’s an example:
In this flow, I want to skip over the introduction and name exchange part, if I already know the user’s name, which may already be provided by the the website or app that the Bot is running on. When testing, all I need to do is pass this state information to the Model, when I run the Bot.
Pro Tip:
It might also be useful to know the context of where your User has come from. You can parse the source URL of the referring site and set this in initial state to further personalise the flows and demonstrate awareness — just be careful not to overstep the creepy line here.
const cameFrom = document.referrer ? (new URL(document.referrer)).hostname : null;// handle it through entry pointsif (cameFrom == "techcrunch.com") {
new Chatbot({id: '<entry_point_for_techcrunch>'})
} else {
new Chatbot({id: '<entry_point_for_anyone_else>'})
}// or alternatively, handle it through filtersnew Chatbot({
id: '<general_entry_point>',
Model: {cameFrom: cameFrom}
})
Chat Widget
Alright, so with all of that — what’s the point? Well the point is to bring all of this to life by enabling rich conversations with your audience, your customers, visitors to your website, new leads.
With Vulcan’s simple embeddable Javascript widget, you can enable a familiar chat pop up.
<script src=”http://developers.beach.io/chatbot.js"></script>var chatbot = new Chatbot({
id: "",
signal: {},
Model: {},
endpointServer: “http://developers.beach.io”,
styles: {}
})chatbot.run()
You can customise the widget to suit the colour scheme of your site, using the simple configuration interface.
You can bring your conversation to life in your website, web applications and soon your native mobile apps with our mobile SDKs.
We will also be enabling integration with the leading messaging and Voice app platforms, such as Google Assistant, Alexa, Messenger, Telegram, Slack.
— — — — — — — — — — — — — — — — — — — — — — — — — — — — — — —
So today, this is how I both Design and BUILD Chatbots at Beach, using a tool we’ve developed based on our own experiences in conversation design and development.
The Vulcan app is not quite ready for public use, but we’d love to have some keen early beta testers to give it a try and help us refine the product for release early next year. If that’s of interest to you, get in touch via our Slack group
Steve is the Founder of Beach.io, a startup that builds beautiful software tools to make complex tasks easier.
