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:

  • Adapter, adapts the messages to and from messaging platforms like webchat (chat window integrated into your website), Facebook Messenger, and others
  • NLU (Natural Language Understanding) component, processes user text messages to detect intents (or QnAs) and extract entities
  • Dialog Manager, decides which dialog(s) to call based on NLU result and previous conversation data
  • Dialogs, process information to compute data needed to generate bot messages
  • Views, generate bot messages based on the data returned by the dialogs
  • Brain, stores values relevant to the operation of the bot

You can see how these components interact in this diagram:

Diagram explaining the concepts


Note that the bot implements the MVC pattern where:

  • Brain is the model, it contains all the information about the bot, the users, and the conversations
  • Dialog is the controller, it updates the brain and calls its view with the required parameters
  • View generates the messages to be sent to the user


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:

  • botfuel, an adapter for Botfuel's webchat
  • shell, an adapter for running a bot in a shell
  • test, a test adapter for running tests

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);

  new UserTextMessage('Hello!'),

const userId = bot.adapter.userId;
  new UserTextMessage('Hello!'),
  new BotTextMessage('Hello human.'),
].map(msg => msg.toJson(, 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:

  • Click on a button
  • Upload (e.g., of an image)
  • Geolocation

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 trip.

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:, 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.

Named entities and extractors

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:

  • Extractors based on Botfuel's entity extraction web service, which includes 31 named entities such as dates, addresses, durations, quantities and more (see Entity Extraction service for more details about the web service and the entities supported).
  • Corpus-based extractors, for user-defined named entities (useful if you plan to integrate industry-specific knowledge into your bot). See the integration tests for examples of corpus-based extractors.

See entities reference for more details.

Dialog Manager

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 trip-dialog.js.

You can define different dialogs for different adapters to handle different messaging platforms, like trip-dialog.messenger.js, or trip-dialog.botfuel.js for example.

See dialog reference for more details.

Complex conversations

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: Cloudy

Bot: When do you leave?

User: I'll leave next week then

Random access navigation

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:

  • BaseDialog for handling basic dialog like greetings or thanks
  • ConfirmationDialog for dialog confirmation
  • PromptDialog for collecting information from the user by prompting him for inputs (entities)
  • QnaDialog for 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:

  • complete indicates that the dialog is complete and should let the DialogManager execute other dialogs
  • wait indicates that user input is required for continuing execution of the dialog
  • triggerNext is used for chaining dialogs
  • cancelPrevious cancels the previous dialog
  • startNewConversation starts 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:

  • Text messages and quick replies
  • Images and image uploads
  • Links
  • Buttons and clicks on buttons (aka postbacks)
  • Complex messages such as carousels

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:

  • In-memory brain
  • MongoDb-based brain

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.