Home

Welcome to the Social-Bot-Framework wiki!

This wiki contains documentation for bot developers 🤖.

Bot-modeling Guide

A Bot's Basic Configuration

First, to be able to deploy the bot (on a running instance of the SBFManager, we will need to connect an Instance element to a Bot element with the "has" relation.

The Instance element will represent the las2peer instance on which our used services are running and on which our bot will be acting. For the attributes, an arbitrary name can be given and the address of the las2peer instance is also needed. There is also the optional attribute "Environment Separator", which can be used if multiple subcategories are defined in the instance. The Bot element will only need a name, with which the las2peer network will identify the created bot. When creating a Chatbot, some additional elements are needed. These will be the NLU Knowledge element and the Messenger element. The Bot element will use the "has" relation connecting both of these elements.

The NLU Knowledge element represents the bot's used NLU Model(language model), thus the bot's vocabulary. As attributes, the NLU Knowledge element will need an arbitrary name, the address of the Rasa server hosting the NLU Model, and an ID to differentiate between multiple NLU Models, as a bot can possess multiple NLU Models. The Messenger element will represent the used communication platform, for which the platforms Slack and Rocket.Chat are currently available. After setting a platform as an attribute, an additional authentication token will be needed which should be provided by the platforms themselves:

• Slack: Create Bot Slack App in the App navigator. Creator of bot will have access to the bot's token.
• Rocket.Chat: Administrator will need to create a bot user and provide name and password for bot user. The auth token will then be name:password.
• Moodle Forum/Chat: Administrator of moodle instance will need to create user and provide the authentication token.
• Telegram: Use bot father (https://t.me/botfather) to create bot user. The bot father also provides the authentication token.

Modelling Chatbot-User Interaction

Now that we have a bot that is ready to be deployed, we still need to model the conversation itself. The SBF will allow us to create the bot's NLU Model, thus how it will interpret the user's messages and we will be able to let the bot respond with fitting messages depending on the user's message.
First things first, the user will need to model the bot's NLU Model in the "NLU Model Training Helper" part of the SBF frontend. The Markdown format is used for creating the NLU Models and a precise tutorial can be found at Rasa's official documentation. Overall, here the user will define the Intents the bot will be able to recognize based on given examples. To upload the NLU Model, the SBF Manager endpoint and the Rasa NLU Endpoint need to be adjusted accordingly. The model will first be trained and thus not be immediately available. One can check the training's state by pressing the "Check Training Status" button. The Incoming Message and Chat Response elements are used for modeling the conversation.

At the beginning of a conversation, the bot will wait for the user's message. After the bot receives a message on the chat platform, it will attempt to extract an Intent from the received message. The Incoming Message element will represent the user's messages and has an Intent attribute, which will contain the expected Intent. If the bot recognizes this Intent, the bot will go to this Incoming Message element and trigger the corresponding Chat Response. The Chat Response element thus represents the bot's response to user messages for which the concrete response can be written in the "Message" attribute field of the element. If the response should be a text message, the "Type" attribute should be "Text Message".
For an easy example, lets say we modelled the bot to expect a greeting from the user and great them back. For that cause, the "greeting" Intent was defined in the NLU Model. Additionally, the Intent attribute of the Incoming Message element will contain "greeting" and the Chat Response's "Message" attribute will contain the message "Hello :)". If the user now greets the bot, the bot will extract the "greeting" Intent and jump to the fitting Incoming Message element and then greet the user back with "Hello :)".

Note that one Incoming Message element can also be triggered by different Intents. Simply separate the Intents using a comma:

An additional option is to let the bot use multiple Chat Response elements for one Incoming Message element. This would simply lead to the bot randomly choosing one of the available Chat Responses to give to the user, making the bot a bit more interactive.

Default Bot Message

Adding an Incoming Message with the Intent attribute set to "default" would lead to the bot giving out a default answer if it does not understand a message (i.e. having low confidence when extracting the Intent) and stop the current conversation path.

It is also possible to give out default messages that do not break the current conversation path. For that, an additional Incoming Message element is needed with the Intent name "defaultX". X represents a positive number, which indicates how often a bot should give out the "defaultX" message. After "X" tries, the bot will cut off the conversation path and give out the normal "default" message, if provided.

Modelling Chatbot-User Interaction: Creating a Conversation Path

After a first chat interaction with the bot, there also is the possibility to create a conversation path, which will make the bot wait for specific Intents and trigger Chat Responses that could be triggered in this conversation path and not from the initial state of the conversation. To create a conversation path, the "leadsTo" relation can be used between Incoming Message elements, where the "label" attribute of the "leadsTo" relation must contain the follow-up Intent.

The Intent attribute of the follow-up Incoming Message elements can remain empty as the leadsTo relation will take care of forwarding the state. For these messages to be reachable from the initial state, the Messenger will again need to connect to these elements using the "generates" relation and the elements will also need to have the Intent attribute set. Once there is no follow-up message the conversation path will be quit and the conversation will go back to the initial state. If no fitting Intent is recognized, the bot will simply send the default message. If one of the leadsTo relations is empty, this path will be taken if no fitting Intent was found while in a conversation. Continuing the previous greeting example, the user could have changed the bot's initial message to "Hello :), how was your day?". To model a fitting response, the user added the Intents "positive" & "negative", added new Incoming Message elements with the leadsTo relation and added Chat Responses with fitting answers. The bot would now, after asking the user about their day, expect a positive or negative answer and respond accordingly.

It is also possible to trigger one leadsTo using different Intents by separating the Intents using a comma.

Use recognized Entities in Chat Responses

The bot is also able to use recognized entities in a chat response. To do so, the text in the response field should simply contain the name of the entitiy in brackets. Let's say the language model looks like this:

Then during a conversation path you can reference a recognized entity in the following way:

This results in following behaviour:

Use recognized Entities to choose Chat Response

It is also possible to use recognized entity values to trigger specific Chat Responses. To do this, you simply need to write the expected entity value in the "trigger" arrow which connects the Incoming Message element with the Chat Response element. If no fitting entity value is found, the Chat Response with an empty trigger arrow will be chosen.

Here a quick example: First we have our NLU model:

Then the trigger arrow:

And this is the conversation with the bot:

File Messages

In addition to modeling simple textual responses, it is also possible to let the bot send a file to the user as a response. For that purpose, the Chat Response Element contains two additional attributes called "FileURL" and "ErrorMessage". FileURL should simply contain the URL to the file's download page. ErrorMessage should simply contain a message, which will be sent to the user in case an error occurs when retrieving the file. Currently, the placeholder "menteeEmail" is available for the FileURL attribute. If "menteeEmail" is contained in the FileURL, it will be replaced by the user's email address.

Create communication state with service

There is the possibility to let users communicate and send messages to a specific triggered service for a certain period of time, depending on the service. During this communication state, the service will receive every user message and also have the possibility to communicate with the user. To model this you need to do the following:

• Have an incoming message object trigger a chat response object
• The chat response object will contain no message
• The chat response object will be connected to a bot action object with the "uses" relation
• The bot action will now be the service with which the user will communicate

The parameters of the Bot Action element will need to be set in the following way for when communicating with a las2peer service (note that the services need to be bootstrapped with each other):

• Action Type: Service
• Function Name: Name of function in implementation.
• Service Alias: Short name of las2peer service. Usually defined at beginning of service code.

In case the service is not a las2peer service, but still supports swagger, the parameters need to be set in the following way:

• Action Type: OpenAPI
• Function Name: Name of function in implementation, can be found by looking up the swagger.json file and searching the operationID of the function.
• Service Alias: Base URL of the SERVICE, such that /swagger.json results in the swagger.json file.

Apart from the defined action parameters, the JSON body contained in the request to the service will contain following additional attributes:

{
    "msg": "Message the bot received from the user",
    "botName":"AgentId of Bot",
    "channel": "Channel Id of bot and user conversation",
    "intent":"Recognized Intent",
    "entities":"List of recongized entities",
    "email":"Email address of user",
    "user":"Username of user",
    "time":"timestamp"
}

The service will need to respond to the request with a json file containing the following data:

{
    "text": "",
    "closeContext": ""
}

The text attribute represents the service's response to the user.

The closeContext attribute is a boolean value that informs the Social Bot Manager if the communication state is to be maintained or stopped. (Note that, if no closeContext attribute is found, the communication state will automatically be stopped.)

The service can also respond to the request with a json file containing the following data:

{
    "blocks": "",
    "closeContext": ""
}

The blocks attribute represents the service's response to the user in form of an interactive message. The Slack block kit builder, to create an interactive message in Slack, can be found at https://app.slack.com/block-kit-builder

Currently supported types of message components in Slack:

• plain text (when using the blocks to encode text, it is formated)
• action checkboxes, including their description
• action buttons
• action radio buttons
• divider

Sending Files to a Service

When modeling the conversation between bot and user, there is also the possibility to let the bot expect files from a user. To be precise, a user could trigger a service by sending a file, which would get forwarded to the service for further processing. Let us take our communication state from before and presume that the Bot Action Element is a service that expects a file:

In this case, we would like the service to be triggered only if a file was sent. To do this, we have the "IsFile" bool attribute in the Incoming Message Element. If the IsFile attribute is checked and no Intent is given, then the Bot Action will be triggered regardless of the file's name (given that a file was sent). If an Intent is given, then Intent extraction will be done on the file's name and see if the extracted Intent corresponds to the Intent given as an attribute in the Incoming Message Element. This for example allows the bot to understand specific file name formats, such as the following:

If a file is sent to a triggered service, it will first be encoded into base64 encoding. Afterwards, the JSON body sent to the triggered service will contain the following attributes:

{
    "fileBody": "String of base64 encoding",
    "fileName": "String",
    "fileType": "String"
}

Note that if a service wants to send a file to a user, it will also need to encode the file in base64 encoding and the response will additionally need to contain the 3 just shown attributes.

Sending Interactive Messages to Slack

Definition in the frontend

When modelling the conversation between bot and user, there is also the possibility to let the bot send an interactive message to a user. To do this, the Chat Response Object needs to be defined with the Type "Interactive Message". The Message field then needs to contain the code that parses the interactive message, only the content of the "blocks" jsonobject is needed.

Creating a Slack app

When using the interactive messages in Slack, it is necessary to:

1. Create a custom Slack app, since interactive messages are not usable with the "Bots" app that is available when clicking on the "Add apps" button on the bottom left.

2. Activate interactive components in the Slack app settings (on the left side: Basic Information: Add features and functionality, Interactive Components. After activating this feature, a Request URL is needed. A Request URL is an address where notification about button clicks will be sent.)

3. Configuring the Request URL. The ip address and port where Slack posts the request (the address from the SBFManager), Slack app token, the bot name from the frontend, the instance name from the frontend and the buttonIntent name are needed. http://{ipAddress:port}/SBFManager/bots/{botName}/appRequestURL/{instanceName}/{buttonIntent}/{token}.

4. Configuring a route that can be publicly accessed when hosting the SBFManager on a local system. This entails a TCP port sharing:

• either by logging into your fritzbox, then go to the internet settings and then port sharing. When using the URL for the Request URL, the newly created public URL needs to be provided
• by using the app called ngork

Deactivate running Bot

Currently, there is no possibility to turn off a bot from the modelling frontend alone. A HTTP call is available that lets users delete their bots:

DELETE <service-address>/SBFManager/bots/{agentId}

The agentId of the running bot can be found by querying the list of the running bots:

GET <service-address>/SBFManager/bots

To prevent unauthorized users to delete bots, an additional array needs to be provided. For every chat platform the particular bot uses, an object with following form will be needed:

{ "messengerNames":[
  {
    "name": "Given Name of Messenger Element found in <Name> attribute of Messenger Element", 
    "authToken": "Authentication Token String"
  },...]
}