Creating your first Chatbot

Owned by Gregor Jarisch
Last updated: Jul 17, 2018Version comment
16 min read
Version: 4.3.x


Steps to create a Chatbot in EDDI

Prerequisites: Up and Running instance of EDDI (See: Getting started)

General

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.

Bot Config

A chatbot consists of the following elements:

  1. A (Regular-) Dictionary to define the inputs from the users as well its meanings resp. categories (called Expressions in EDDI).
  2. Behavior Rules creating Actions based on decision making with predefined as well as custom conditions.
  3. Output to answer the users request based on the results from the behavior rule execution.
  4. Package to align the LifecycleTasks (such as the parser, behavior evaluation, output generation, ...)
  5. A Bot to align different Packages and Channels.

Follow these steps to create the configuation files you will need:

1. Creating a Regular Dictionary

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 an json in the body like this:

regular dictionary json 
{
  "language" : "en",
  "words" : [
    {
      "word" : "hello",
      "exp" : "greeting(hello)",
      "frequency" : 0
    },
    {
      "word" : "hi",
      "exp" : "greeting(hi)",
      "frequency" : 0
    },
    {
      "word" : "bye",
      "exp" : "goodbye(bye)",
      "frequency" : 0
    },
    {
      "word" : "thanks",
      "exp" : "thanks(thanks)",
      "frequency" : 0
    }
  ],
  "phrases" : [
    {
      "phrase" : "good afternoon",
      "exp" : "greeting(good_afternoon)"
    },
    {
      "phrase" : "how are you",
      "exp" : "how_are_you"
    }
  ]
}


e.g. as CURL

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{ \ 
   "language" : "en", \ 
   "words" : [ \ 
     { \ 
       "word" : "hello", \ 
       "exp" : "greeting(hello)", \ 
       "frequency" : 0 \ 
     }, \ 
     { \ 
       "word" : "hi", \ 
       "exp" : "greeting(hi)", \ 
       "frequency" : 0 \ 
     }, \ 
     { \ 
       "word" : "bye", \ 
       "exp" : "goodbye(bye)", \ 
       "frequency" : 0 \ 
     }, \ 
     { \ 
       "word" : "thanks", \ 
       "exp" : "thanks(thanks)", \ 
       "frequency" : 0 \ 
     } \ 
   ], \ 
   "phrases" : [ \ 
     { \ 
       "phrase" : "good afternoon", \ 
       "exp" : "greeting(good_afternoon)" \ 
     }, \ 
     { \ 
       "phrase" : "how are you", \ 
       "exp" : "how_are_you" \ 
     } \ 
   ] \ 
 }' 'http://localhost:7070/regulardictionarystore/regulardictionaries'


Parameters, Dictionary

See also the API documentation at http://localhost:7070/view#!/configurations/createRegularDictionary

Parameter
langugaeString, mandatory
wordsArray of Word
phrasesArray of Phrase
Word.wordString, required. Single word, no spaces.
Word.expString, required. "greeting(hello)": "greeting" is the category of this expression and "hello" is an entity.
Word.frequencyint, required. Used for a randomizer
Phrase.phraseString, required. Spaces allowed
Phrase.expString, required. "greeting(hello)": "greeting" is the category of this expression and "hello" is an entity.


        b. The API returns with HTTP code 201 an URI in the location header referencing the newly created dictionary
            with format eddi://ai.labs.regulardictionary/regulardictionarystore/regulardictionaries/<UNIQUE_DICTIONARY_ID>?version=<DICTIONARY_VERSION>
            e.g. eddi://ai.labs.regulardictionary/regulardictionarystore/regulardictionaries/5a26d25817312628b46119f9?version=1

Structure of Identifiers

The returned URI is a reference for this specific resource. This recourse will be referenced in the bot definition.

Part of URIMeaning
eddi://This URI is related to a resource with in EDDI
ai.labs.regulardictionaryType of resource
/regulardictionarystore/regulardictionariesAPI path
<UNIQUE_DICTIONARY_ID>ID of the resources
<DICTIONARY_VERSION>

