E.D.D.I Documentation
Getting started
Creating your first Chatbot
Import/Export a Chatbot
Git support
Managed Bots
Deployement management of Chatbots
Extensions
Behavior Rules
Output Configuration
Semantic Parser
Conversations
Passing context information
Output Templating
HttpCalls
HTTP2 and SSL
Facebook Channel Setup
Bot Manager GUI
Docker
RedHat Openshift
Metrics
FAQs
Powered by GitBook

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:

Previous
Semantic Parser
Next
Passing context information
Last updated 10 months ago
Contents
Conversations
Creating/initiating a conversation :
Create a Conversation with a Chatbot REST API Endpoint
Response Model
Description of the Conversation response model
Sample Response
Example :
Send/receive messages
Send a message
Send message in a conversation with a Chatbot REST API Endpoint
Example :
Receive a message
Receive message in a conversation with a Chatbot REST API Endpoint
Example
Undo and redo :
Undo and redo in a conversation REST API Endpoint
Example (undo)
Sample bot: