Getting Started Guide

This guide will walk you through creating your first two chatbots:

  • A “Hello World” bot that responds to user input.
  • A simple NewsBot that connects with a public API and displays news stories to the user.

These two bots will illustrate the most important features of the BotCentral platform.

What you need to get started

BotCentral bots run on the Facebook Messenger platform. Before you get started you need:

The Facebook page that you connect your ChatBot to will respond to incoming messages — so you may want to create a testing page for working on your bot. You’ll be able to switch your bot to a different page later.

Creating a Facebook page. Any type of page will do.

Creating a Facebook page. Any type of page will do.

Hello World

Assuming you already have a Facebook page to connect to, log into BotCentral and Create a New Bot.

Create Bot button

Create Bot button

In the Bot Details tab, give your bot a name and a description. The description will be shown to Facebook messenger users when they view your bot’s page.

Bot Details.

Bot Details tab

Connect Your Bot to Facebook

Now, connect your new bot to your Facebook page.

Facebook Connection tab

Facebook Connection tab

Select the Facebook Page option, not the Messenger App option. (Connecting to a Messenger App is an advanced feature.)

You should see a list of all Facebook pages managed by your Facebook account. Select the one you want to use, and click Done.

Click Done

Click Done

Congratulations, you have a bot. The BotCentral Platform immediately adds a few boilerplate messages, which means you can immediately say hello to your bot if you want to.

Say Hello to your little chatbot friend.

Say Hello to your little chatbot friend.

There’s also some Preprocess Code in place to make sure that returning visitors are greeted appropriately.

Chatbot recognizes a return visitor.

Chatbot recognizes a return visitor.

Add a new message

Go to your Dashboard to find your bot’s menu, and then open the Messages Editor.

Main Menu. Go to Dashboard to see your bots.

Main Menu. Go to Dashboard to see your bots.

Bot Menu. Open 'Messages Editor' to add messages to your bot.

Bot Menu. Open ‘Messages Editor’ to add messages to your bot.

One you have the Messages Editor open, add a new Chat Message. You’ll see the Chat Message editor.

Chat Messages Editor

Chat Messages Editor

Let’s give the Message a name, and add some patterns. Patterns are used to match user input to a message. We’ll trigger this message if a user includes the string world in a message.

Name and Patterns input

Name and Patterns input

The asterisks (*) before and after the strings are a stand-in for any text. They are optional. The content they represent can be accessed with the {$botContext.starVar1} & {$botContext.starVar2} variables.

Next, set the Type, the Content Type, and the Result Type:

  • Type
    • Bot Response — Select this one. Used for messages that are triggered by user input.
    • Bot Message — Used for messages that are triggered by other bot processes.
    • Default — Triggered when a user input matches no pattern.
  • Content Type
    • Static — Select this one. Used for responses that return static content.
    • Dynamic — Used for responses which include information fetched from a Responder.
  • Result Type
    • Text — Select this one. Returns text responses to the user.
    • Structured — Returns structured tiles.
    • Image — Returns an image to the user.
    • Audio — Returns a sound file to the user.
    • Video — Returns a video to the user.
    • Button — Returns one or more buttons. Buttons can be used to trigger further actions.
Set the Type, the Content Type, and Result Type

Set the Type, the Content Type, and Result Type

In the Text Tile, add some text you want to return, like Hello, World!

Add "Hello, World!" text tile.

Add “Hello, World!” text tile.

And, now that you have a Message with a response, you can Test in Messenger or simply send a message to your page from your phone’s Messenger app.

Hello, World!

Hello, World!

NewsBot

Now we’ll do something a little less trivial — a chat bot that fetches news and sends it to the user. Along the way we’ll also ask the user their name, and use it in responses.

If you don’t already have a Facebook page you want to use, start by creating a new Facebook page for this.

Creating a new Facebook Page.

Creating a new Facebook Page.

Then go to BotCentral and create a new bot.

Create a new bot for the news.

