Getting Started

This article presents the core concepts to define and run bots with Xatkit.

Objectives

• Learn how to design simple intents with the Xatkit language
• Learn how to bind intents to actions to create a bot execution scenario
• Understand what is the configuration file and its contents
• Extend the GreetingsBot with custom intents and execution scenario

Xatkit Tip: check your installation

To complete this tutorial you need to have a local installation of Xatkit as well as the Xatkit Eclipse plugins installed in your Eclipse IDE. You can check the installation instructions to know how to setup your Xatkit environment.

Open the GreetingsBot example

The GreetingsBot is a bot example embedded with Xatkit (be sure to complete the installation first). You can open it in Eclipse by importing the Eclipse project located in xatkit/examples/GreetingsBot.

Once imported, Eclipse should show the following content in your Package Explorer:

A Xatkit project is composed of 3 different types of files:

• At least one .intent file containing the input matched by the bot
• An .execution file describing the bot's execution logic
• At least one .properties file containing execution-level configuration to deploy the bot

GreetingsBot Intent Library

Open GreetingsBot.intent. A pop-up may appear asking if you want to convert the project to a Xtext project. You can confirm it and the following editor will show up:

The first line defines the name of the intent library. The library name is used to identify the library, and provide useful auto-completion information in the other editors.

The rest of the file is composed of two intents that represent the user intentions the GreetingsBot responds to. Each intent contains a set of inputs which are examples of user input corresponding to the intent. Note that in this tutorial the bot is defined in English, but additional languages are also supported.

Xatkit Tip: the more input examples the better!

Xatkit uses the intent's inputs to train its underlying intent recognition engine. Increasing the number of input examples will improve the quality of the recognition, leading to smarter and more accurate bots!

GreetingsBot Execution Model

Open GreetingsBot.execution. The following editor will show up:

Execution models contain 3 sections:

• a set of library and platform imports that define what are the intent libraries and platforms used by the bot
• at least one use provider clause that specifies what inputs the bot will listen to
• a state machine defining the set of states (and transitions among them) the chatbot will execute depending on the user intents (and events).

Imports

Our example defines 2 library imports and 1 platform import

• import library "GreetingsBot/GreetingsBot-Lib.xmi" tells Xatkit to use the intent library defined in the previous section. In the example the provided path is relative to the workspace (<project_name>/<file_name>), but absolute paths are also supported.
• import library "CoreLibrary" specifies that the bot uses some intents defined in the Core Library, a set of intents bundled with Xatkit and providing generic, high-level intents that can be reused in multiple bots.
• import platform "ChatPlatform" specifies that the bot uses the Chat Platform, a generic messaging platform that can be deployed on multiple messaging services like Slack or Discord, or our React-based web component.

Xatkit Tip: the alias mechanism

The as GreetingsBotLib clause is an optional alias that can be dynamically re-mapped to a path when deploying the bot. This is required for custom imports (i.e. not provided as part of Xatkit bundled platforms and libraries) when the bot is not deployed on the machine it has been developed on (for example, the GreetingsBot is developed by us but can be run on your machine without changing any path thanks to this alias). The alias mechanism is further detailed in the tutorial article on remote bot deployment.

Providers