Version of this resource
(each update operation will create a new version of the resource)

2. Creating Behavior Rules

See also Behavior Rules

Next, create a behavior rule resource to configure the decision making
        a. Make a POST to /behaviorstore/behaviorsets
        With an json in the body like this:

Behavior Rules 
{
  "behaviorGroups": [
    {
      "name": "Smalltalk",
      "behaviorRules": [
        {
          "name": "Welcome",
          "actions": [
            "welcome"
          ],
          "children": [
            {
              "type": "occurrence",
              "values": {
                "maxTimesOccurred": 0,
                "behaviorRuleName": "Welcome"
              }
            }
          ]
        },
        {
          "name": "Greeting",
          "actions": [
            "greet"
          ],
          "children": [
            {
              "type": "inputmatcher",
              "values": {
                "expressions": "greeting(*)",
                "occurrence": "currentStep"
              }
            }
          ]
        },
        {
          "name": "Goodbye",
          "actions": [
            "say_goodbye",
            "CONVERSATION_END"
          ],
          "children": [
            {
              "type": "inputmatcher",
              "values": {
                "expressions": "goodbye(*)"
              }
            }
          ]
        },
        {
          "name": "Thank",
          "actions": [
            "thank"
          ],
          "children": [
            {
              "type": "inputmatcher",
              "values": {
                "expressions": "thank(*)"
              }
            }
          ]
        },
        {
          "name": "how are you",
          "actions": [
            "how_are_you"
          ],
          "children": [
            {
              "type": "inputmatcher",
              "values": {
                "expressions": "how_are_you"
              }
            }
          ]
        }
      ]
    }
  ]
}

Parameters, Behavior Rules

See also the API documentation at http://localhost:7070/view#!/configurations/createBehaviorRuleSet

Parameter
behaviorGroups

Array of BehaviourGroups

BehaviourGroup.name

String, e.g. "Smalltalk"

BehaviourGroup.behaviorRules

