From a thought to your first chatbot, a step-by-step tutorial

Published in

alana.cloud

17 min readApr 13, 2017

Coding and deploying a bot to Facebook messenger

This is taken from our techtalk on April 12, 2017 in NYC. The talk is part of a series of 4 that covers creating a chatbot from scratch using the alana framework on the alana.cloud bot platform.

The talk covers

What’s a chatbot
What’s the alana framework, how is is structured?
Creating a chatbot step-by-step
Deploying the bot to Facebook

If you have any questions, join us on slack. The completed bot’s code is also available on github here.

What’s a chatbot?

What is a chatbot? A chatbot is a program that conducts a conversation with a user. These are useful for automated support, shopping assistants, voice assistants, etc.

There are 4 major components to a modern chatbot.

NLP or natural language processing — understanding what the user wants to do or wants to bot to do
Flow control — maintining state of the conversation so that responses make sense
Connectivity — Connecting to at least a chat platform if not an external API (either your API or a third-party one)
Saving data — maintaining either user state (name, email, interests, previous purchases, etc) and/or app state (knowledge base, etc)

In order to help developers write chatbots, frameworks started popping up. Alana is a new framework built with the lessons learning after having used other frameworks to build successful bots for fortune 100 companies

Javascript based — easy to find devs who know javascript and easy to pick up for beginners
Opinionated — Files are expected to be in certain places and also alana handles most functionality on its own (DB storage, platform connectvity, middleware, etc) and prefers it!
Embedded NLP engine — along with an ever growing of intents built in. The intents are open-source and slowly building community involvement. Everyone bot gets smarter as the community gets smarter
Script based flow — We’ll cover this later
(Not mentioned) Test-first — Testing is a deeply integrated component of the framework
Everything is opinionated but plug-and-play
Most importantly our platform is running the publicly available open source code. This means you’ll always be able to take your code with you and run it on your own infrastructure, we even have turorials how to do it on common IaaS including Google cloud, AWS, Heroku and more.

Bot framework architectures (Click on a slide to enlarge it)

As developers gained experience writing bots and more complex bots were built, how these frameworks organized code changed to keep up.

The first architectures were event based. They were responsible for communicating with chat platforms like facebook messenger. When a message was received, an event handler would be called by the framework with the event. This would lead to a spagheti of if blocks and switch statements as the developer was responsible for maintaining all the state for each user. For some frameworks, each type of message (text, image, button click) would be handled by different handlers, meaning you could have entry points everywhere. It was a mess.

The next generation of frameworks switched to a waterfall architecture. This was moving toward the understood way web routers work, you have a route and move progresivly down the handlers until you run out of them or stop. Since there are no hyperlinks with chatbots, the developer is responsible for moving between routes. The framework is responsible for communication with chat platforms and also mainting the state of the conversation. Unlike most web server routers, waterfall chatbot frameworks keep track of which route the user is in and which handler was last used and resume from there.

Alana is a refinement of the waterfall architecture. If we may, a 3rd generation. It takes the responsibility for not only platform communication and maintaining conversation state but also for transitioning between states. This means the developer can now just desribe how to respond to specific user actions and the framework handles calling the right handler. Handlers can be much more specific, handling only a specific text input or button click making them much easier to write, understand, and debug.

Difference between waterfall and script style. Left side is MS Bot Framework and right is Alana

Here is an example of a profile route (or script in alana’s terminology). On the left is a traditonal waterfall style using MS Bot Framework. On the right is the same code using the alana framework.

Notice how the script style is much better at self describing the code. Instead of using an array as the chaining technique, alana chains the dialogs(handlers). Alana also allows the developer to specify how they want that dialog to be triggered for explicitly pushing more responsiblity onto the framework and away from the developer’s code.

In this example, the developer sets up 2expect blocks to tell the framework to pause the bot and expect some user input. The first expect block is completely generic, it will take any input from the user, this is exactly how traditional waterfall handlers work. Then there is a secondexpect block, where the developer sets up specific handlers. We can see that the bot sends 3 buttons to the user allowing them to choose a topic that interests them. Each button has it’s own handler that is is only called if that button is clicked. We also have a special catch handler that catches any other input, if the user entered text for example. With the waterfall architecture, handling the different types and specific buttons must be handled by the developer each time, alana takes that responsibility from you.

Two ideas you need to understand, scripts and dialogs

There are 2 major ideas in alana’s world. The first is a script, which represents a “route” and is made up of a 1 or more dialogs. The second is a dialog.

Scripts are conversations, for example

a profile script could guide the user through entering their name, email and age
a trivia script could quiz the user from a set of questions and loop endlessly

The second concept is a dialog. It is simply a block of code (a dialog handler) that is called based on conditions.

There are multiple types of dialogs:

dialog — general case, will always be called. Will automatically call the next dialog when it is finished
button —if incoming message is a button click, call handler
intent — if incoming message has a recognized intent, call handler. We’ll cover intents later.
text — if incoming message is a text message, call handler
match — if incoming message is a text message and matches a regex, call handler
expect — pauses flow to wait for user input. Can then chain multiple dialogs including a special catch type to create a smart tree, only one dialog will be called in the block

