ChatFlow Build A Bot Tutorial

Introduction

In this ChatFlow tutorial, we will walkthrough the process of building a bot from start to finish. In addition, we will introduce NLU - ChatFlow’s Natural Language Understanding companion platform.

By the end of this tutorial, you will be able to:
  • create a new project from scratch
  • configure Enter and State Nodes
  • create an NLU application.
  • configure the NLU node in ChatFlow
  • export and import ChatFlow Projects

The final bot should act a like this:




Build A Bot Walkthrough Video

Here is a video walking you through the entire Free Lunch Bot creation process:




The Free Lunch Bot

1. Creating an App from Scratch

Let’s create a simple flow that does a little more than just say hello. Our new bot will simply ask users for a free lunch. In addition, it will keep count of how many times it had to ask before getting a free lunch.

  1. Click on “Create new app”.
_images/CreateNewApp.png
  1. Under the “Start with a clean project” section, enter your project name and click “Create”.
_images/StartFromScratch.png
  1. Your bot will appear in your App List. Click on the name to enter the Editor.
_images/AppList.png
  1. Once the page loads, you will have an empty Canvas, as shown below.
_images/BlankCanvas.png
  1. Drag in the Chat In and Chat Out Nodes.
_images/chatin-chatout.png

2. The Conversational Router

  1. Drag a Router Node onto the empty Canvas. Connect the Chat In, Router, and Chat Out nodes like the image below:
_images/router-node.png

Note

The Router is responsible for directing messages within our Flow producing the conversational agent’s output.

Warning

In order to function, a project must have a Router!

  1. Double-click on the Router Node to name the Router Node.
_images/router-pop-up.png

3. Enter and State Nodes

Besides the Router Node, we are going to need two other nodes - the Enter and State Nodes.

State Nodes are used to define what the bot will say. Enter nodes are used to specify entrance conditions (the selection criteria that dictate when a branch in our Flow will be activated).

Enter Node

  1. Add an Enter Node to the Canvas. Each Enter Node contains a set of entrance conditions that specify when that specific Enter Node is chosen by the Router.
_images/enternode-1.png
  1. Double click on the Enter Node to edit.
_images/enternode-popup.png
  1. In this pop-up, name the node. Let’s call this Enter Node Initial state.
  2. Below the name field is the entrance conditions section. Remove the conditions by clicking on the “”X”” to the right of the condition.
_images/highlightedx.png

Note

One condition is partially added by default to get you started.

  1. Check the box towards the bottom of the pop-up that says Initial state. This will tell the Router that this Enter Node marks the first branch of Flow. You can then attach a State Node to it for initializing variables.
_images/initial-state.png

State Node

  1. Drag a State Node onto Canvas to the right of the Enter Node.
  2. Connect the Enter Node and the State Node together. Click on the grey dot on the right of the Enter Node. Drag the resulting wire to the left grey dot of the State Node.
_images/Intialstate-statenode.png
  1. Double click on the new State Node. Name it Initialize state.

  2. Below the name field, you will find a code editor. In the code editor, create a single variable called count that will keep track of how many times our bot has asked the user for lunch. The code inside this State Node will be:

    msg.kitt.count = 1;
    return msg;
    

Note

User variables are passed from node to node in the variable msg. In addition, special property msg.kitt will be persisted over sessions so you can track your context over different dialogue turns. Our variable in this case is msg.kitt.count.

Warning

The code associated with the State Node should end with return msg;. Otherwise no message will be outputted, thus halting the conversation.

  1. Select the “Request User Input After This Node” option. The bot will wait for the users response before proceeding.
  2. In the Output text field, input “Hello! Will you please buy me lunch?” Output text is outputted whenever the State Node is activated. The figure below shows what your State Node should look like.
_images/initialize-state.png

4. Adding input and output

  1. Deploy the bot.
_images/deploy.png
  1. Open the Chat Tab. Enter hello into the input field on the bottom of the screen. You should see a system output message from the State Node Initialize state.
_images/chat-bubble.png

The “No” Case

If you try to continue, the bot does nothing since the bot has nothing else to say. Let’s now give our bot the ability to handle yes and no answers from the user.

  1. Add an Enter Node and a State Node. Connect them as before.
  2. Edit the Enter Node:
  • Name it “U: no”
  • Set its condition to Property msg.payload == no

Note

This simply checks if the user input to the Router coming from the Chat In node is “no”

_images/u-no.png

Note

By convention, the main output of nodes is placed into payload. The user input coming from Chat In is stored in msg.payload.

  1. Edit the new State Node.

    • Name it ask again
    • Add the following code into its body:
    msg.kitt.count += 1;
    return msg;
    
  2. In the Output text field, enter I must insist. Will you reconsider? Your State Node should look like the one shown below:

_images/ask-again.png

The “Yes” Case

Now that the system understands no, let’s add another Enter Node and another State Node to handle yes.

  1. Add another pair of Enter and State Nodes. Connect them as before.
  2. Name the Enter Node U:yes and add the entrance condition:
    • Property msg.payload == yes
  3. Name the new State Node thank user, and leave the code as return msg;

Note

Since we don’t need the bot to do anything else when it reaches this node, return msg; will simply dump out the raw output of the node.

  1. In the Output text field, enter Thank you! Number of times I asked: {{kitt.count}}.

Note

In the Output text field, we can access variables stored in msg.kitt without the msg prefix.

  1. Check the box that says Dialogue ends here to tell the system that the conversation is over once we reach this state.
_images/thank-user.png

