This document explains how a Botfuel bot works as well as the underlying concepts.
The purpose of a bot is to exchange messages with a user. A user message is processed by the bot, which then computes responses (bot messages).
A bot is an application composed of the following main components:
You can see how these components interact in this diagram:
Note that the bot implements the MVC pattern where:
Each messaging platform (e.g., Facebook Messenger) has its own message format. The adapters are responsible for translating external formats into the SDK's message format and vice-versa.
The SDK comes with the following adapters:
You can also use the external module Facebook Messenger as a adapter.
It is very easy to develop a new adapter. One just needs to implement the
Adapter abstract class.
The shell adapter and test adapter play a special role in the development of bots:
Shell Adapter allows you to run a bot in a shell, which is handy for debugging purposes:
> hello <span style="color:#16a085">> Hello!</span> > I want to buy some jeans <span style="color:#16a085">> What is your size?</span> <span style="color:#16a085">> S,M,L,XL</span> > M <span style="color:#16a085">> Which brand do you like?</span> <span style="color:#16a085">> Calvin Klein, Levis</span> > Levis <span style="color:#16a085">> Thank you. We have 2 products:</span>
Test Adapter allows you to easily run tests. Here is the code of a simple test:
const config = require('../test-config'); const bot = new Bot(config); await bot.play([ new UserTextMessage('Hello!'), ]); const userId = bot.adapter.userId; expect(bot.adapter.log).to.eql([ new UserTextMessage('Hello!'), new BotTextMessage('Hello human.'), ].map(msg => msg.toJson(bot.id, userId)));
See the integration tests of Botfuel Dialog for more examples of tests.
User messages usually contain text. Note, however, that a user message can also be:
When the message is text, the NLU (Natural Language Understanding) module is responsible for computing intents (or QnAs) and entities from the text.
Given a sentence, it is key to understand the user intention or intent. Look at the following example:
I want a ticket to Paris!
In this case, the intent could be
Given a sentence, the NLU module computes the expected intent (as well as the probability of this intent being correct).
You define the intents for your bot inside the Trainer on the Botfuel developer portal: https://app.botfuel.io, as in the image below. For each intent you must provide a list of examples of what the user might say for that intent.
Besides intents, you can create QnAs in your bot. A QnA is a special kind of intent where you define answers to questions. For each QnA you must provide some example questions for training. If the user sentence matches one of those questions then the QnA answer will be sent to the user.
This feature is very useful for several use cases, for example, when you would like to create a bot that answers commonly asked questions.
You can define both intents and QnAs in your bot. See Intents and QnAs reference for more details on intents and QnAs.
In order to understand the meaning of a sentence, it is also key to be able to extract named entities.
Given a sentence, the NLU module computes a list of named entities. The actual computation is performed by extractors. The SDK has two types of extractors:
quantitiesand more (see Entity Extraction service for more details about the web service and the entities supported).
See entities reference for more details.
The dialog manager is responsible for choosing which dialog to call. In the case where an intent has been classified, the dialog manager will try to find a dialog with the same name. For example, if the user sentence is classified by the NLU with the
trip intent, then the dialog manager will look for
You can define different dialogs for different adapters to handle different messaging platforms, like
trip-dialog.botfuel.js for example.
See dialog reference for more details.
The dialog manager enables complex conversations, including:
Let's illustrate different examples of complex conversations:
User: I want to go to Paris
Bot: I can help you get to Paris. When would you like to leave?
User: BTW, what's the weather like in Paris this week?
Bot: When do you leave?
User: I'll leave next week then
User: I want to go to Paris next Monday
Bot: I can help you get to Paris next Monday. Where are you leaving from?
User: Actually, I am leaving next Tuesday
Bot: Ok, Tuesday it is!. Where do you want to leave from?
From an MVC perspective, dialogs are the controllers of the bot. A dialog interacts with the brain (reads and writes), performs computations (e.g., by calling external APIs) and calls its view with the required parameters. Each dialog has a corresponding view with the same name.
The SDK offers several built-in dialogs:
BaseDialogfor handling basic dialog like greetings or thanks
ConfirmationDialogfor dialog confirmation
PromptDialogfor collecting information from the user by prompting him for inputs (entities)
QnaDialogfor answering the user's questions with your pre-defined QnAs (see the Botfuel Trainer document for how to create QnAs in your bot)
It is very easy to write new dialog types to implement custom logic.
Dialogs come with a set of powerful instructions to coordinate with other dialogs as well as with the Dialog Manager. This enables you to create complex, non-linear conversation flow in a clear and easy way:
completeindicates that the dialog is complete and should let the DialogManager execute other dialogs
waitindicates that user input is required for continuing execution of the dialog
triggerNextis used for chaining dialogs
cancelPreviouscancels the previous dialog
startNewConversationstarts a new conversation
See the integration tests for examples of how to use these instructions.
See dialog reference for more details.
Each dialog comes with a single view. The view is responsible for generating the bot messages depending on the parameters passed by its dialog. The view should not contain complex logic.
See view reference for more details.
Views generate messages. The SDK defines its own message format so that you can easily develop multi-channel bots. It supports:
See messages reference for more details.
From an MVC perspective, the brain is the model of a bot. A brain is needed to store important information from past user messages.
The SDK offers different brain implementations:
If you plan to deploy your bot on more than a single machine, then you need a brain which is shareable like the MongoDb-based brain.
It is very easy to write a new brain implementation. One just needs to implement the
Brain abstract class.
See brain reference for more details.