Search…
Creating your first Chatbot
Prerequisites: Up and Running instance of EDDI (see: Getting started)

How does it work?

In order to build a Chatbot with EDDI, you will have to create a few configuration files and POST them to the corresponding REST APIs.
A chatbot consists of the following elements:
  1. 1.
    (Regular) Dictionary to define the inputs from the users as well as its meanings in respective categories (called Expressions in EDDI).
  2. 2.
    Behavior Rules creating Actions based on decision making with predefined as well as custom conditions.
  3. 3.
    Output to answer the users request based on the results from the behavior rule execution.
  4. 4.
    Package to align the `LifecycleTasks` (such as the parser, behavior evaluation, output generation, ...)
  5. 5.
    Bot to align different Packages and Channels.

Example of a resource reference

eddi://ai.labs.regulardictionary/regulardictionarystore/regulardictionaries/ID?version=VERSION
eddi:// URI resources starting with this protocol are to be related with in EDDI
ai.labs.regulardictionary Type of resource
/regulardictionarystore/regulardictionaries API path
ID ID of the resources
VERSION Read-only version of the resource (each change is a new version)
Version of this resource (each update operation will create a new version of the resource)

Let's get started

Follow these steps to create the configuration files you will need:
(It is a good practice for the first time creating a bot to do it manually via the rest interface. For further configuration, there is a GUI [Manager] available as well)

1. Creating a Regular Dictionary inside Parser

See also Semantic Parser
Create regular dictionaries in order to store custom words and phrases. A dictionary is there to map user input to expressions, which are later used in Behavior Rules. A POST to /regulardictionarystore/regulardictionaries with a JSON in the body like this:
1
{
2
"words": [
3
{
4
"word": "hello",
5
"expressions": "greeting(hello)",
6
"frequency": 0
7
},
8
{
9
"word": "hi",
10
"expressions": "greeting(hi)",
11
"frequency": 0
12
},
13
{
14
"word": "bye",
15
"expressions": "goodbye(bye)",
16
"frequency": 0
17
},
18
{
19
"word": "thanks",
20
"expressions": "thanks(thanks)",
21
"frequency": 0
22
}
23
],
24
"phrases": [
25
{
26
"phrase": "good afternoon",
27
"expressions": "greeting(good_afternoon)"
28
},
29
{
30
"phrase": "how are you",
31
"expressions": "how_are_you"
32
}
33
]
34
}
Copied!
Example using CURL:
1
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{ \
2
"language" : "en", \
3
"words" : [ \
4
{ \
5
"word" : "hello", \
6
"expressions" : "greeting(hello)", \
7
"frequency" : 0 \
8
}, \
9
{ \
10
"word" : "hi", \
11
"expressions" : "greeting(hi)", \
12
"frequency" : 0 \
13
}, \
14
{ \
15
"word" : "bye", \
16
"expressions" : "goodbye(bye)", \
17
"frequency" : 0 \
18
}, \
19
{ \
20
"word" : "thanks", \
21
"expressions" : "thanks(thanks)", \
22
"frequency" : 0 \
23
} \
24
], \
25
"phrases" : [ \
26
{ \
27
"phrase" : "good afternoon", \
28
"expressions" : "greeting(good_afternoon)" \
29
}, \
30
{ \
31
"phrase" : "how are you", \
32
"expressions" : "how_are_you" \
33
} \
34
] \
35
}' 'http://localhost:7070/regulardictionarystore/regulardictionaries'
Copied!

Dictionary parameters

Name
Description
Required
words
Array of Word
phrases
Array of Phrase
Word.word
String, single word, no spaces.
True
Word.expressions
String, "greeting(hello)": "greeting" is the category of this expression and "hello" is an entity.
Word.frequency
int, Used for a randomizer
Phrase.phrase
String, Spaces allowed
True
Phrase.expressions
String, "greeting(hello)": "greeting" is the category of this expression and "hello" is an entity.
The returned URI is a reference for this specific resource. This resource will be referenced in the bot definition.

2. Creating Behavior Rules

