Conversations

Conversations
In this section we will talk about how to send/receive messages from a Chatbot, the first step is the creation of the conversation, once you have the conversation Id you will be able to send a message to the Chabot through a POST and to receive the message through A GET, while having a the capacity to send context information through the body of the POST request as well.
Important EDDI has a great feature for conversations with chat bots, it's the possibility to go back in time by using the two API endpoints : /undo and /redo !
Creating/initiating a conversation :
 Create a Conversation with a Chatbot REST API Endpoint
Element
Tags
HTTP Method
POST
Api endpoint
/bots/{environment}/{botId}
{environment}
(Path parameter):String Deployment environment (e.g: restricted,unrestricted,test)
{botId}
(Path parameter):String Id of the bot that you wish to start conversation with.
Response Model
{
  "botId": "string",
  "botVersion": Integer,
  "userId": "string",
  "environment": "string",
  "conversationState": "string",
  "redoCacheSize": 0,
  "conversationOutputs": [
                "input"    :    "string",
                "expressions"    :    <arrayOfString>,
                "intents" :        <arrayOfString>,
                "actions"    :    <arrayOfString>,
                "httpCalls"    :    {JsonObject},
                "properties" :    <arrayOfString>,
                "output" : "string"
    ],
  "conversationProperties": {
        "<nameOfProperty>" : {
      "name" : "string",
      "value" : "string" | {JsonObject},
      "scope" : "string"
    }},
  "conversationSteps": [
    {
      "conversationStep": [
        {
          "key": "string",
          "value": {}
        }
      ],
      "timestamp": "dateTime"
    }
  ]
}
Description of the Conversation response model
Element
Tags
botId
(String) The id of the bot that sent the reply.
botVersion
(integer) The version of the bot that sent the reply.
userId
(String) The id of the user who interacted with the bot.
environment
(String) the name of the environment where the bot is deployed
conversationState
(String) The state of the current conversation, could be READY, 
IN_PROGRESS, 
ENDED, 
EXECUTION_INTERRUPTED, 
ERROR
redoCount
(integer) if undo has been performed, this number indicates how many times redo can be done (=times undo has been triggered)
conversationOutputs
(Array: <conversationOutput>) Array of conversationOutput
conversationOutput.input
(String) The user's input.
conversationOutput.expressions
(Array: <String>) an array of the expressions involved in the creation of this reply (output).
conversationOutput.intents
(Array: <String>) an array of the intents involved in the creation of this reply (output).
conversationOutput.actions
(Array: <String>) an array of the actions involved in the creation of this reply (output).
conversationOutput.httpCalls
(Array: <JsonObject>) an array of the httpCalls objects involved in the creation of this reply (output).
conversationOutput.properties
(Array: <JsonObject>) the list of available properties in the current conversation.
conversationOutput.output
(String) The final bot's output
conversationProperties
(Array: <>) Array of conversationProperty, <nameOfProperty> is a dynamic value that represents the name of the property
<nameOfProperty>.name
(String) name of the property.
<nameOfProperty>.value
(String|JsonObject) value of the property.
<nameOfProperty>.scope
(String) scope can be 
step (=valid one interaction [user input to user output]), 
conversation (=valid for the entire conversation), 
longTerm (=valid across conversations [based on given userId])
conversationSteps
(Array: <conversationStep>) Array of conversationStep.
conversationStep.key
(String) the element key in the conversationStep e.g key : input:initial, actions
conversationStep.value
(String) the element value of the conversationStep e.g in case of actionq as key it could be an array string [ "current_weather_in_city" ].
timestamp.timestamp
(dateTime) the timestamp in (ISO 8601) format
Note conversationProperties can also be used in output templating e.g: [[${properties.city}]].
Sample Response
{
  "botId": "5bf5418c46e0fb000b7636d0",
  "botVersion": 10,
  "userId": "anonymous-zj1p1GDtM5",
  "environment": "unrestricted",
  "conversationState": "READY",
  "redoCacheSize": 0,
  "conversationOutputs": [
    {
      "input": "madrid",
      "expressions": "unknown(madrid)",
      "intents": [
        "unknown"
      ],
      "actions": [
        "current_weather_in_city"
      ],
      "httpCalls": {
        "currentWeather": {
          "coord": {
            "lon": -3.7,
            "lat": 40.42
          },
          "weather": [
            {
              "id": 800,
              "main": "Clear",
              "description": "clear sky",
              "icon": "01n"
            }
          ],
          "base": "stations",
          "main": {
            "temp": 10.86,
            "pressure": 1019,
            "humidity": 66,
            "temp_min": 8.33,
            "temp_max": 13.33
          },
          "visibility": 10000,
          "wind": {
            "speed": 5.7,
            "deg": 240
          },
          "clouds": {
            "all": 0
          },
          "dt": 1551735805,
          "sys": {
            "type": 1,
            "id": 6443,
            "message": 0.0049,
            "country": "ES",
            "sunrise": 1551681788,
            "sunset": 1551723011
          },
          "id": 3117735,
          "name": "Madrid",
          "cod": 200
        }
      },
      "properties": {
        "currentWeather": {
          "coord": {
            "lon": -3.7,
            "lat": 40.42
          },
          "weather": [
            {
              "id": 800,
              "main": "Clear",
              "description": "clear sky",
              "icon": "01n"
            }
          ],
          "base": "stations",
          "main": {
            "temp": 10.86,
            "pressure": 1019,
            "humidity": 66,
            "temp_min": 8.33,
            "temp_max": 13.33
          },
          "visibility": 10000,
          "wind": {
            "speed": 5.7,
            "deg": 240
          },
          "clouds": {
            "all": 0
          },
          "dt": 1551735805,
          "sys": {
            "type": 1,
            "id": 6443,
            "message": 0.0049,
            "country": "ES",
            "sunrise": 1551681788,
            "sunset": 1551723011
          },
          "id": 3117735,
          "name": "Madrid",
          "cod": 200
        },
        "city": "madrid"
      },
      "output": [
        "The current weather situation of madrid is clear sky at 10.86 °C"
      ]
    }
  ],
  "conversationProperties": {
    "city": {
      "name": "city",
      "value": "madrid",
      "scope": "conversation"
    }
  },
  "conversationSteps": [
    {
      "conversationStep": [
        {
          "key": "input:initial",
          "value": "madrid"
        },
        {
          "key": "actions",
          "value": [
            "current_weather_in_city"
          ]
        },
        {
          "key": "output:text:current_weather_in_city",
          "value": "The current weather situation of madrid is clear sky at 10.86 °C"
        }
      ],
      "timestamp": 1551736024776
    }
  ]
}
The conversationId will be provided through the location HTTP Header of the response, you will use that later to submit messages to the Chabot to maintain a conversation.
Example :
Request URL:
http://localhost:7070/bots/unrestricted/5ad2ab182de29719b44a792a
Response Body
no content
Response Code
201
Response Headers
{
  "access-control-allow-origin": "*",
  "date": "Sun, 15 Apr 2018 01:45:09 GMT",
  "access-control-allow-headers": "authorization, Content-Type",
  "content-length": "0",
  "location": "eddi://ai.labs.conversation/conversationstore/conversations/5ad2aea52de29719b44a792c",
  "access-control-allow-methods": "GET, PUT, POST, DELETE, PATCH, OPTIONS",
  "access-control-expose-headers": "location",
  "content-type": null
}
Send/receive messages
Send a message
Send message in a conversation with a Chatbot REST API Endpoint
Element
Tags
HTTP Method
POST
Api endpoint
/bots/{environment}/{botId}/{conversationId}
{environment}
(Path parameter):String Deployment environment (e.g: restricted,unrestricted,test)
botId
(Path parameter):String Id of the bot that you wish to continue a conversation with.
conversationId
(Path parameter): String Id of the conversation that you wish to send the message to.
returnDetailed
(Query parameter):Boolean - Default : false
returnCurrentStepOnly
(Query parameter):Boolean - Default : true
Request Body
JSON Object , example : { "input": "the message", "context": {} }
The context here is where you pass context variables that can be evaluated by EDDI, we will be explaining this in more details in Passing Context Information
Example :
Request URL
http://localhost:7070/bots/restricted/5aaf90e29f7dd421ac3c7dd4/5add1fe8a081a228a0588d1c?returnDetailed=false&returnCurrentStepOnly=true
Request Body
{
  "input": "Hi!",
  "context": {}
}
Response Code
200
Response Body
{
  "botId": "5aaf90e29f7dd421ac3c7dd4",
  "botVersion": 1,
  "environment": "restricted",
  "conversationState": "READY",
  "redoCacheSize": 0,
  "conversationSteps": [
    {
      "conversationStep": [
        {
          "key": "input:initial",
          "value": "Hi!"
        }
      ],
      "timestamp": 1524441253098
    }
  ]
}
Response Headers
{
  "access-control-allow-origin": "*",
  "date": "Sun, 22 Apr 2018 23:54:12 GMT",
  "access-control-allow-headers": "authorization, Content-Type",
  "content-length": "321",
  "access-control-allow-methods": "GET, PUT, POST, DELETE, PATCH, OPTIONS",
  "content-type": "application/json;resteasy-server-has-produces=true"
}
Receive a message
Receive message in a conversation with a Chatbot REST API Endpoint
Element
Tags
HTTP Method
GET
Api endpoint
/bots/{environment}/{botId}/{conversationId}
{environment}
(Path parameter):String Deployment environment (e.g: restricted,unrestricted,test)
{botId}
(Path parameter):String Id of the bot that you wish to continue a conversation with.
{conversationId}
(Path parameter): String Id of the conversation that you wish to receive a the message from.
returnDetailed
(Query parameter):Boolean - Default : false
​
​
Example
Request URL:
http://localhost:7070/bots/unrestricted/5aaf90e29f7dd421ac3c7dd4/5add1fe8a081a228a0588d1c?returnDetailed=false
Response Body
{
  "botId": "5aaf90e29f7dd421ac3c7dd4",
  "botVersion": 1,
  "environment": "restricted",
  "conversationState": "READY",
  "redoCacheSize": 0,
  "conversationSteps": [
    {
      "conversationStep": [
        {
          "key": "actions",
          "value": [
            "global_menu"
          ]
        },
        {
          "key": "output:text:global_menu",
          "value": "What do you want to do?"
        },
        {
          "key": "quickReplies:global_menu",
          "value": [
            {
              "value": "Show me your skillz",
              "expressions": "confirmation(show_skills)",
              "default": false
            },
            {
              "value": "Tell me a joke",
              "expressions": "trigger(tell_a_joke)",
              "default": false
            }
          ]
        }
      ],
      "timestamp": 1524441064450
    },
    {
      "conversationStep": [
        {
          "key": "input:initial",
          "value": "Hi!"
        }
      ],
      "timestamp": 1524441253098
    }
  ]
}
Response Code
200
Response Headers
{
  "access-control-allow-origin": "*",
  "date": "Mon, 23 Apr 2018 00:07:25 GMT",
  "cache-control": "no-cache",
  "access-control-allow-headers": "authorization, Content-Type",
  "content-length": "891",
  "access-control-allow-methods": "GET, PUT, POST, DELETE, PATCH, OPTIONS",
  "content-type": "application/json"
}
Undo and redo :
The undo and redo methods basically allow you to return a step back in a conversation, this is done by sending a POST along with bot and conversation ids to /bots/{environment}/{botId}/redo/{conversationId} endpoint, the GET call of the same endpoint with the same parameters will allow you to see if the last submitted undo/redo was successful by receiving a true or false in the response body.
Undo and redo in a conversation REST API Endpoint
Element
Tags
HTTP Method
POST
Api endpoint
/bots/{environment}/{botId}/[undo/redo]/{conversationId}
{environment}
(Path parameter):String Deployment environment (e.g: restricted,unrestricted,test)
{botId}
(Path parameter):String Id of the bot that you wish to continue a conversation with.
{conversationId}
(Path parameter): String Id of the conversation that you wish to undo/redo the last conversation step.
Example (undo)
Request URL:
http://localhost:7070/bots/restricted/5aaf98e19f7dd421ac3c7de9/undo/5ade58dda081a23418503d6f
Response Body
no content
Response Code
200
Response Headers
{
  "access-control-allow-origin": "*",
  "date": "Mon, 23 Apr 2018 22:20:57 GMT",
  "access-control-allow-headers": "authorization, Content-Type",
  "content-length": "0",
  "access-control-allow-methods": "GET, PUT, POST, DELETE, PATCH, OPTIONS",
  "content-type": null
}
Sample bot:
Weather-bot-v2.zip
weather_bot_v2.zip - 5KB

