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 conversationId you will be able to send a message to the Chatbot through a POST and to receive the message through A GET, while having the capacity to send context information through the body of the POST request as well.
Important: EDDI has a great feature for conversations with chatbots, 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
(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
NoteconversationProperties 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 locationHTTP Header of the response, you will use that later to submit messages to the Chabot to maintain a conversation.
(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
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.
