Time bot tutorial
Ready to build your first bot?! Let's go!
We are going to build a bot that gives the current time to your users.
## Create the chatbot
We will create your chatbot called "time_chatbot" with the following command.
docker run -v $(pwd)/time_chatbot:/app -it openintent/chatbot
This will create a directory called time_chatbot on your host. This directory contains all necessary files for you to start editing the bot with our specifications (we call it the bot model) and the configuration for the various platforms. In this tutorial we only cover the model part. If you want to see how to plug your chatbot to messenger, please follow this link.
## Playing with initial bot
When you first run the command, docker creates the time_chatbot directory and initialize the bot model inside it. Then the chatbot starts and you can start typing in the console to test it right away. Just say "hello" and you should start chatting.
Are you done with the default bot? Let's continue.
A chatbot is like a child to who you teach life. He does not know anything about your business at the beginning but with your help he is gonna be smarter and able to handle a whole conversation with your users.
### Filling the dictionary
First, we must teach him the concepts of your business he will handle. In our case, we will teach him only three fairly simple concepts: greetings, time and question. That way, the bot will be able to say hello to your user and gives the time when the user asks it.
Replace the content of "time_chatbot/res/dictionary.json" with the following snippet and save the file:
{
"entities":
{
"@greetings": {
"Hello": ["Hi"],
"Hey": []
},
"@time": {
"time": []
},
"@question": {
"what": []
},
"@name": {
"name": []
}
}
}
This is a dictionary of what we call entities in the world of chatbots. Those entities are the founding principles of entity-based chatbots. One entity is a set of one or several words. For example, the entity "greetings" has two words "Hello" and "Hey" and each of them can have aliases like "Hi". You'll understand later the importance of those words and their differences.
Have you noticed that the application restarted when you saved the file? The chatbot is watching the model and configuration files and restart when one of them is modified so that the changes are automatically applied and you can test your bot right after the changes.
### Telling the stories
At this stage, there is something missing to test our bot. What is missing is the descriptions of the interactions with the user (we call it the story). Our time bot will handle a single story. He replies when the users say "hello" and gives him or her the current time when asked.
The stories are written with the Open-Intent Markup Language format (a.k.a. OIML) in the "time_chatbot/res/script.txt".
Replace the content of the file with the following script:
{
@root_state
-Hello
#greetings
*Be gentle, say hello!
-Hello, I can tell you what time it is if you ask.
@ask_state
-What time is it?
#telltime
*I don't understand what you mean...
-It is _.
@end_state
}
You can then test your bot with the IRC client since the bot model is done.
Now, let's have a little dive in the OIML script to discover and understand the various features of the framework.
The script contains one story between brackets. A story is a succession of user intents, bot replies and actions that we'll discover later. It is very important that you keep in mind that an intent is an ordered list of entities defined in the dictionary.
The first intent in our example contains one entity "hello" and the second contains two entities "what" and "time". They represent greetings and a request from the user to get the current time. The aim of entity-based intent detection is to detect the intent in a sentence without knowing anything about the syntax of the sentence . Instead, the bot will try to match the words one by one with entities defined in the dictionary. And when the ordered list of entities is found, the chatbot knows he must trigger the associated action.
For instance, "What time is it?" is an intent made of two entities ["@question", "@times"]. Thus when the bot find "what" and "time" in this order in a sentence from the user, he knows the user wanted to get the current time and trigger the action "#telltime".
Note that intents and replies are starting with a dash. -Hello
There are some scenarii in which the bot does not understand the user intent because he did not find any matching ordered list of entities. In such a case, we would like our bot to reply something anyway to tell the user he did not understand. This is the aim of fallback replies that starts with a star.
*Be gentle, say hello!
Try to type "Where are you?" and the bot should reply "Be gentle, say hello!"
In our test case, we only have one story but there can be as many stories as you wish. In that case, state annotations are useful to cross stories. Let say the user can either ask the current time or request the name of your bot. There might be two stories depending on the intent. Let's try this feature by appending the following story to the script.
{
@ask_state
-What is your name?
#tellname
*I don't understand what you mean...
-My name is Bob.
@ask_state
}
After greatings, you can now ask the name of the bot or the current time. Great, uh?
#### Reply variables and user commands
Have you noticed the ${0} while chatting with your bot whereas you were exepecting the current time? This is called a reply variable. The placeholder _ declares a reply variable that the chatbot must fill with the current time. To do that, the bot must compute this current time with a user defined command in Javascript.
Copy and paste the following piece of Javascript code in time_chatbot/res/user_commands.js
function getDateTime() {
return new Date().toString().substring(16,24);
}
module.exports = {
'#telltime': function(intentVariables, sessionId, next) {
var replyVariables = {};
replyVariables['0'] = getDateTime();
next(replyVariables);
}
};
Now, try asking the current time and it should work as expected.
The user commands have two roles. They make the link with your business and are used to fill reply variables with computed values. In this example, the command with ID "#telltime" referenced in the OIML script is called when the intent with entity ["question", "time"] is found.
In the Javascript function, the variable '0' is filled with the current time. Note that there can be as many reply variables as you wish in the reply template. The variable names are incremented so that the second variable would have name '1'.
The variable intentVariables is a dictionary filled by the framework and contains information about the detected intent such as the entities of the intent and the words that matched (remember, an entity is a set of words each of them having aliases). The keys are the entities with incremented number as suffix and the value is the text that has been detected.
We have seen how to create our first simple chabot. Yet, there are much more features to discover in the documentation like multi-words entities, regexp entities and a lot more to come.
Have fun and stay tuned!