Chatbot builder documentation

What are the chatbot builder’s features?

The Chatbot Builder is a versatile tool to help you create chatbots for all messengers supported that WhatsBroadcast supports. The bots answer automatically. A large variety of usage scenarios is possible.

The central element of the Chatbot Builder are the Dialogues. These connect questions (or parts of questions) to bot answers.

In order to structure the dialogs, they can be put into Topics. This feature also makes it possible to create a tour through all answers in all topics.

The Chatbot Builder also supports Data Models. Entities can be used to group similar objects. It is possible to use entities in the dialogues, generating several similar dialogues concerning all objects of an entity at the same time.

With the Analyze feature, you can obtain information on your bot’s performance and development. It displays the trending bot questions and whether the bot answered them.

The Preview enables you to test the bot before setting it to active. If you turn the bot to inactive under Dialogue, it will not react to user input in your channel.

Dialogue

DIALOGUE


The central element of the Chatbot Builder is the Dialogue menu.

Here you can not only define user entries that will trigger a response, but it is also possible to upload pictures and to create buttons for bot answers.

Creating questions and corresponding bot answers is simple. However, it makes sense to follow a few rules.

Creating Dialogues


You connect an answer to user entries by creating at least one “user question” for the bot to respond to and a corresponding “answer”. Clicking the save icon will create the Dialogue element.

Clicking to the green arrow to the right will open a Dialogue elements editing view, where you can upload a picture and/or define buttons for the answer.

Editing the Bot Answer


It is possible to edit the bot answer. Clicking on the green arrow on the right-hand side of a Dialogue element opens its editing view. In this view, you have the option to upload a picture and create or edit buttons for this specific answer. The green arrow to the left will lead you back to the Dialogue view.

Image formats are PNG and JPG.

Buttons have character restrictions in order for them not to be cut off in messenger apps.

For Facebook Messenger, Telegram, and Insta, you can also add button actions. If you simply add a text for your button and leave the button action empty, this text will be treated as a text entry. Since WhatsApp does not support buttons, users need to enter the equivalent to the button action manually. There is a field for this purpose in which you can enter text that will only be displayed in WhatsApp and which should give users instructions on what they need to enter.

Buttons can have a link as button action. These are automatically shortened for WhatsApp and will be added below the answer.

How to use Dialogues


Following the steps mentioned above repeatedly, it is already possible to build a bot that answers user questions. There are, however, a few things to keep in mind in order to create a good bot.

The following principles are important:

User Questions are prioritized from top to bottom.*
Example: You could have two identical user questions right above each other. Let’s say, they are both the word “help”. Only the first one’s answer will ever be outputted. The lower one will be highlighted in soft yellow in order to help you detect conflicting user questions.

  • The bot only recognizes user questions if the words come in the right order.
    Example: You have a Dialogue that is prompted by “opening hours”. If a user asks “What are your opening hours?” the bot will identify the entry as a match; if a user would ask “In how many hours are you opening?” the bot would not consider the entry a match.

 

*There is one exception: The bot prioritizes Dialogues that belong to the same Topic as the answer that it just gave.

Based on these principles, the following rule can be derived:
Your questions should look like a funnel – those consisting of several words should be questions asking about specific information and these should be above short and one-word questions that concern information of a more general nature.

Example:

The bot is supposed to give specific information when a user asks for the price or brand of a product – let’s say, peanuts. If the question is less specific or if it concerns something that is not price or quantity, the bot is supposed to give general information on the product. This would mean that the user question “peanuts” should be placed below more specific user questions, such as “price peanuts”, “how much are peanuts”, “what peanuts cost”, “brand peanuts”…

Putting the simple one-word entry “peanuts” above those consisting of several words will give the lower user questions a yellow background to indicate that they have been rendered useless by an entry above.

Topics

TOPICS


Topics create a context for responses and control what the bot recognizes as user entries. It is possible to create an unlimited number of Topics and to add an unlimited number of Dialogues to a Topic.

In the Dialogue view, you can hide or display the Dialogues within a specific Topic.

An arrow pointing to the right indicates that a Topic is closed.

An open Topic is indicated by an arrow that is pointing downwards. All Dialogue elements in this Topic are visible when the Topic is open.

All Dialogues can be opened or closed by clicking on the buttons in the upper right corner of the Dialogues page:

Controling the Bot’s Behavior with Topics


Topics play an important role in creating a context for responses and controling what the bot recognizes as user entries.

Your Topics need to be activated via another Dialogue in order to become active.

