API docs
This documentation covers the Mind Expression API reference.

Perform an end-user input query. The client provides a {conversation-id} used to identify an ongoing conversation context, or none to create a new conversation.
Returns code 201 on conversation creation, or code 200 on submitting input to an existing conversation.
{dev-key} and {scope-key} are created when a scope is created, which is a part of the Engine URL. Auth Key has also generated automatically when a scope is created, which is to be used to authenticate the API endpoint.

  • 200
    The conversation API processed the query
  • 401
    Unauthorized, for example: {auth_key} is invalid or subject is not activated yet. There is no "data" property in the out JSON payload
  • 400
    Bad request, invalid data for example: {dev-key} and/or {scope-key} is invalid or the wrong API call. There is no "data" property in the out JSON payload

The following headers are defined for this endpoint: There are two mandatory keys: "Authorization", and "X-Conversation-Id". However, a developer can set any information to the header that they need to carry over a webhook. For example, if a developer wants to send "UUID" to identify their customer from a webhook, they can carry "X-UUID" as part of the HTTP headers and with the simple lookup function http-header.{{Key in http header}} such as http-header.x-uuid in the webhook configuration, to be sent to the developer's system.
  • Authorization
    Bearer {auth-token}
  • X-Conversation-Id
    {conversation-id} (interchangeably conversation-key, conversation-token)
The client must provide the same {auth-token} provided when this scope is created (the Auth Key).

The following headers are returned from this endpoint:
  • X-Conversation-Id
    {conversation-id} which is generated by the AI engine

  • query-id
    Generated by the developer's chat system to distinguish the query. The same query-id will be returned to the developer's chat system. (GUID version 4)
  • query
    The user utterance to provide to the conversation system.
  • timestamp
    Generated by the developer's chat system in epoch unix timestamp (including milliseconds)

  • code
    We implement a similar concept to the existing HTTP status codes:
    • 201
      There was no X-Conversation-Id carried in the incoming HTTP header, therefore the input query is treated as the first conversation from the end customer. X-Conversation-Id will be in the OUT HTTP Header
    • 202
      There was no X-Conversation-Id carried in the incoming HTTP header, therefore the input query is treated as the first input in a new conversation from the end customer. The input query contained text which was classified and the conversation has been initiated. A new X-Conversation-Id will be in the OUT HTTP Header.
    • 200
      X-Conversation-Id is presented in the IN HTTP Header, therefore the query is processed normally
    • 204
      The input query is not classified, so a fallback message will be returned, such as "I'm sorry, I don't understand, can you rephrase it?" (configured in the message UI)
    • 210
      The input query only has a bag of empty strings, so there was nothing to act upon.
    • 220
      The conversation is terminated by either end-user or AI (if there is no more configured conversation to process with)
  • description
    A human-readable description of the code
  • data
    Holds query result
    • query-id
      The same id from IN Payload
    • result
      A list, a developer can draw a balloon per item inside the list.
    • timestamp
      Generated by the reasoning engine in epoch unix timestamp (including milliseconds)

"Authorization": "bWluZC1haTpyZWFsam9obmRvZQ=="
"X-Conversation-Id": NULL
"UUID": "cab64bcd-9e97-424e-b786-30b617615e02"

{
"query-id": "6703595b-5ce9-4680-8294-b82c7bfd2082",
"query": null,
"timestamp": 1615861988000
}

"X-Conversation-Id": "4355d048-2438-405d-aac5-c04ce7086dcf"

{
"code": 201,
"description": "Created",
"data": {
"query-id": "6703595b-5ce9-4680-8294-b82c7bfd2082",
"result": [
"Welcome to Mind Expression. How can I help you?"
],
"timestamp": 1615862088000
}
}

"Authorization": "bWluZC1haTpyZWFsam9obmRvZQ=="
"X-Conversation-Id": NULL
"UUID": "cab64bcd-9e97-424e-b786-30b617615e02"

{
"query-id": "6703595b-5ce9-4680-8294-b82c7bfd2082",
"query": "change mobile package",
"timestamp": 1615861988000
}

"X-Conversation-Id": "4355d048-2438-405d-aac5-c04ce7086dcf"

{
"code": 202,
"description": "Created",
"data": {
"query-id": "6703595b-5ce9-4680-8294-b82c7bfd2082",
"result": [
"These are the Mobile Phone numbers you have.\n0101002000 \n0101012001 \n0101022002 \n\nWhich Mobile Phone Number do you want to change package?"
],
"timestamp": 1615862088000
}
}