Array of BehaviorRule
BehaviorRule.nameString, e.g. "Greeting"
BehaviorRule.actionsArray of String, e.g. "greet" or "CONVERSATION_END"
BehaviorRule.childrenArray of RuleChild
RuleChild.typeString, allowed values:
  • "inputmatcher" (has params: "expressions" (Array of String( and "occurrence")
  • "negation" (BehaviorExtension object, has params: "children" and "occurrence")
RuleChild.valuesHashMap, allowed values:
  • "expressions": String, mandatory. Expression e.g. "greeting(*)" or "how_are_you"
  • "occurrence": String, optional. Allowed values "currentStep"
Negation.childrenArray of NegationChild
NegationChild.typeString e.g. "occurrence"
NegationChild.valuesHashMap, allowed values:
  • "maxTimesOccurred": Integer, e.g. 1
  • "minTimesOccurred": Integer, e.g. 1
  • "behaviorRuleName": String


b. You should again get a return code of 201 with an URI in the location header referencing the newly created behavior rules
            eddi://ai.labs.behavior/behaviorstore/behaviorsets/<UNIQUE_BEHAVIOR_ID>?version=<BEHAVIOR_VERSION>
            e.g. eddi://ai.labs.behavior/behaviorstore/behaviorsets/5a26d8fd17312628b46119fb?version=1

3. Creating Output

See also Output Configuration.

You have guessed correctly, another POST to /outputstore/outputsets create the bot's Output.

With an JSON in the body like this:

Output 
{
  "outputSet": [
    {
      "action": "welcome",
      "timesOccurred": 0,
      "outputs": [
        {
          "type": "text",
          "valueAlternatives": [
            "Welcome!"
          ]
        },
        {
          "type": "text",
          "valueAlternatives": [
            "My name is E.D.D.I"
          ]
        }
      ],
      "quickReplies": [
        {
          "value": "Hi EDDI",
          "expressions": "greeting(hi)"
        },
        {
          "value": "Bye EDDI",
          "expressions": "goodbye(bye)"
        }
      ]
    },
    {
      "action": "greet",
      "timesOccurred": 0,
      "outputs": [
        {
          "type": "text",
          "valueAlternatives": [
            "Hi there! Nice to meet up! :-)",
            "Hey you!"
          ]
        }
      ]
    },
    {
      "action": "greet",
      "timesOccurred": 1,
      "outputs": [
        {
          "type": "text",
          "valueAlternatives": [
            "Did we already say hi ?! Well, twice is better than not at all! ;-)"
          ]
        }
      ]
    },
    {
      "action": "say_goodbye",
      "timesOccurred": 0,
      "outputs": [
        {
          "type": "text",
          "valueAlternatives": [
            "See you soon!"
          ]
        }
      ]
    },
    {
      "action": "thank",
      "timesOccurred": 0,
      "outputs": [
        {
          "type": "text",
          "valueAlternatives": [
            "Your Welcome!"
          ]
        }
      ]
    },
    {
      "action": "how_are_you",
      "timesOccurred": 0,
      "outputs": [
        {
          "type": "text",
          "valueAlternatives": [
            "Pretty good.. having lovely conversations all day long.. :-D"
          ]
        }
      ]
    }
  ]
}


Parameters, Output

See also the API documentation at http://localhost:7070/view#!/configurations/createOutputSet

Parameter
outputsetArray of Output
Output.actionString, e.g. "welcome"
Output.timesOccurredInteger, e.g. 0 or 1
Output.outputsArray of OutputValue
OutputValue.typeString, e.g. "text"
OutputValue.valueAlternativesArray of String, e.g. ["Welcome!", "Hello!"]
Output.quickRepliesArray of QuickReply
QuickReply.valueString, e.g. "Hi""
QuickReply.expressionsString, e.g. "greeting(hi)"


b. You should again get a return code of 201 with an URI in the location header referencing the newly created output
            eddi://ai.labs.output/outputstore/outputsets/<UNIQUE_OUTPUTSET_ID>?version=<OUTPUTSET_VERSION>
            e.g. 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:

Package 
{
  "packageExtensions": [
    {
      "type": "eddi://ai.labs.normalizer",
      "config": {
        "allowedChars": "1234567890abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ !?:;.,",
        "convertUmlaute": "true"
      }
    },
    {
      "type": "eddi://ai.labs.parser",
      "extensions": {
        "dictionaries": [
          {
            "type": "eddi://ai.labs.parser.dictionaries.integer"
          },
          {
            "type": "eddi://ai.labs.parser.dictionaries.decimal"
          },
          {
            "type": "eddi://ai.labs.parser.dictionaries.punctuation"
          },
          {
            "type": "eddi://ai.labs.parser.dictionaries.email"
          },
          {
            "type": "eddi://ai.labs.parser.dictionaries.time"
          },
          {
            "type": "eddi://ai.labs.parser.dictionaries.ordinalNumber"
          },
          {
            "type": "eddi://ai.labs.parser.dictionaries.regular",
            "config": {
              "uri": "eddi://ai.labs.regulardictionary/regulardictionarystore/regulardictionaries/<UNIQUE_DICTIONARY_ID>?version=<DICTIONARY_VERSION>"
            }
          }
        ],
        "corrections": [
          {
            "type": "eddi://ai.labs.parser.corrections.stemming",
            "config": {
              "language": "english",
              "lookupIfKnown": "false"
            }
          },
          {
            "type": "eddi://ai.labs.parser.corrections.levenshtein",
            "config": {
              "distance": "2"
            }
          },
          {
            "type": "eddi://ai.labs.parser.corrections.mergedTerms"
          }
        ]
      },
      "config": {}
    },
    {
      "type": "eddi://ai.labs.behavior",
      "config": {
        "uri": "eddi://ai.labs.behavior/behaviorstore/behaviorsets/<UNIQUE_BEHAVIOR_ID>?version=<BEHAVIOR_VERSION>"
      }
    },
    {
      "type": "eddi://ai.labs.output",
      "config": {
        "uri": "eddi://ai.labs.output/outputstore/outputsets/<UNIQUE_OUTPUTSET_ID>?version=<OUTPUTSET_VERSION>"
      }
    }
  ]
}

Parameters, Package

See also the API documentation at http://localhost:7070/view#!/configurations/createPackage

Parameter
packageextensionsArray of PackageExtension
PackageExtension.typepossible values, see box "Extension Types" below
PackageExtension.extensionsArray of Object, optional.
PackageExtension.configConfig object, Required, but can be empty.
ExtensionConfig
eddi://ai.labs.normalizer

To normalize the text, e.g. throw away not allowed characters or convert umlauts.

Object "config" has the following parameters:

  • "allowedChars": String, e.g. "1234567890abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ !?:;.,",
  • "convertUmlaute": Boolean, e.g. "true"
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:

Object "Correction" has params "type" and "config" (optional)
Correction.type can reference one of the EDDI out of the box types:

eddi://ai.labs.behaviorObject Config contains param uri with Link to behavior set, e.g. eddi://ai.labs.behavior/behaviorstore/behaviorsets/5a26d8fd17312628b46119fb?version=1
eddi://ai.labs.outputObject Config contains param uri with Link to output set, e.g. eddi://ai.labs.output/outputstore/outputsets/5a26d97417312628b46119fc?version=1


b. 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>
            e.g. eddi://ai.labs.package/packagestore/packages/5a2ae60f17312624f8b8a445?version=1

5. Creating a Bot

Make a POST to /botstore/bots

with a JSON like this:

bot 
{
  "packages" : [
    "eddi://ai.labs.package/packagestore/packages/<UNIQUE_PACKAGE_ID>?version=<PACKAGE_VERSION>"
  ],    "channels" : []
}

Parameters, Bot

See also the API documentation at http://localhost:7070/view#!/configurations/createBot

Parameter
packagesArray of String, reference to the package
channelsArray of Channel, optional
Channel.typeString, e.g. "eddi://ai.labs.channel.facebook"
Channel.configConfig 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 an URI in the location header referencing the newly created bot
            format eddi://ai.labs.bot/botstore/bots/<UNIQUE_BOT_ID>?version=<BOT_VERSION>
            e.g. eddi://ai.labs.bot/botstore/bots/5a2ae68a17312624f8b8a446?version=1

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. Deploy the Bot
    Make a POST to /administration/unrestricted/deploy/<UNIQUE_BOT_ID>?version=<BOT_VERSION>
    You will receive a 202 http code
    1. Since deployment could take awhile it has been made asynchronous
    2. Make a Get to /administration/unrestricted/deploymentstatus/<UNIQUE_BOT_ID>?version=<BOT_VERSION> to find out when it is ready to go
    3. NOT_FOUND, IN_PROGRESS, ERROR and READY is what you can expect to be returned in the body

  2. As soon as the Bot is deployed and READY, make a POST to /bots/unrestricted/<UNIQUE_BOT_ID>
    1. You will receive a 201 with the URI for the newly created Conversation, like this:
      1. e.g.
        eddi://ai.labs.conversation/conversationstore/conversations/<UNIQUE_CONVERSATION_ID>

  3. Now it's time to start talking to our Bot
    1. Make a POST to /bots/unrestricted/<UNIQUE_BOT_ID>/<UNIQUE_CONVERSATION_ID>
      1. Option 1 is to hand over the input text as contentType text/plain
        1. Include the User Input in the body as text/plain (e.g. Hello)
      2. 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)

          {
  "input": "some user input"
}
      3. 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. The output from the bot will be returned as json
    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 E.D.D.I (breites Grinsen)

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 - Create dictionary (greetings)
2 - Create behaviourSet
3 - Create outputSet
4 - Creating package
5 - Creating bot
6 - Deploy the bot
7 - Create conversation
8 - Say Hello to the bot

Additional info :

Using collections in postman