See also Behavior Rules
Next, create a behaviorRule resource to configure the decision making a. Make a POST to /behaviorstore/behaviorsets with a JSON in the body like this:
1
{
2
"behaviorGroups": [
3
{
4
"name": "Smalltalk",
5
"behaviorRules": [
6
{
7
"name": "Welcome",
8
"actions": [
9
"welcome"
10
],
11
"conditions": [
12
{
13
"type": "occurrence",
14
"configs": {
15
"maxTimesOccurred": "0",
16
"behaviorRuleName": "Welcome"
17
}
18
}
19
]
20
},
21
{
22
"name": "Greeting",
23
"actions": [
24
"greet"
25
],
26
"conditions": [
27
{
28
"type": "inputmatcher",
29
"configs": {
30
"expressions": "greeting(*)",
31
"occurrence": "currentStep"
32
}
33
}
34
]
35
},
36
{
37
"name": "Goodbye",
38
"actions": [
39
"say_goodbye",
40
"CONVERSATION_END"
41
],
42
"conditions": [
43
{
44
"type": "inputmatcher",
45
"configs": {
46
"expressions": "goodbye(*)"
47
}
48
}
49
]
50
},
51
{
52
"name": "Thank",
53
"actions": [
54
"thank"
55
],
56
"conditions": [
57
{
58
"type": "inputmatcher",
59
"configs": {
60
"expressions": "thank(*)"
61
}
62
}
63
]
64
},
65
{
66
"name": "how are you",
67
"actions": [
68
"how_are_you"
69
],
70
"conditions": [
71
{
72
"type": "inputmatcher",
73
"configs": {
74
"expressions": "how_are_you"
75
}
76
}
77
]
78
}
79
]
80
}
81
]
82
}
Copied!

Behavior Rules parameters