Every block takes a dialog function. Also see how the cloud IDE gived code hints 😀

A dialog handler is simply a function with two inputs

session
response

The session argument holds all information about the user and incoming messages.

The response argument allows the bot to respond to the user in multiple ways. All the response are normalized by the platform connectors. You just send a text message, and the platform middleware is responsible for generating the correct type message to the platform.

This is how the general flow of the alana framework. An incoming message is represented by the arrow coming in on the left.

The first decision is checking if the user is already in the middle of a script. If they are then the correct dialog handler is called.
If they are not then see if they are a new user.
If they are a new user then run a special greeting dialog (covered later). This dialog is only called once per user when they first connect or interact with the bot. This is best for on-boarding tasks.
If they are not a new user then run the default script, usually the main menu. The default script can then provide ways for the user to run other scripts, a set of buttons for example.

Making spacebot

We’ll be using the alana.cloud online platform to create the bot. We could do it locally on the machine but for ease of setup for everyone this is easier.

Go to https://alana.cloud and sign up for a new account using the button on the top right.
On the bottom right of the logged in page you’ll see a (+) button to create a new bot. Click it.
Select an amazing name for your bot and select the empty dialog.
Click “create bot” on the bottom.
When the bot is ready click on it to edit it.

You’ll be taken to the editor page first. There are three major panes to the editor

Left — File list. Since alana is opnionated all script files must be in scripts directory and all tests are in tests directory. How you organize scripts is up to you, have all scripts in one file or each in a seperate is up to you, it doesn’t matter.
Middle — Editor. This is where you’ll enter code. It includes code hints, code snippets and some other goodies you would expect from a modern editor.
Right — Info pane. There are four major views including documentation, integrated test results, live chat (and logging), and a list of built-in intents.

We’ll be making spacebot, a bot all about space

Today’s project we’ll be making “spacebot” a bot that loves to talk about space. There will 4 major scripts we’ll write and a new-user on-boarding greeting.

The greeting will welcome the user to the bot and transition the user to creating a profile
The user profile script will ask the user some biographical information. We’ll use this to demonstrate basic input/out of the bot and switching between scripts.
A default script will provide a menu that allows the choice of trivia game, today’s space photo, or a random space fact. We’ll use this to demonstrate more complex input/output and error handling.
The trivia script will give the user a question and a choice of answers. They choose one and we let them know if they are right or wrong. They can then ask a for a new question or go back to the main menu. This will demonstrate how to loop a script and more script fundamentals.
The photo of the day (POTD) script will request today’s photo of the day from NASA and send it to the user. This will demonstrate how to contact third party APIs.

We’ll work on adding a greeting to the bot first. Remember, a greeting is a special dialog that is called once and only once when the user first interacts with the bot.

Create a new file inside the scripts directory, naming it something similar to “greeting.js”.
Most commands with alana are globally referenced as only 1 bot at a time can be created and it cuts down on reptetitive typing of bot.command. We’ll use the function addGreeting((user: User, response: Response) => void) to add a greeting to the bot. Let’s also add a console.log so that we can see that your code runs in a normal node.js sandbox and experience the joy of real-time logging.
Type the following code (so you can see the code hints at work)

Click “Save all”. This will save your code, compile it and create a new version.
Watch the chat window for a notification that you are using a new version, for example “Using version 2”. When a new version is made your current user’s state is not modified, most of the time you’ll be making small changes to your bot and don’t want to reset the user. However, this time we do as we want to run the greeting again.
Click the hamburger menu and choose “new user”. This will create a new user so you can go through the greeting dialog.
You should see logs about the on the bottom right. Feel free to click on one and get more information.
Great, you see the greeting but nothing else happens, let’s get some information from the user.
Add response.startScript('profile'); to the end of your greeting handler. That this will do is start a new script called “profile” after the 2 text messages are sent. Your code should look like below:

Let’s ask about & save some information about the user

Next we’ll add a user profile. We’ll create a new script using the newScript(name?: string): Script function. If we call it a string then we’ll create a “named script” that can be called from anywhere. If we don’t have any arguments then we create a default script that is the base state of the bot. All scripts automatically transition to the default script when they complete.

Create a new file again called something like “profile.js”
Enter the following code

There are two dialogs here, a regular dialog and an expect dialog. The first dialog simple sends a text message to the user asking for their name.

When the framework hits the expect block it will pause the bot and wait for user input, for example typing something or clicking a button. Here we tell the expect block to call our handler only if it recieves a text input (since we haven’t sent any buttons yet they couldn’t send anything else anyway).

In the handler we grab the text of the user message session.message.text and store it into the user’s state session.user.state.name . The framework is responsible for storing and retrieving the user object from a DB, different DB middleware. Then we echo it back to the user.

Let’s try it out!

Click “Save all”. This will save your code, compile it and create a new version.
Watch the chat window for a notification that you are using a new version, for example “Using version 3”.
Click the hamburger menu and choose “new user”. This will create a new user so you can go through the greeting dialog and profile.

So now we know who the user is but lets give them a main menu.

Open the main.js file and delete all the contents
Write the following code

