Conversations in EDDI
- Jalal Sordo
- Gregor Jarisch
In this section we will talk about how to send to and 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 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 !
1 - Creating/initiating a conversation :
| HTTP Method | POST |
|---|---|
| Api endpoint | /bots/{environment}/{botId} |
| {environment} | (Path parameter):String Deployment environment (e.g: |
| {botId} | (Path parameter):String Id of the bot that you wish to start conversation with. |
The conversation Id will be provided through the location header, you will use that later to submit messages to the chatbot to maintain a conversation.
Example :
Start conversation with a chatbot.
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
}
2 - Send and receive messages:
Send :
| HTTP Method | POST |
|---|---|
| Api endpoint | /bots/{environment}/{botId}/{conversationId} |
| {environment} | (Path parameter):String Deployment environment (e.g: |
| {botId} | (Path parameter):String Id of the bot that you wish tosend a message to. |
| {conversationId} | (Path parameter):String id of the conversation that you wish to add the message to. |
| returnDetailed | (Query parameter):Boolean - Default : false |
| returnCurrentStepOnly | (Query parameter):Boolean - Default : true |
| Request Body | { |
Example :
Request URL:
http://localhost:7070/bots/restricted/5aaf90e29f7dd421ac3c7dd4/5add1fe8a081a228a0588d1c?returnDetailed=false&returnCurrentStepOnly=true
Request Body
{
"input": "Hi!",
"context": {}
}
Response Body
{
"botId": "5aaf90e29f7dd421ac3c7dd4",
"botVersion": 1,
"environment": "restricted",
"conversationState": "READY",
"redoCacheSize": 0,
"conversationSteps": [
{
"conversationStep": [
{
"key": "input:initial",
"value": "Hi!"
}
],
"timestamp": 1524441253098
}
]
}
Response Code
200
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 :
| HTTP Method | GET |
|---|---|
| Api endpoint | /bots/{environment}/{botId}/{conversationId} |
| {environment} | (Path parameter):String Deployment environment (e.g: |
| {conversationId} | (Path parameter):String id of the conversation that you wish to add the message to. |
| returnDetailed | (Query parameter):Boolean - Default : true |
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"
}
3 - 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 succesful by receiving a true or false in the response body.
| HTTP Method | POST |
|---|---|
| Api endpoint | /bots/{environment}/{botId}/[undo/redo]/{conversationId} |
| {environment} | (Path parameter):String Deployment environment (e.g: |
| {conversationId} | (Path parameter):String id of the conversation that you wish to undo the last conversation step. |
Example undo POST:
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
}