Create a new bot for the news.

And associate it with your Facebook page.

Facebook connection tab.

Facebook connection tab.

Edit the Welcome messages

Go to the Messages editor and change the text results for the Welcome message. We want to change the generic greetings so that the bot identifies itself and asks the user their name.

Let’s go with these options:

  • Hi there, I’m your NewsBot! What should I call you?
  • Welcome to NewsBot! What’s your name?
  • Howdy! I’m NewsBot! What’s your name?
Setting up the Welcome message

Setting up the Welcome message

When this response is sent, one of these will be chosen at random. (They will not all be sent — only one of them.) This lets you introduce a little bit of variety to your responses.

Say hello to NewsBot

Say hello to NewsBot

We want the user to tell NewsBot their name, and for NewsBot to remember it.

To do this, we’ll add some code at Process User Response.

Process User Response

Process User Response

If there’s any code here, the bot waits for a response from the user. Then, the code is run. You can access the user’s response in this code with getCurrentUserMessage()

Here’s the code to use for setting the user’s response as a persistent variable, using setBotVariable().

botContext.setBotVariable('userName',botContext.getCurrentUserMessage(),true);

We’ll also add a line to print a debugging message to the logs, using printDebugMessage().

botContext.printDebugMessage('userName is ' + botContext.getBotVariable('userName'));

And, finally, we’ll kick off the next message, which will be the main menu for our NewsBot, with setTriggerNextMessage(). This will keep the interaction moving, instead of waiting for the user to think of what to do next.

botContext.setTriggerNextMessage('01 SOURCE MENU');

So, your entire Process User Response code should look like:

botContext.setBotVariable('userName',botContext.getCurrentUserMessage(),true);
botContext.printDebugMessage('userName is ' + botContext.getBotVariable('userName'));
botContext.setTriggerNextMessage('01 SOURCE MENU');

If we’re going to call the Source Menu from the Greeting, we better set that up.

Source Menu

Create a new message, call it 01 Source Menu. Add the pattern menu so that the user can say menu to see this menu again later. (Remember, though — the first time this appears, it is triggered by the Welcome message.)

Then set the responder to ask the user which news source they would like to see. Be sure to use the $botContext.userName variable to personalize the message.

Source menu message setup.

Source menu message setup.

You can test this if you want.

The Chatbot knows my name.

The Chatbot knows my name.

Now we’ll add some Quick Replies. Quick Replies work like multiple-choice responses to a message. For the Source Menu, the Quick Replies will be the different news sources we can access through the News API we are using.

Quick Replies

Quick Replies

Quick Replies have a Title (which the user sees as a choice in the menu) and a payload (which is a string that you can use in your code).

Here are the Quick Replies to add, with their payload. (You can find other news sources’ titles and payloads on the News API website)

  • Ars Technicaars-technica
  • Buzzfeedbuzzfeed
  • ESPNespn
  • The Guardian (UK)the-guardian-uk
  • Hacker Newshacker-news
  • The Huffington Postthe-huffington-post
  • NFL Newsnfl-news
  • The New York Timesthe-new-york-times
  • Timetime
  • USA Todayusa-today
Showing Source Menu

Showing Source Menu

But now we have to do something with the user’s selection. We’ll use Process User Response to get the selected value. Then we’ll trigger another message that handles displaying the news.

Process User Response

Process User Response

The code:

var name = botContext.getCurrentUserMessage();
var value = botContext.getQuickReplyPayload();
if(value != null) {
    botContext.setBotVariable('newsSource',value,true);
    botContext.setBotVariable('newsSourceFullName',name,true);
    botContext.printDebugMessage('User selected ' + name);
    botContext.setTriggerNextMessage('02 STORIES BY SOURCE');
} else {
    botContext.sendImmediateReply('Sorry, something went wrong...');
}

This sets two local variables with the user’s Quick Reply selection (one for the name, and one for the payload). Then, if the Payload is set, it assigns the values from those local variables to persistent variables that can be used in the next step. After that, the next message, 02 Stories By Source is triggered.

The else condition runs if there was no payload, which happens if the user types something without selecting a Quick Reply.

Now, we’ll take the selection and build a message that calls a Responder.

Stories by Source

Create a new chat message.

Stories by Source

Stories by Source

Oh, but in order to select a Responder, you have to create a Responder.

News API Responder

We’re going to build a Responder that calls the NewsAPI.org web service. You’ll need to register and get a free API key.

Once you have an API key, you can create a Responder.

Create a new Responder

Create a new Responder

The Webhook is the API URL, in this case, https://newsapi.org/v1/articles.

The News API only requires two parameters:

  • your API key (you can find your API key once you make NewsAPI account)
  • the name of the news source

We’ll pass the name of the news source with the saved data from the Quick Response payload, which we set as a variable named newsSource. We access this in the Responder form with {$botContext.newsSource}.

Next we set the Method (GET) and the Result Type. We’re going to return several news stories in the form of scrollable structured tiles, so select Structured.

Set the method and result type

Set the method and result type

Now we’ll create the structure of the tiles. You can access the result set with $, and iterate through them with i. (See the NewsAPI Documentation for details.)

Responder structured tile

Responder structured tile

  • Title{$.articles[i].title}
  • Image Url{$.articles[i].urlToImage}

That will display the stories, but we need a way to let the user read them. So let’s add a button for that.

Responder button to Read story

Responder button to Read story

  • NameRead Full Story
  • TypeWeb URL
  • WebviewFull
  • CallBack{$.articles[i].url}

The Read button will open the article URL in the user’s browser.

Let’s also add a button that takes the user back to the Source Menu as well.

Menu button setup

Menu button setup

  • NameMenu
  • TypePostback
  • CallBackmenu

This simply sends the word menu back into the chat message, as if the user had typed it. That will trigger the pattern match on the Source Menu message.

Calling the Responder from a Message

Ok, let’s go back to the Message that included this Responder.

Stories by Source setup

Stories by Source setup

Setting the content type as Dynamic and selecting the Stories Responder causes the Stories Responder to generate the response. We can prepend a message to the response using the Pre-Result.

Here are the top stories from {$botContext.newsSourceFullName}…

This prints just before the structured results from the Stories Responder are displayed.

Displaying stories from ESPN

Displaying stories from ESPN

Welcome Back

Once you have some basic functionality, you need to clean up the Welcome Back message.

As mentioned above, BotCentral adds some Preprocess Code to the built-in Greeting message. This code is executed before the message output is prepared. The code catches the message before the results are sent, and triggers the Welcome Back me message.

The built-in preprocess code.

The built-in preprocess code.

Here’s the built-in code:

function evaluate() {var d = new Date(); if (botContext.getBotVariable('lastVisited') != null) { botContext.setTriggerNextMessage('Welcome Back');} else { botContext.setBotVariable('lastVisited',d, true); }} evaluate();

This triggers the Welcome Back message, but right now the Welcome Back message is a dead end — it doesn’t do anything after it says Welcome Back. So, let’s trigger the Stories by Source message. This will fetch the latest stories from the last news source the user asked about.

botContext.setTriggerNextMessage('02 STORIES BY SOURCE');

We’ll add this to the Post-Process code, so it will execute after result (Welcome back.) is sent.

Triggering the Stories by Source message from the Welcome Back message.

Triggering the Stories by Source message from the Welcome Back message.

We can even add the user’s name into the result messages, and customize them to be about the news.

Custom Welcome Back messages

Custom Welcome Back messages

And now you have a bot that remembers users when they come back.

Welcome back!

Welcome back!

Next Steps

  • If you haven’t yet, read our Introduction to Chatbots. This provides information about how to design and think about conversational user interfaces.
  • Explore the in-depth Message Flow guide, which shows what actually happens when a user sends a message to a bot — very helpful for thinking through more complicated bot designs.