This makes it possible to create one yes/no question per Topic and to have the bot respond adequately to user responses like “yes”, “sure”, “no”, “nope” etc. within a subject.

The bot behaves as follows:

Initially, no Topic is active. Dialogues in Priority and Default are always recognized by the bot. An additional Topic can be activated via a Dialogue in Priority or Default.

Only one Topic can be active at a time.

The reading order of the bot is as follows:

Priority
(Active Topic)
Default
Inactive Topic 1
Inactive Topic 2
Inactive Topic 3

Priority always comes first. If a Topic is active, it directly follows after Priority and Default comes last.

Activating Topics via a Dialogue

It is possibe to activate or deactivate a Topic via a Dialogue. The Dialogues of a topic are only recognized by the bot if they are in Priority, an active Topic, or in Default.

Tipps


  • If you combine a bot with our customer service module, you need to make sure that the bot does not frequently respond to user messages that you would rather have your staff respond to.
  • It makes a lot of sense to plan the bot’s architecture and content beforehand. Topics play an important role in a bot’s architecture.

Variables (PRO)

VARIABLES


The entities, which are described in the Data Model section, allow you to define data sets that the bot can flexibly access. These are information that you provide. In many cases, what you want is for the user to give you information that you can save and also use later on, e.g. for an order.

For this kind of scenario, the Chatbot Builder supports variables.

These can be used in the Dialogues. At the moment, you can have users set variables and you can give them back to the user. Depending on the messenger, you can also use variables in buttons. We are continuously developing new features. Feel free to tell us about your desired use case and we will let you know if the feature you require is already in development and we can learn from your ideas.

Exporting variables is not yet a feature of the Chatbot Builder. You can, however, combine the Builder with a Customer Service Module to manually collect the values from user chats.

Overview


Variables have a name (that you give them in the Variables section). They can be used in the Dialoges with this name. They also have a type and other attribues, such as a range of values and an expiration time.

Name
The name of the Variable can be used in the Dialoges by putting it between $ signs.

Type
The type of variable defines possible values and there is an automatic drop-down menu for selecting one of the existing entitites.

Values
You can select or limit possible values for the variable here. This is necessary for some types and optional for others; it makes no sense for some other types and is therefore not possible.

Expiration
this field sets the expiration time for a variable in seconds. The value is automatically deleted after this period of time.

Value for no expiration: -1

The Different Types of Variables in Detail


Number
A “Number” variable can save one number (decimal numbers are possible). The range of valid entries can be altered by relational operators (<, >, <=, >=):
e.g. “<=0” to exclude negative numbers. A space is interpreted as an AND, e.g. “>=0 <=100” for values from 0 to 100.

Example:
You would like to collect a user’s age. You could limit the possible entries as mentioned above and comment invalid entries via additional dialogues that are triggered by number variables for the respective ranges.

Word
“Word” variables use the first entry up to the next space or punctuation mark that a user enters where the variable is placed in the dialogue’s user question. The bot would therefore recognize “Mary-Sue” as one word, however, only recognize “Mary” for “Mary Sue”.

For a limited number of valid entries, an enumeration may be a better alternative.

Text
A “Text” variable saves a sequence of words and/or characters. The sequence can include punctuation marks.

For a limited number of valid entries, an enumeration may be a better alternative.

Date
At the moment, German and English date formats are recognized. The bot also makes dates from relative entries, such as “tomorrow” or “next week”.

Time
At the moment, “Time” variables recognize German and English time formats.

Enumeration
An enumberation is a number of words or sequences that a bot recognizes as valid entries. This type of variable is similar to “Text” and “Word”, but allows only very specific entries.

Location
A “Location” variable is set with any entry that Google Maps would accept. This type of variable uses the Google Maps Geocoding API. It usually makes sense to check back with users to make sure the right location has been recognized. The user should have the opportunity to confirm or correct the entry.

It is also possible to use the location feature of WhatsApp, Facebook Messenger, or Telegram to set the variable.

In the value field of the Variables section, you can limit possible entries to one or more countries, e.g. components=country:DE

Please refer to the documentation of the Google maps Geocoding API for in-depth information on how entries are recognized as locations: Google Maps Geocoding API

Collection
A collection works similar to an ennumberation. A collection, however, allows you to store several values instead of just one value that is overwritten whenever a user enters a matching value.

You can add as many values to a collection as you wish by dividing them with commas. A value can consist of several words or characters that can also be divided by spaces.