Semantic Parser

Passing context information

Last updated 2 months ago

Element	Tags
HTTP Method	`POST`
Api endpoint	`/bots/{environment}/{botId}`
{environment}	(`Path` parameter):`String` Deployment environment (e.g: `restricted`,`unrestricted`,`test`)
{botId}	(`Path` parameter):`String Id` of the bot that you wish to start conversation with.

Element	Tags
botId	(`String`) The id of the bot that sent the reply.
botVersion	(`integer`) The version of the bot that sent the reply.
userId	(`String`) The id of the user who interacted with the bot.
environment	(`String`) the name of the environment where the bot is deployed
conversationState	(`String`) The state of the current conversation, could be `READY`, `IN_PROGRESS`, `ENDED`, `EXECUTION_INTERRUPTED`, `ERROR`
redoCount	(`integer`) if undo has been performed, this number indicates how many times redo can be done (=times undo has been triggered)
conversationOutputs	(`Array`: <`conversationOutput`>) Array of `conversationOutput`
conversationOutput.input	(`String`) The user's input.
conversationOutput.expressions	(`Array`: <`String`>) an array of the `expressions` involved in the creation of this reply (output).
conversationOutput.intents	(`Array`: <`String`>) an array of the `intents` involved in the creation of this reply (output).
conversationOutput.actions	(`Array`: <`String`>) an array of the `actions` involved in the creation of this reply (output).
conversationOutput.httpCalls	(`Array`: <`JsonObject`>) an array of the `httpCalls` objects involved in the creation of this reply (output).
conversationOutput.properties	(`Array`: <`JsonObject`>) the list of available properties in the current conversation.
conversationOutput.output	(`String`) The final bot's output
conversationProperties	(`Array`: <>) Array of `conversationProperty`, <`nameOfProperty`> is a dynamic value that represents the name of the property
<nameOfProperty>.name	(`String`) name of the property.
<nameOfProperty>.value	(`String`\|`JsonObject`) value of the property.
<nameOfProperty>.scope	(`String`) scope can be `step` (=valid one interaction [user input to user output]), `conversation` (=valid for the entire conversation), `longTerm` (=valid across conversations [based on given userId])
conversationSteps	(`Array`: <`conversationStep`>) Array of `conversationStep`.
conversationStep.key	(`String`) the element key in the conversationStep e.g key : input:initial, actions
conversationStep.value	(`String`) the element value of the conversationStep e.g in case of `actionq` as `key` it could be an array string `[ "current_weather_in_city" ]`.
timestamp.timestamp	(`dateTime`) the timestamp in (ISO 8601) format

Element	Tags
HTTP Method	`POST`
Api endpoint	`/bots/{environment}/{botId}/{conversationId}`
{environment}	(`Path` parameter):`String` Deployment environment (e.g: `restricted`,`unrestricted`,`test`)
botId	(`Path` parameter):`String Id` of the bot that you wish to continue a conversation with.
conversationId	(`Path` parameter): `String Id` of the conversation that you wish to send the message to.
returnDetailed	(`Query` parameter):`Boolean` - Default : `false`
returnCurrentStepOnly	(`Query` parameter):`Boolean` - Default : `true`
Request Body	JSON Object , example : `{ "input": "the message", "context": {} }` The `context` here is where you pass context variables that can be evaluated by EDDI, we will be explaining this in more details in Passing Context Information