Name
Description
BehaviorRule.name
String, e.g. "Smalltalk"
BehaviourGroup.behaviorRules
Array of BehaviorRule
BehaviorRule.name
String, e.g. "Greeting"
BehaviorRule.actions
Array of String, e.g. "greet" or "CONVERSATION_END"
BehaviorRule.conditions
Array of RuleChild
RuleChild.type
String, allowed values:
—>"inputmatcher" (has params: "expressions" (Array of String( and "occurrence")
—>"negation" (BehaviorExtension object, has params: "conditions" and "occurrence")
RuleChild.values
HashMap, allowed values:
—>"expressions": String, mandatory. Expression e.g. "greeting(*)" or "how_are_you"
—>"occurrence": String, optional. Allowed values "currentStep"
Negation.conditons
Array of NegationChild
NegationChild.type
String e.g. "occurrence"
NegationChild.values
HashMap, allowed values:
—>"maxTimesOccurred": String, e.g. 1
—>"minTimesOccurred": String, e.g. 1
—>"behaviorRuleName": String
You should again get a return code of 201 with a URI in the location header referencing the newly created Behavior Rules:
eddi://ai.labs.behavior/behaviorstore/behaviorsets/<UNIQUE_BEHAVIOR_ID>?version=<BEHAVIOR_VERSION>
Example:
eddi://ai.labs.behavior/behaviorstore/behaviorsets/5a26d8fd17312628b46119fb?version=1

3. Creating Output

You have guessed it correctly, another POST to /outputstore/outputsets creates the bot's Output with a JSON in the body like this:
1
{
2
"outputSet": [
3
{
4
"action": "welcome",
5
"timesOccurred": 0,
6
"outputs": [
7
{
8
"type": "text",
9
"valueAlternatives": [
10
"Welcome!"
11
]
12
},
13
{
14
"type": "text",
15
"valueAlternatives": [
16
"My name is E.D.D.I"
17
]
18
}
19
],
20
"quickReplies": [
21
{
22
"value": "Hi EDDI",
23
"expressions": "greeting(hi)"
24
},
25
{
26
"value": "Bye EDDI",
27
"expressions": "goodbye(bye)"
28
}
29
]
30
},
31
{
32
"action": "greet",
33
"timesOccurred": 0,
34
"outputs": [
35
{
36
"type": "text",
37
"valueAlternatives": [
38
"Hi there! Nice to meet up! :-)",
39
"Hey you!"
40
]
41
}
42
]
43
},
44
{
45
"action": "greet",
46
"timesOccurred": 1,
47
"outputs": [
48
{
49
"type": "text",
50
"valueAlternatives": [
51
"Did we already say hi ?! Well, twice is better than not at all! ;-)"
52
]
53
}
54
]
55
},
56
{
57
"action": "say_goodbye",
58
"timesOccurred": 0,
59
"outputs": [
60
{
61
"type": "text",
62
"valueAlternatives": [
63
"See you soon!"
64
]
65
}
66
]
67
},
68
{
69
"action": "thank",
70
"timesOccurred": 0,
71
"outputs": [
72
{
73
"type": "text",
74
"valueAlternatives": [
75
"Your Welcome!"
76
]
77
}
78
]
79
},
80
{
81
"action": "how_are_you",
82
"timesOccurred": 0,
83
"outputs": [
84
{
85
"type": "text",
86
"valueAlternatives": [
87
"Pretty good.. having lovely conversations all day long.. :-D"
88
]
89
}
90
]
91
}
92
]
93
}
Copied!
You should again get a return code of 201 with a URI in the location header referencing the newly created output :
eddi://ai.labs.output/outputstore/outputsets/<UNIQUE_OUTPUTSET_ID>?version=<OUTPUTSET_VERSION>
Example :
eddi://ai.labs.output/outputstore/outputsets/5a26d97417312628b46119fc?version=1

4. Creating the Package

Now we will align the just created LifecycleTasks in the Package. Make a POST to /packagestore/packages with a JSON in the body like this:
1
{
2
"packageExtensions": [
3
{
4
"type": "eddi://ai.labs.parser",
5
"extensions": {
6
"dictionaries": [
7
{
8
"type": "eddi://ai.labs.parser.dictionaries.integer"
9
},
10
{
11
"type": "eddi://ai.labs.parser.dictionaries.decimal"
12
},
13
{
14
"type": "eddi://ai.labs.parser.dictionaries.punctuation"
15
},
16
{
17
"type": "eddi://ai.labs.parser.dictionaries.email"
18
},
19
{
20
"type": "eddi://ai.labs.parser.dictionaries.time"
21
},
22
{
23
"type": "eddi://ai.labs.parser.dictionaries.ordinalNumber"
24
},
25
{
26
"type": "eddi://ai.labs.parser.dictionaries.regular",
27
"config": {
28
"uri": "eddi://ai.labs.regulardictionary/regulardictionarystore/regulardictionaries/<UNIQUE_DICTIONARY_ID>?version=<DICTIONARY_VERSION>"
29
}
30
}
31
],
32
"corrections": [
33
{
34
"type": "eddi://ai.labs.parser.corrections.stemming",
35
"config": {
36
"language": "english",
37
"lookupIfKnown": "false"
38
}
39
},
40
{
41
"type": "eddi://ai.labs.parser.corrections.levenshtein",
42
"config": {
43
"distance": "2"
44
}
45
},
46
{
47
"type": "eddi://ai.labs.parser.corrections.mergedTerms"
48
}
49
]
50
},
51
"config": {}
52
},
53
{
54
"type": "eddi://ai.labs.behavior",
55
"config": {
56
"uri": "eddi://ai.labs.behavior/behaviorstore/behaviorsets/<UNIQUE_BEHAVIOR_ID>?version=<BEHAVIOR_VERSION>"
57
}
58
},
59
{
60
"type": "eddi://ai.labs.output",
61
"config": {
62
"uri": "eddi://ai.labs.output/outputstore/outputsets/<UNIQUE_OUTPUTSET_ID>?version=<OUTPUTSET_VERSION>"
63
}
64
}
65
]
66
}
Copied!

Package parameters

Name
Description
Required
packageextensions
Array of PackageExtension
PackageExtension.type
possible values, see table below "Extension Types"
PackageExtension.extensions
Array of Object
False
PackageExtension.config
Config object, but can be empty.
True
Extension Types
Extension
Config
eddi://ai.labs.parser
Dictionaries and/or corrections
Object "extensions" can contain "dictionaries" (Array of Dictionary) and/or "corrections" (Array of Correction)
Object "Dictionary" has params "type" and "config" (optional)
Dictionary.type can reference Regular-Dictionaries "eddi://ai.labs.parser.dictionaries.regular" (needs param "config.uri") or be one of the EDDI out of the box types:
—>"eddi://ai.labs.parser.dictionaries.integer"
—>"eddi://ai.labs.parser.dictionaries.decimal"
—>"eddi://ai.labs.parser.dictionaries.punctuation"
—>"eddi://ai.labs.parser.dictionaries.email"
—>"eddi://ai.labs.parser.dictionaries.time"
—>"eddi://ai.labs.parser.dictionaries.ordinalNumber"
Object "Correction" has params "type" and "config" (optional)
Correction.type can reference one of the EDDI out of the box types:
—>"eddi://ai.labs.parser.corrections.stemming": Object "config" has params "language" (String e.g. "english") and "lookupIfKnown" (Boolean)
—>"eddi://ai.labs.parser.corrections.levenshtein": Object "config" has param "distance" (Integer, e.g. 2)
—>"eddi://ai.labs.parser.corrections.mergedTerms"
eddi://ai.labs.behavior
Object Config contains param uri with Link to a behavior set, e.g. eddi://ai.labs.behavior/behaviorstore/behaviorsets/5a26d8fd17312628b46119fb?version=1
eddi://ai.labs.output
Object Config contains param uri with Link to output set, e.g. eddi://ai.labs.output/outputstore/outputsets/5a26d97417312628b46119fc?version=1
New
Now you can use the new feature of defining properties in the package definition : This can be used by introducing an extension with type eddi://ai.labs.property which has the config model as follows:
1
{
2
"type": "eddi://ai.labs.property",
3
"config": {
4
"setOnActions": [
5
{
6
"actions": "string",
7
"setProperties": [
8
{
9
"name": "string",
10
"fromObjectPath": "string",
11
"scope": "string"
12
}
13
]
14
}
15
]
16
}
17
}
Copied!

Description of eddi://ai.labs.property model

Name
Description
setOnActions.actions
(string) defines which for which actions (triggered by BehaviorRules) these Properties should be set
setOnActions.setProperties
(Array <Property>: ) must respect the Propertymodel: name, fromObjectPath and scope.
setOnActions.setProperties.name
(string) name of the Property.
setOnActions.setProperties.fromObjectPath
(string) path to the json object.
setOnActions.setProperties.scope
(string) Possible values step, conversation and longTerm .

Example of eddi://ai.labs.property

1
{
2
"packageExtensions": [
3
...
4
{
5
"type": "eddi://ai.labs.property",
6
"config": {
7
"setOnActions": [
8
{
9
"actions": "currentWeather",
10
"setProperties": [
11
{
12
"name": "city",
13
"fromObjectPath": "memory.current.input",
14
"scope": "longTerm"
15
}
16
]
17
}
18
]
19
}
20
},
21
...
22
{
23
"type": "eddi://ai.labs.property",
24
"config": {
25
"setOnActions": [
26
{
27
"actions": "currentWeather",
28
"setProperties": [
29
{
30
"name": "currentWeather",
31
"fromObjectPath": "memory.current.httpCalls.currentWeather",
32
"scope": "conversation"
33
}
34
]
35
}
36
]
37
}
38
},
39
...
40
]
41
}
Copied!
You should again get a return code of 201 with an URI in the location header referencing the newly created package format
eddi://ai.labs.package/packagestore/packages/<UNIQUE_PACKAGE_ID>?version=<PACKAGE_VERSION>
Example
eddi://ai.labs.package/packagestore/packages/5a2ae60f17312624f8b8a445?version=1

5. Creating a Bot

Make a POST to /botstore/bots with a JSON like this:
1
{
2
"packages": [
3
"eddi://ai.labs.package/packagestore/packages/<UNIQUE_PACKAGE_ID>?version=<PACKAGE_VERSION>"
4
],
5
"channels": []
6
}
Copied!

Bot parameters

Name
Description
packages
Array of String, references to Packages
channels
Array of Channel,
Channel.type
String, e.g. "eddi://ai.labs.channel.facebook"
Channel.config
Config Object. For "Facebook" this object has the params "appSecret" (String), "verificationToken" (String), "pageAccessToken" (String)
b. You should again get a return code of 201 with a URI in the location header referencing the newly created bot :
eddi://ai.labs.bot/botstore/bots/<UNIQUE_BOT_ID>?version=<BOT_VERSION>
Example:
eddi://ai.labs.bot/botstore/bots/5a2ae68a17312624f8b8a446?version=1
See also the API documentation at http://localhost:7070/view#!/configurations/createBot

6. Launching the Bot

Finally, we are ready to let the bot fly. From here on, you have the possibility to let an UI do it for you or you do it step by step.
The UI that automates these steps can be reached here: /chat/unrestricted/<UNIQUE_BOT_ID>
Otherwise via REST:
  1. 1.
    Deploy the Bot:
    Make a POST to /administration/unrestricted/deploy/<UNIQUE_BOT_ID>?version=<BOT_VERSION>
    You will receive a 202 http code.
  2. 2.
    Since deployment could take a while it has been made asynchronous.
  3. 3.
    Make a GET to /administration/unrestricted/deploymentstatus/<UNIQUE_BOT_ID>?version=<BOT_VERSION> to find out the status of deployment.
NOT_FOUND, IN_PROGRESS, ERROR and READY is what you can expect to be returned in the body.
  1. 1.
    As soon as the Bot is deployed and has READY status, make a POST to /bots/unrestricted/<UNIQUE_BOT_ID>
    1. 1.
      You will receive a 201 with the URI for the newly created Conversation, like this:
      1. 1.
        e.g.
        eddi://ai.labs.conversation/conversationstore/conversations/<UNIQUE_CONVERSATION_ID>
  2. 2.
    Now it's time to start talking to our Bot 1. Make a POST to /bots/unrestricted/<UNIQUE_BOT_ID>/<UNIQUE_CONVERSATION_ID>
Option 1: is to hand over the input text as contentType text/plain. Include the User Input in the body as text/plain (e.g. Hello)
Option 2: is to hand over the input as contentType application/json, which also allows you to handover context information that you can use with the eddi configurations 1. Include the User Input in the body as application/json (e.g. Hello)
1
{
2
"input": "some user input"
3
}
Copied!
  1. 1.
    You have two query params you can use to config the returned output 1. returnDetailed - default is false - will return all sub results of the entire conversation steps, otherwise only public ones such as input, action, output & quickreplies 2. returnCurrentStepOnly - default is true - will return only the latest conversation step that has just been processed, otherwise returns all conversation steps since the beginning of this conversation
  2. 2.
    The output from the bot will be returned as JSON
  3. 3.
    If you are interested in fetching the conversationmemory at any given time, make a GET to /bots/unrestricted/<UNIQUE_BOT_ID>/<UNIQUE_CONVERSATION_ID>?returnDetailed=true (the query param is optional, default is false)
If you made it till here, CONGRATULATIONS, you have created your first Chatbot with EDDI !
By the way you can use the attached postman collection below to do all of the steps mentioned above by clicking send on each request in postman.
  1. 1.
    Create dictionary (greetings)
  2. 2.
    Create behaviourSet
  3. 3.
    Create outputSet
  4. 4.
    Creating package
  5. 5.
    Creating bot
  6. 6.
    Deploy the bot
  7. 7.
    Create conversation
  8. 8.
    Say Hello to the bot
Creating and chatting with a bot.postman_collection.json
21KB
Binary
Example to download
Last modified 5mo ago