"Authorization": "bWluZC1haTpyZWFsam9obmRvZQ=="
"X-Conversation-Id": "4355d048-2438-405d-aac5-c04ce7086dcf"
"UUID": "cab64bcd-9e97-424e-b786-30b617615e02"

{
"query-id": "ddcd29e6-209e-4896-a0e1-00c16678c331",
"query": "Can I upgrade my mobile package?",
"timestamp": 1615862988000
}

"X-Conversation-Id": "4355d048-2438-405d-aac5-c04ce7086dcf"

{
"code": 200,
"description": "OK",
"data": {
"query-id": "ddcd29e6-209e-4896-a0e1-00c16678c331",
"result": [
"These are the Mobile Phone numbers you have.\n0101002000 \n0101012001 \n0101022002 \n\nWhich Mobile Phone Number do you want to change package?"
],
"timestamp": 1615863088000
}
}

"Authorization": "bWluZC1haTpyZWFsam9obmRvZQ=="
"X-Conversation-Id": "4355d048-2438-405d-aac5-c04ce7086dcf"
"UUID": "cab64bcd-9e97-424e-b786-30b617615e02"

{
"query-id": "4c3ee1c3-a66f-4608-92bd-88e8a3903ec4",
"query": "I don't like someone",
"timestamp": 1615879888000
}

"X-Conversation-Id": "4355d048-2438-405d-aac5-c04ce7086dcf"

{
"code": 204,
"description": "Not classified",
"data": {
"query-id": "4c3ee1c3-a66f-4608-92bd-88e8a3903ec4",
"result": [
"I'm sorry, I don't understand, can you rephrase it?"
],
"timestamp": 1615879988000
}
}

"Authorization": "bWluZC1haTpyZWFsam9obmRvZQ=="
"X-Conversation-Id": "4355d048-2438-405d-aac5-c04ce7086dcf"
"UUID": "cab64bcd-9e97-424e-b786-30b617615e02"

{
"query-id": "4c3ee1c3-a66f-4608-92bd-88e8a3903ec4",
"query": " ",
"timestamp": 1615879888000
}

"X-Conversation-Id": "4355d048-2438-405d-aac5-c04ce7086dcf"

{
"code": 210,
"description": "Empty input message",
"data": {
"query-id": "4c3ee1c3-a66f-4608-92bd-88e8a3903ec4",
"result": [
"I'm sorry, I don't understand, can you rephrase it?"
],
"timestamp": 1615879988000
}
}

"Authorization": "bWluZC1haTpyZWFsam9obmRvZQ=="
"X-Conversation-Id": "4355d048-2438-405d-aac5-c04ce7086dcf"
"UUID": "cab64bcd-9e97-424e-b786-30b617615e02"

{
"query-id": "4c3ee1c3-a66f-4608-92bd-88e8a3903ec4",
"query": "No thank you",
"timestamp": 1615879888000
}

"X-Conversation-Id": "4355d048-2438-405d-aac5-c04ce7086dcf"

{
"code": 220,
"description": "Conversation terminated",
"data": {
"query-id": "4c3ee1c3-a66f-4608-92bd-88e8a3903ec4",
"result": [
"Thank you. We look forward to seeing you again."
],
"timestamp": 1615879988000
}
}

{
"code": 401,
"description": "Unauthorized",
}

Terminate the designated conversation.
When a conversation is over (closing the chat window or leaving the chat room) the client should send appropriate messages to the API endpoint to indicate the conversation has successfully completed.
Also, if there is no API call within 3 minutes after the last conversation message, the AI engine will automatically close the session (conversation).
It will be ignored if "X-Conversation-Id" is not valid (it will always return code 200)

The following headers are defined for this endpoint:
  • Authorization
    Bearer {auth-token}
  • X-Conversation-Id
    {conversation-id}
The client must provide the same {auth-token} provided when this scope was activated.

"Authorization": "bWluZC1haTpyZWFsam9obmRvZQ=="
"X-Conversation-Id": "4355d048-2438-405d-aac5-c04ce7086dcf"

{}

"X-Conversation-Id": "4355d048-2438-405d-aac5-c04ce7086dcf"

{
"code": 200,
"description": "No Content",
}
Last modified 4mo ago
Copy link
On this page
/v1/scopes/{dev-key}/{scope-key}/conversations - (POST)
HTTP Response codes
In-Headers
Out-Headers
IN Payload
OUT Payload
Handshaking
Handshaking with input query
A normal conversation
Input query is not understood
Input query contains a bag of empty string
The conversation is terminated by either end-user or AI
Authentication error
/v1/scopes/{dev-key}/{scope-key}/conversations - (DELETE)
In-Headers