It is possible to trigger specific dialogues depending on the values that have been collected when a new collection value is entered by the user. To do so, you set $nameofvariable_x$ as a user question. This way, the dialogue is triggered when the “x”th value is entered by the user.

Using $nameofvariable_duplicate$ as a user question will create a dialogue that is triggered whenever a user enters a collection value that has already been collected.

Entity
If you have created entities, you can set these as a variable. Using an entity variable will set all of the entity’s identifiers as possible values of the variable.

Commands for Variables


The following commands, which have an effect on a user’s variable values, can be used in the Dialogues:

$clear_variables$
deletes all values set by the user

$clear_all$
deletes all variable values and ends the current topic

$clear_$
(e.g. $clear_variable1$, if the respective variable is named “variable1”)
deletes the current value of the respective variable

Data Model

DATA MODELS FOR DIALOGUES


It is often desirable for the bot to answer questions about a number of similar objects, e.g. weather information for a large number of cities.

Instead of creating numerous similar Dialogues, you can use placeholders that will automatically get the respective data from your data model. To achieve this, you go to Data Model and create entities.

First, it is important to consider which entities (which groups of similar objects) make sense for your scenario and to identify the required attributes. Additional attributes may be created later on and they can be deleted anytime.

As a rule, groups of objects that share similar traits and can be arranged in a table can be used as entities.

Creating Entities


First, create a new entity by clicking on the “+ Entity” button.

You now have two options: You can either edit the entity via the browser interface or you can import a table in the right format. A document that is suitable for import can be created in a spreadsheet in Excel or a similar program. Import formats are: “Text (Tab-delimited)” (.txt) and CSV.

Editing Entities via the Chatbot Builder Interface


In this example we have the entity “food”*. It includes 5 attributes (colour, shape, price, health, name) and 4 objects (apples, chocolate, broccoli, and sunflower seeds). The objects and their attributes can be used in Dialogues.

*You could write “food”, “FOOD” or even “fOoD” – neither an entity’s name nor its attributes are case-sensitive.

Importing Entities


You can use Excel or a similar program to create an import file for an entity.
Simply use the name of the entity as file name; the import table should look very similar to what it will look like in the editing view of the entity.

First, let’s say, the bot is supposed to answer questions about the color of a specific food. For the answer, the bot uses the entry in the “name” column and the entry in the “colour” column that match the identifier that has been used in the user’s question. Of course, the placeholders need to be included into the answer in a way that makes a correct sentence. This should be considered when creating the entity: e.g. singular and plural forms in an attribute column could cause problems in sentences.

There are often several ways to ask the same thing.

When creating a Dialogue on the pricing of objects, several different questions come to mind. We want to cover as many different wordings as possible without being too general. Simply using %food% alone can make sense at the very bottom of our Topic, in order to give general information on a type of food. It would, however, not make sense to answer any question on a specific food by telling the user the price. The goal is to be specific enough to not answer questions the wrong way, but to cover as many wordings as possible.

For more information on how to work with Dialogues, please refer to the Dialogue page.

Comparison


Here is an example of how many Dialogues would be required without the entity in order to replace a Dialogue that works with the entity. Both cover the same questions, e.g.
What do chocolate bars cost?
How much is the broccoli?
How much are the apples?
How much does a serving of sunflower seeds clost?
How much are sun flower seeds?
What’s the price of chocolate?
What is the price of broccoli?

Dialogue with Entity

This is what the Dialogue looks like with placeholders.

Dialogues without Entity

These Dialogues would be required to replace the Dialogue that works with the entity.

Analyze

ANALYZE


In Analyse you will find two graphs to help you evaluate the bot’s performance.

The first graph shows the number of chats that the bot has answered and development your bot’s quantitative usage over time:

The second graph displays the most frequent incoming chats of the last 24 hours. Green means that the bot responded to a chat; red means that it did not recognize any keywords. Responses are not automatically positive while not responding needn’t be a sign of bad performance, since it may not be desirable for the bot to respond to all incoming chats.

Entries that are marked red may be an indicator for missing keywords and can help decide what dialogues you should add for the bot to answer a frequently asked question.

Preview

THE PREVIEW


/

The Preview feature allows a bot test directly via the interface. This way, it is possible to set up the bot without putting it in the channel. When the bot is set to “active”, it is available in the channel. If it is set to “inactive”, it is only available via the Preview.

It is advisable to test each Dialogue in the Preview when first setting up a bot with the Chatbot Builder. It helps to get a good idea of how the product works.

The bot’s status can easily be changed in the upper left corner of the Dialogue view.