This article presents the core concepts to define and run bots with Xatkit.
- 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 releases. You can open it in Eclipse by importing the Eclipse project located in
Once imported, Eclipse should show the following content in your Package Explorer:
A Xatkit project is composed of 4 different types of file:
- At least one
.intentfile containing the input matched by the bot
.executionfile describing the bot's execution logic
- At least one
.propertiesfile containing execution-level configuration to deploy the bot
.xmifiles that are compiled from
.executionfiles and should not be updated manually
GreetingsBot Intent Library
GreetingsBot-Lib.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
GreetingsBot-Ex.execution. The following editor will show up:
Execution models contains 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 are the inputs the bot will listen to
- a set of execution rules binding user intents to actions (execution rules also support additional constructs that are not covered in this tutorial)
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
as GreetingsBotLibclause 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.
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!
Our example defines 3 execution rules:
- The first two ones bind the intents defined in
Replyactions, that are simple actions allowing to post a message as a reply to a user input.
- The third one is triggered when the
Default_Fallback_Intentis received. This intent is defined in the
CoreLibrary, and is returned when the underlying intent recognition engine does not find any intent corresponding to the user input. We also bind it to a
Replyaction, with the dedicated message
"Sorry I didn't get it".
Xatkit Tip: multiple actions
You can bind multiple actions to a received intent.
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.modelis 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
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. Note that the alias mechanism is further detailed in the tutorial article on remote bot deployment, 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.ReactPlatformspecifies 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
Sadcould be added to handle the user response to the question
"I am fine and you?
- Use CoreLibrary's
Helpintent 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:
You can continue reading here to learn how to extract information from user input and how to create complex conversation flows with Xatkit. You can also 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.