The GreetingsBot uses a single provider: ChatPlatform.ChatProvider. This means that the bot will receive user intents from the generic ChatProvider defined in the ChatPlatform (the list of each platform's provider is defined in the corresponding wiki article).

Xatkit Tip: no need to parse user input

The intent providers take care of parsing and extracting the intents from the user input. The concrete technology used to perform such parsing is defined in the configuration file. You can forget about intent extraction and natural language parsing and focus on what really matters: the specification of your bot!

States

Each state in the execution language contains 3 sections

• Body (optional): the bot reaction, executed when entering the state.
• Next (mandatory): the outgoing transitions defined as condition –> State. The conditions are evaluated when an event/intent is received, and if a transition is navigable the execution engine moves to the specified state (and executes its body, etc). Note that transition conditions can be as complex as you want.  And they are real guards, meaning that if the entire condition is not true the transition is not navigable, and the engine will stay in the same state.
• Fallback (optional): local fallbacks made easy. This section can contain arbitrary code (as the Body section) that will be executed if the engine cannot find a navigable transition.

An execution model also contains 2 special states:

• Init: a regular state that is entered when the user session is created. It can contain a Body, Next, and Fallback section.
• Default_Fallback: a state that can only contain a Body section, and cannot be the target of a transition. This state represents the default fallback code to execute when there is no local fallback defined in a state. This state can be used to print a generic error message (“Sorry I didn’t get it“), while local fallback can print a custom message tailored to the current state (“Please reply by yes or no“).

Finally, states can define a single wildcard transition (using the reserved character _ as the transition condition) that will be automatically navigated when the state’s body has been computed. This allows us to modularize the execution logic and reuse the same code in multiple places. See the detailed example below that shows a simple bot that just replies to the Hello intent above, asks for the user name and says hello to her (this example bot is supposed to be displayed via our React-based chat widget):

Our example defines 4 states:

• A init state that redirects the bot execution depending on the intent matching the user utterance
• Two states in charge of responding to each intent. In this simple example they just reply to the user.
• The last one is the Default fallback that just informs the user the bot was unable to understand the input text.

Xatkit Tip: multiple actions

You can bind multiple actions to a received intent.

Configuration

We now have defined the intents and the execution logic of our bot. The last step we need to perform is to deploy it. Open GreetingsBot.properties, this file contains the configuration elements required to deploy the developed bot:

Our configuration file contains 3 properties:

• xatkit.execution.model is mandatory, and specifies the path of the compiled execution file to run. In our example the path is provided as a relative path, but absolute paths are also supported. Note that relative path are relative to the .properties location.
• xatkit.libraries.custom.<alias_name> is mandatory for each library import with an alias. And specifies the path of the compiled intent library to bind to the alias. As for execution model, both relative and absolute paths are supported. the key point for now is to make sure that all the aliases defined in your execution model are bound to concrete paths in your configuration.
• xatkit.platforms.abstract.ChatPlatform = com.xatkit.plugins.react.platform.ReactPlatform specifies which concrete messaging service should be used to deploy the generic ChatPlatform. You can find the list of supported messaging services in this article. In this example we deploy our bot on the React Platform, allowing us to quickly test the bot locally. Different deployment options are covered in this tutorial.

Xatkit defined various properties that can be set in the configuration to customize the behavior and deployment of the bot. You can check the list of all the properties supported by the Xatkit Runtime component here, and find platform-specific properties in the corresponding platform's wiki article.

Start your bot

We now have all the pieces we need to deploy and test our bot! To do so, open a bash interpreter (for Windows users we recommend the one bundled with Git for Windows), navigate to your Xatkit installation's bin directory, and start your bot:

cd $XATKIT/bin
./start-xatkit-windows.sh <path to your GreetingsBot.properties file>

The console will log some initialization information, and after a few seconds you should see the following message:

You can test your chatbot here http://localhost:5000/admin (note that the bots behavior can be slightly different on the test page than when it is deployed on a server)

Open your browser and navigate to http://localhost:5000/admin to test your deployed chat bot!

Note that in this tutorial we use Xatkit's default intent recognition that performs exact matches based on regular expressions. This means that you have to send messages that are strictly the same as the ones defined in your intents' inputs. The configuration of advanced intent recognition services is detailed in this tutorial article.

Extend the bot

We have now reviewed all the basic concepts to define and deploy bots with Xatkit, and it's time for you to do some homework!

Here are possible extensions that reuse the key points of this tutorial:

• Extend the intents' input lists with new examples
• Create new intents to enrich the conversation: for example the intents Fine and Sad could be added to handle the user response to the question "I am fine and you?
• Use CoreLibrary's Help intent to provide some help information to the user

Xatkit Tip: test your changes

Xatkit doesn't automatically redeploy your bot when you update it. To test a new version of the bot you need to stop the current Xatkit application, and start it again.

If you prefer to check the extended GreetingsBot by yourself you can find it in your local Xatkit installation at this location: xatkit/examples/GreetingsBot-Extended.

What's next?

You can check this tutorial article to see how to configure Xatkit to use an advanced intent recognition service like Google DialogFlow. If you want to learn more about other messaging services that can be used to deploy the bot you can check this tutorial article.