The figure below shows the entire conversational network:

_images/complete-flow-1.png
  1. Click Deploy and head to the Chat Tab. You should now be able to have a simple conversation with the agent as shown below.
_images/chat-bubble-1.png

Unable To Process Case

Our bot only understands yes and no, because we only included case-sensitive tests for yes and no user input. If we say anything else, the agent will not response. We can easily create an Enter Node to handle all other input strings.

  1. Add an Enter Node and a State Node to the Canvas. Connect them together.
  2. Edit the Enter Node, name is “U: default”, and set it’s entrance conditions to:
    • Property msg.payload is not null
    • Property msg.NLU.intent != positive_response
    • Property msg.NLU.intent != negative_response
_images/u-default.png
  1. In the new State Node, change the name to not understanding, leave the code as return msg;, and add the following text to the Output field: * Sorry, I didn’t understand what you said. I only understand “yes” and “no”.
_images/not-understanding.png

Now, your bot will always have something to say, whether it understands the user or not. Your Flow should look like the figure below.

_images/complete-flow-2.png

We can now have interactions like the following using our bot!

_images/chat-bubble-2.png

5. NLU & Dealing with Natural Language Input

We have built a simple bot that illustrates the basics of creating a bot in ChatFlow. However, we have yet to address how our bot can understand real natural language utterances. To deal with input in the form of natural language utterances without restrictions, we will use a Natural Language Understanding (NLU) node. The NLU node will map that utterance into a finite set of intents and entities, which we can then use in our Enter Nodes as the basis for our entrance conditions.

Add an NLU Node

  1. Insert the NLU node between our Chat In node and out Router node.
_images/flow-with-NLU.png

Create and NLU App

  1. Go to NLU, ChatFlow’s companion app. Create a new NLU app. Name the application.
  2. In the app, click on “Set Up Intents” to expand the “Set Up Intents” drop down.
_images/setup-intents.png
  1. Click on add intent.
  2. Name the new intent positive_response and click create.
_images/positive_response.png
  1. Under Example of Use, add the following natural language input strings. Feel free to include more:
    • Yes
    • yes
    • sure
    • of course
    • you bet!
    • it would be my honor
  2. When finished, click on the red “X” on the top right to exit the window.
_images/positive-utterance.png
  1. Click on add intent. Name the new intent negative_response and click create. Under Example of Use, add the following natural language input strings. Feel free to include more:

    • Nah
    • no
    • No way jose!
    • Never
    • I shall not
    • We are not amused
_images/negative-response.png
  1. Once finished adding the positive_response and negative_response intents, click TRAIN APPLICATION, and then DEPLOY.
_images/deploy-nlu.png

Warning

In order for your NLU model to update and be fully operation, you must train your model and deploy it.

  1. Test you model in the “Train the model” Section. Input a sentence and click analyze.
_images/train-the-model.png
  1. Once it has completed, check the result. You can correct the result by clicking on the blue button and selecting the correct response. When finished, click submit.
_images/submit-response.png

Deploy the NLU App

Warning

Before the final deployment, click “TRAIN APPLICATION” to fully optimize you NLU app. Afterwards, you will be able to issue RESTful API calls to your app.

  1. Click on “Show All Apps” in the upper lefthand corner to go back to the NLU app list.
  2. In you newly created apps bubble, click on Deployment Information.
_images/deployment-information.png
  1. Copy the Deployment Url onto your clipboard.
_images/deployment-url-expanded.png

Configure the NLU Node

  1. Edit the NLU Node. In the URL field paste the Deployment URL.
_images/flow-with-NLU.png

Note

The NLU node with store all NLU information in msg.NLU. Intents, entities and the original utterance will be stored in msg.NLU.intent, msg.NLU.entities, and msg.NLU.sentence, respectively.

  1. Add {{{payload}}} to the end of the URL. The final URL will look like this:

    http://api-nlu.kitt.ai/v1/api/900584f4-7360-479c?token=xxx?q={{{payload}}}
    
_images/NLU-node-payload.png

6. Reconfiguring The Enter Nodes

We now have NLU configured for our bot. However, we currently do not using this information within our bot. In order to do so, we must reconfigure the U: Yes and U: No Enter Nodes.

  1. Edit the U: Yes node. Under the entrance conditions section, remove the Property msg.payload == yes condition.
  2. Add a new condition, Property msg.NLU.intent == positive_response.
_images/u-yes-2.png
  1. Edit the U: No node. Under the entrance conditions section, remove the Property msg.payload == no condition. Add a new condition, Property msg.NLU.intent == negative_response.
_images/u-no-2.png
  1. When finished, click Deploy.

Go ahead and test you bot! The interactions should go a little like this:




Export and Import

You are able to export and import projects using the Export and Import JSON features.

To export, simply click on Export in the ChatFlow Editor and select whether you wish to export the project with or without credentials. ChatFlow will export a JSON file containing the entire Flow.

_images/export.png

To import, simply click on Import JSON on the ChatFlow home page and select the JSON file you wish to import.

_images/import.png

Warning

Both ChatFlow and NLU have export and import features. However, ChatFlow apps cannot be imported in NLU and NLU apps cannot be imported into ChatFlow.

Feel free to play with the bots template. You can either:

  • Download the ChatFlow json of our application and import the project using the Import JSON feature on the applications page.
  • Use the “Free Lunch” sample application when clicking “CREATE NEW APP” on the main page.

In addition, download the NLU json Use the NLU’s import JSON feature to import it as an NLU application and configure it to your ChatFlow App.