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 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
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:
Last updated
Was this helpful?