This time we create a default script by not including a string. This means that all other scripts will automatically start this script when they end.
We start by creating a button object using response.createButtons()
We can add a text banner and buttons to the button message. There are two types of buttons 'postback' and 'url' . Postback buttons return a certain payload to the bot when they are clicked and url buttons open a new tab with a specific url. We’ll send 2 postback buttons with different payloads representing what script to start. addButton(type, button_text, payload_or_url) takes 3 arguments, the buttons type, the text of the button and the payload to return or the url to open. At the end of the chain we need to call a send() to send the button message to the user.
We want to pause execution after we send the menu and let the user choose an option. This is done by adding an expect block. In the block we add 2 button handlers, each with a specific payload they require.

Let’s try it out!

Click “Save all”. This will save your code, compile it and create a new version.
Watch the chat window for a notification that you are using a new version, for example “Using version 4”.
Click the hamburger menu and choose “new user”. This will create a new user so you can go through the greeting dialog, profile and hit the main menu.

We should notice two behaviors if we play around with the bot. First, if we click a button, nothing happens. This makes sense, we haven’t create the POTD or TRIVIA scripts yet so there’s nothing to start. However, shouldn’t we show the main menu then? Second, if the user types anything to the bot, nothing happens again.

Let’s fix the second one now. For that we’ll introduce a new idea, the “named dialog”. This means that we add a string argument before the handler. Once we have named a dialog we can now call it from anywhere in the script and go directly to it. Let’s call the first dialog start and add a new handler to the expect. In the text handler we will chastise the user for not clicking a button and goto the dialog named start, showing the user the menu again.

Let’s try it out!

Click “Save all”. This will save your code, compile it and create a new version.
Watch the chat window for a notification that you are using a new version, for example “Using version 5”.
Now type something and chastise yourself for not clicking.

Next up we’ll complete the photo of the day. We’ll NASA’s awesome API to grab today’s photo.

Let’s create a new script and call it POTD and a dialog to the script. Alana comes with request-promise available under the global request . We’ll craft a request to the API (yes you can use ‘DEMO_KEY’) then we’ll use promises to get the response and
It’s smart to add a delay to the promise so that we give the user some time to marvel at the galaxy before we send them the main menu. (Also it helps reiterate this is all real JS)

Let’s try it out!

Click “Save all”. This will save your code, compile it and create a new version.
Watch the chat window for a notification that you are using a new version, for example “Using version…”.
Click Photo of the day

Homework is to also add an error handler to the request promise!

The next script we’ll add is a small trivia game. You’ve now seen most of the components needed to make the game work. Here’s how the script will work:

On script start, pick a random question from the list of questions
Create a button message with the question and a button for each right and wrong answer.
Wait for the user to pick one
Tell the user if they are correct
Ask if they want another question. If they do go back to the beginning of the script. If they do not then end the script and go back to the main menu (automatically done on response.endScript() )

Some new things to focus on

Two named scripts so we can loop to around
The first expect has a generic button handler since we don’t know what payload we will be getting back. We then look at the message’s payload property to see if the user clicked the right button
Intents! We allow the user to type in yes or no instead of forcing them to click a button. Intents automaticlly run NLP on the user’s message to figure what they intend to do. Intents are organized into domains and sub-actions. Here we are using two actions from the general domain, yes and no. For example yes matches “yes”, “ya”, “yep”, etc. You can see a list of built-in intents in the right pane by clicking intents.
Catch dialog. What if they user types “abcdefg”? Neither of the intents nor the button handlers will be called so that catch handler is called and the user is sent the menu again. This also works if the user clicks the main menu while they are here as they payload will not match with the 2 handlers.

Deploying spacebot to FB Messenger

After we’re sure that the bot works locally on the chat let’s deploy it to Facebook.

Go to https://developers.facebook.com and create a new app.
Click on “Add product” on the left menu and then find the messenger section.
Click “Get Started”

Create a new page and get an access token

We’ll generate an access token so that alana.cloud can talk to facebook and specifically your users of your page.

If you don’t have a page use the “Create a new page” button to make one. Now select the page (refresh if you don’t see your new page) from the drop down and you’ll get an access token. Click it to copy the access token.

Go back to alana.cloud and open the platform section (it’s on the top bar).

Click the (+) button on the bottom right to add a new platform
Select Facebook and paste your access token
Click “Add Facebook”
You should see facebook added as a platform

Now it’s time to connect Facebook to your bot.

Go back to developers.facebook.com and click “setup webhook”.
You’ll get a prompt, copy over the information from the alana.cloud platform information including webhook url and verify token (these are not the same). Click veridy and you should get a green checkmark that the endpoint was verified. Make sure at least “messages” and “messaging_postbacks” is checked.
Now you need to subscribe the webhook to your page. From the dropdown, select the page you generated the token for.

Now go back to alana.cloud and click the “Deploy” button. Deploying makes your current development version live publicly. This means that you can be working on a development version and not screw up your live delployed version. You can see deploy information in the Activity section of your bot.

Go back to facebook.com and find your page. Use the search bar or the little triangle menu on the top right. If you scroll down the page to the “About” section, you’ll see a “send message” button, click that and a message window should pop up with your bot.