HELP!
© XpertRule

Chat Depolyment API

This interactive API allows a question/answer type knowledge base to be driven by a third party.

The basic premise is that a third party calls the REST based API to request the "next" question in the inference flow. The API returns the next question (along with relevant information required to render the question). Once the third party has an answer to the question, it supplies that answer to the API to continue inference.

A publicly available sample of the API can be reached via this endpoint...

https://alphaxrkb.xpertrule.com:8125/1IJ5G4xLo2LFGHDq

An example test page to render the questions can be found here...

https://alphaxrkb.xpertrule.com:8125/site/1IJ5G4xLo2LFGHDq/index.html

API overview

All API calls are performed via an HTTP POST request. The BODY of the request can either be empty or a well formed JSON Message

Worked Example

Given the following decision tree, let's run through the HTTP calls to see how to drive the inference to its conclusion...

Call #1

To start the session, simply call the API via HTTP with an empty BODY

curl -X POST 'https://alphaxrkb.xpertrule.com:8125/1IJ5G4xLo2LFGHDq'

n.b. You have the option to pre-supply question answers in this call by sending a well formed JSON Message in the POST BODY. See the [[decision_factory:reference_guide:deploying_applications:chat_engine_api#Pre-Supplying Question Answers]] section for more information.

Call #1 Response

{
  "state": "SUSPEND",
  "data": {
    "name": "Grade",
    "display": "What is the applicants position within the company?",
    "baseclass": "List_Question",
    "type": "list",
    "values": [
      {
        "name": "Director",
        "display": "Director",
        "valid": true
      },
      {
        "name": "SnrMgr",
        "display": "Senior Manager",
        "valid": true
      },
      {
        "name": "JnrMgr",
        "display": "Junior Manager",
        "valid": true
      }
    ],
    "multiselect": false,
    "allowblank": false,
    "info": {
      "name": "Interactive_Silent_Example"
    }
  },
  "resumePath": "/1IJ5G4xLo2LFGHDq?s=KJEuzHEoLDDDoqDJyvD71uvHxH6twp4M"
}

The 3 key components of this return message are...

Key Description
state The state of inference after execution. Possible values are "SUSPEND", "END" and "ERROR"
data This is the definition of the encountered inference suspend point (for "SUSPEND" state only)
resumePath This is the path to make your next API call to once there is an answer to the question (for "SUSPEND" state only)

Looking further at the data object...

Key Description
name The internal name of the question. This is required for passing the question's answer in the next call
display The text to display for the question. This relates to the Viabl.ai [description] property of the question. n.b. This property can be an empty string in which case you may choose to display the name property
baseclass The baseclass object from which this question was constructed
type The type of the question. Possible values are "list", "number", "date", "text" and "message"
values For list type questions, this is a list of possible answers
multiselect For list type questions, this indicates whether multiple selections are allowed
allowblank Can this question be skipped (i.e. no value selected). To continue inference with an empty value, make the return call with a value of "%%XR__EMPTY%%"

And finally the values array (only applicable for "list" type questions)...

Key Description
name The internal name of the answer. This is required for passing the question's answer in the next call
display The text to display for the question. User defined list value properties can be added to the baseclass via the Object Structure Maintenance, from which one can be chosen for display. n.b. This property can be an empty string in which case you may choose to display the name property
valid Is this a valid value? The validity of values is governed by the imposition of Viabl.ai constraints. A front end might choose to exclude this value, or, disable it

Call #2

Once the third party has captured an answer to the question, they should call the API (as specified in the previous response's resumePath property) with a well formed JSON Message. e.g.

{
    "Grade": "SnrMgr"
}

n.b. It's the question name and value name properties that are sent back to the API (NOT the display value). Additionally, if the question is optional, and the user does not supply an answer, you should supply the value "%%XR__EMPTY%%"

n.b. This format is also used to pre-supply answers at the start of the session

curl -X POST 'https://alphaxrkb.viabl.ai.com:8125/1IJ5G4xLo2LFGHDq?s=thx1138' -d '{"Grade":"SnrMgr"}'

Call #2 Response

{
    "state": "SUSPEND",
    "data": {
        "name": "Cost",
        "display": "What was the daily cost of the hotel?",
        "baseclass": "Numeric_Question",
        "type": "number",
        "decs": 0,
        "allowblank": false
        "minimum": 0,
        "maximum": 1000
    },
    "resumePath": "/1IJ5G4xLo2LFGHDq?s=thx1138"
}

Note that this response is asking for a numeric question so there is no values array (as was the case for the list question type). There is also no values array for "date", "text" and "message" types. Additionally, the minimum and maximum properties are optional and are omitted from the return message if they have not been set by the developer.

Call #3

Once the third party has captured an answer to the question, they again call the API (as specified in the previous response's resumePath property) with a well formed JSON Message. e.g.

{
    "Cost": 42
}

n.b. Because this is a numeric question, the property value is a number (not a string)

curl -X POST 'https://alphaxrkb.xpertrule.com:8125/1IJ5G4xLo2LFGHDq?s=thx1138' -d '{"Cost":42}'

Call #3 Response

{
    "state": "SUSPEND",
    "data": {
        "type": "message",
        "messages": [
            "Hello Sailor"
        ]
    },
    "resumePath": "/1IJ5G4xLo2LFGHDq?s=thx1138"
}

This response expects the third party to echo the supplied message to the user (as specified in the display property). The Viabl.ai developer triggers this via the xpertrule.message function.

n.b. The third party application could either just display the message to the user, or, require the user to perform some kind of OK action.

Call #4

If the user had to perform some kind of OK action (e.g. the message was displayed and the user had to click an OK button to continue), the next API call is just an HTTP POST to the end point...

curl -X POST 'https://alphaxrkb.xpertrule.com:8125/1IJ5G4xLo2LFGHDq?s=thx1138'

However, if the end user DID NOT have to perform an "OK" action, the response should be a well formed JSON object with the reserved "_skipped": true parameter set appropriately (this is required for the "back" operation to function more efficiently; see the [[decision_factory:reference_guide:deploying_applications:chat_engine_api#Stepping Back]] section for more details)...

{
    "_skipped": true
}

Whether the message was auto-continued, or the user performed an OK action, the third party can also supply arbitrary question answers (in the usual JSON format) providing they know the internal question name. This has the effect of both supplying more information to the inference engine AND continuing inference.

Call #4 Response

{
    "state": "END",
    "data": {
        "display": "Session ended OK"
    }
}

This signifies that inference has complete. The third party app can deal with this situation in various ways.

n.b. The entire "data" section is optional, but, if present there can be a "display" property which has been defined by the knowledge-base developer using the Final Message option in the Knowledge Base Settings. This can be presented to the end user.

Supplying Values for Date Questions

Date question values are supplied as strings in ISO 8601 format. e.g.

{
    "DateOfBirth": "1970-01-01T00:00:00Z"
}

Pre-Supplying Question Answers

If data is available upfront, this can be pre-supplied in the initial API call. For example, to pre-supply the applicant's grade the POST BODY might look like this...

{
    "Grade": "Director"
}

curl -X POST 'https://alphaxrkb.xpertrule.com:8125/1IJ5G4xLo2LFGHDq' -d '{"Grade":"Director"}'

n.b. Note we can tell that this is the first call because there is no parameter on the API endpoint URL

Adding Extra Properties to the Question Definition

The Viabl.ai developer can attach custom properties to the question's data object by adding extra Object Properties to the question (via the Object Structure Maintenance option). Custom properties set as Include in xpertrule.getValues are returned in the data object.

e.g. If the developer added a custom color property to the Cost object...

{
    "state": "SUSPEND",
    "data": {
        "name": "Cost",
        "display": "What was the daily cost of the hotel?",
        "type": "number",
        "color": "green"
    },
    "resumePath": "/1IJ5G4xLo2LFGHDq?s=thx1138"
}

Extra properties can also be added to the list values (via the Object Structure Maintenance option and set to Include in xpertrule.getValues).

e.g. If the developer added an imageURL property to the values of the Grade object...

{
    "state": "SUSPEND",
    "data": {
        "name": "Grade",
        "display": "What is the applicants position within the company?",
        "type": "list",
        "values": [
            {
                "name": "Director",
                "display": "Director",
                "valid": true,
                "imageURL": "http://acme.com/img1.png"

            },
            {
                "name": "SenMgr",
                "display": "Senior Manager",
                "valid": true,
                "imageURL": "http://acme.com/img2.png"
            },
            {
                "name": "JunMgr",
                "display": "Junior Manager",
                "valid": true,
                "imageURL": "http://acme.com/img3.png"
            }
        ]
    },
    "resumePath": "/1IJ5G4xLo2LFGHDq?s=thx1138"
}

Returning Internal Values at the End Of Inference

If the Viabl.ai developer sets any questions to be output in the Inputs & Outputs, these are also returned in the END state. e.g. If the Expenses decision tree object is set as an output...

{
    "state": "END",
    "Expenses": "Reject"
}

Handling Errors

If an error is encountered in inference, the API will respond with a state of "ERROR". e.g.

{
  "state": "ERROR",
  "description": "An error was encountered in script execution!"
}

Reports

A Viabl.ai Platform report object is reflected as a "report" type...

{
    "state": "SUSPEND",
    "data": {
        "type": "report",
        "contents": "Hello, this is a report for you!"
    },
    "resumePath": "/1IJ5G4xLo2LFGHDq?s=thx1138"
}

n.b. The third party application could either just display the message to the user, or, require the user to perform some kind of OK action.

Stepping Back

If an option is presented to allow the user to "undo" or "back" the last action, this is indicated to the API via the reserved _action property. An example message passed to the API would look like...

{
  "_action": "back"
}

Extra Application Information

In the FIRST response from the API, there is an additional "info" object which is used to return global application information. e.g.

{
    "state": "SUSPEND",
    "data": {
        "name": "Grade",
        "display": "What is the applicants position within the company?",
        "type": "list",
        ...
    },
    "resumePath": "/1IJ5G4xLo2LFGHDq?s=thx1138",
    "info": {
        "name": "Interactive Test Application"
    }
}

Knowledge-Base Defined Output Objects

If the Knowledge-Base defines any output objects in the Inputs & Outputs then this is returned with each response in the data.outputs object.

{
    "state": "SUSPEND",
    "data": {
        "name": "Cost",
        "display": "What was the cost of the hotel?",
        "type": "numeric",
        "outputs": {
            "Grade": "SnrMsg"
        }
        ...
    },
    "resumePath": "/1IJ5G4xLo2LFGHDq?s=thx1138"
}
  • n.b. If no objects are specified (or they are all empty and the "return empty objects" option is not set), there will NOT be a data.outputs object.*

On This Page