API Docs

Send messages to Mind Expression API

Use the /api/v1/gateway/default/DEVEOPER_ID/SCOPE_ID endpoint to send a message to the Mind Expression API, where the Mind Expression CAI will receive your message query and respond according to the configurations of your subjects. You can configure the responses with multiple types of templates and formats, presenting you with the flexibility to format messages on your platform.

Endpoint	Authentication
/api/v1/gateway/default/DEVEOPER_ID/SCOPE_ID	Developers can authenticate API calls to this endpoint with the Auth Key given on the integration page.

What you need

1. Engine URL - You can get this on the integration page. This is the main URL you will use to access the API’s endpoint.

2. Auth Key - This is the authorization token on the integration page. This token is used to authorize your access to the Mind Expression API.

Request Headers

Content-Type	Required	application/json
Authorization	Required	Bearer {Auth Key}
X-Conversation-Id		UUID (e.g. 408b6dca-fc5e-4be7-b5a9-cfa9d6c61a3c)

All messages are contained with a conversation with a unique ID in the UUID format. On the first message that will start a new conversation, the Mind Expression API will return a 202 along with the conversation ID in which the user must return in the request header in order to continue the conversation. Messages without this header will be considered as a new conversation and might result in unintended behaviors.

Request Body

query	Required	String of messages to send
query-id	Required	Unique UUID to identify the message
timestamp	Required	Time in UNIX Epoch on sending the message
custom		Custom Object (See example below)

Custom Object can be any JSON object.

Custom Object Example

{
    "user-name": "Jane Doe"
}

How to get Header & Body using Mindscript in Mind Expression

Request Example

HTTP Header

Content-Type: application/json
Authorization: Bearer bWluZC1haTpyZWFsam9obmRvZQ
platform: ANDROID

HTTP Body

{
    "query": "Hello",
    "query-id": "1c4339cd-d53a-489e-85f3-50a14d1da658",
    "timestamp": 1697768070001,
    "custom": {
        "user-name": "Jane Doe"
    }
}

Mindscript code Example

The following code can be added to the Program Logic(Before/After) of the Mind Expression.

"Get HTTPHeader"
platform := self httpHeaders at: 'platform' ifAbsent: 'IOS'.

"Get HTTPBody"
userName := self httpRequestBody at: 'user-name' ifAbsent: 'John Doe'.

Response

The Mind Expression API will return the list of response messages and the status code for the response.

description	String of short description messages for the action
code	Status Code
data	Message Object See details below.

Status Codes

200 Ok	Typical response for a message
202 Created	No Conversation ID was given. Message starts a conversation.
204 Not classified	The Mind Expression engine does not understand the message within the conversation configurations. Returns a fallback response.
210 Empty input message	The API call contains an empty string as a query.
220 Conversation terminated	The message and response ends the current conversation.

Message Object

execution-time	Time in milliseconds it takes to execute the query.
timestamp	Time in UNIX Epoch when the query is executed.
query-id	ID of the query if sent by the user.
conversation-id	Conversation ID of the message
result - deprecated	A list of response messages.
channel-result	A list of Channel Message Object. See details below.

Channel Message Object

channel-instruction	Optional	Template Object of instruction message
channel-instruction-alt	Optional	Template Object of alternative instruction message that is guaranteed as text type in case the other specified type of message is not implemented.
channel-message		Template Object of prompt message to obtain input
channel-message-alt	Optional	Template Object of prompt instruction message to obtain that is guaranteed as text type in case the other specified type of message is not implemented.

Template Object

channel-name	Name of the message channel. Configurations for Mind Expression API on the subject settings correlate to the channel default.
template-type	Type of template message. One of text | card | quick_reply | image | code | free
template	Required in case of text or code. String of content. In case of quick_reply, represent the prompt message.
image-url	Required in case of image. The url for the media
upload-type	Required in case of image. The type of media upload.
quick-replies	Required in case of quick_reply. A list of Quick Reply Objects buttons. See details below.
card-list	Required in case of card. A list of Card Objects response message. See details below.

Quick Reply Object

label	Button label of the quick reply button.
message	Required if type is message. Message that will be sent as reply when the button is pressed.
type	Type of action taken when the button is pressed. One of link | message
image-url	Image that will be added to the button.
url	Required if type is link. The link that the user will be directed when the button is pressed.

Card Object

title	Required. Title of the card object.
sub-title	Sub-title of the card object.
image-url	URL of the image to be shown in the card.
buttons	A list of Button Objects. See details below.

Button Object

button-type	Type of action taken when the button is pressed. One of link | message
label	Button label.
link	Required if button-type is link. The URL user will be redirected on button press.
message	Required if button-type is message. The message that will be sent as reply when the button is pressed.

Examples

Handshaking Request Example

Request Header

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

Request Payload

{
    "query": null,
    "query-id": "1c4339cd-d53a-489e-85f3-50a14d1da658",
    "timestamp": 1676943114143
}

Response Example

{
    "description": "Created",
    "code": 202,
    "data": {
        "channel-result": null,
        "result": [
            "Hello, how may I help you?"
        ],
        "execution-time": 79,
        "timestamp": 1676940742565,
        "query-id": "ddcd29e6-209e-4896-a0e1-00c16678c331",
        "conversation_id": "408b6dca-fc5e-4be7-b5a9-cfa9d6c61a3c"
    }
}

Handshaking with Input Query Example

Request Header

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

Request Payload

{
    "query": "Hello",
    "query-id": "1c4339cd-d53a-489e-85f3-50a14d1da658",
    "timestamp": 1676943114143
}

Response Example

{
    "description": "Created",
    "code": 202,
    "data": {
        "channel-result": [
            {
                "channel-message": {
                    "channel-name": "default",
                    "template-type": "text",
                    "template": "Hello from Mind Expression",
                    "image-url": "",
                    "upload-type": "",
                    "quick-replies": [],
                    "card-list": []
                },
                "channel-message-alt": {
                    "channels": [
                        {
                            "channel-name": "default",
                            "template-type": "text",
                            "template": null,
                            "image-url": "",
                            "upload-type": "",
                            "quick-replies": [],
                            "card-list": []
                        }
                    ]
                },
                "channel-instruction": {
                    "channel-name": "default",
                    "template-type": "text",
                    "template": "Hi there",
                    "image-url": "",
                    "upload-type": "",
                    "quick-replies": [],
                    "card-list": []
                },
                "channel-instruction-alt": {
                    "channels": [
                        {
                            "channel-name": "default",
                            "template-type": "text",
                            "template": null,
                            "image-url": "",
                            "upload-type": "",
                            "quick-replies": [],
                            "card-list": []
                        }
                    ]
                }
            }
        ],
        "result": [
            ""
        ],
        "execution-time": 79,
        "timestamp": 1676940742565,
        "query-id": "ddcd29e6-209e-4896-a0e1-00c16678c331",
        "conversation_id": "408b6dca-fc5e-4be7-b5a9-cfa9d6c61a3c"
    }
}

Normal Conversation Example

Request Header

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

Request Payload

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

Response Example

{
    "description": "Created",
    "code": 202,
    "data": {
        "channel-result": [
            {
                "channel-message": {
                    "channel-name": "default",
                    "template-type": "text",
                    "template": "Hello from Mind Expression",
                    "image-url": "",
                    "upload-type": "",
                    "quick-replies": [],
                    "card-list": []
                },
                "channel-message-alt": {
                    "channels": [
                        {
                            "channel-name": "default",
                            "template-type": "text",
                            "template": null,
                            "image-url": "",
                            "upload-type": "",
                            "quick-replies": [],
                            "card-list": []
                        }
                    ]
                },
                "channel-instruction": {
                    "channel-name": "default",
                    "template-type": "text",
                    "template": "Hi there",
                    "image-url": "",
                    "upload-type": "",
                    "quick-replies": [],
                    "card-list": []
                },
                "channel-instruction-alt": {
                    "channels": [
                        {
                            "channel-name": "default",
                            "template-type": "text",
                            "template": null,
                            "image-url": "",
                            "upload-type": "",
                            "quick-replies": [],
                            "card-list": []
                        }
                    ]
                }
            }
        ],
        "result": [
            ""
        ],
        "execution-time": 79,
        "timestamp": 1676940742565,
        "query-id": "ddcd29e6-209e-4896-a0e1-00c16678c331",
        "conversation_id": "408b6dca-fc5e-4be7-b5a9-cfa9d6c61a3c"
    }
}

Response Example (with Quick Reply)

{
    "description": "Created",
    "code": 202,
    "data": {
        "channel-result": [
            {
                "channel-message": {
                    "channel-name": "default",
                    "template-type": "quick_reply",
                    "template": "How are you today?",
                    "image-url": "",
                    "upload-type": "",
                    "quick-replies": [
                        {
                            "label": "Good",
                            "message": "I'm good, thanks.",
                            "type": "message",
                            "image-url": null,
                            "url": null
                        },
                        {
                            "label": "Not good",
                            "message": "Not so good, I'm afraid.",
                            "type": "message",
                            "image-url": null,
                            "url": null
                        }
                    ],
                    "card-list": []
                },
                "channel-message-alt": {
                    "channels": [
                        {
                            "channel-name": "default",
                            "template-type": "text",
                            "template": null,
                            "image-url": "",
                            "upload-type": "",
                            "quick-replies": [],
                            "card-list": []
                        }
                    ]
                },
                "channel-instruction": {
                    "channel-name": "default",
                    "template-type": "text",
                    "template": "Hello from Mind Expression.",
                    "image-url": "",
                    "upload-type": "",
                    "quick-replies": [],
                    "card-list": []
                },
                "channel-instruction-alt": {
                    "channels": [
                        {
                            "channel-name": "default",
                            "template-type": "text",
                            "template": null,
                            "image-url": "",
                            "upload-type": "",
                            "quick-replies": [],
                            "card-list": []
                        }
                    ]
                }
            }
        ],
        "result": [
            ""
        ],
        "execution-time": 79,
        "timestamp": 1676945014202,
        "query-id": "ddcd29e6-209e-4896-a0e1-00c16678c331",
        "conversation_id": "527998fc-f03c-47fd-9b7a-0624d5f341f0"
    }
}

Response Example (with Card)

{
    "description": "Ok",
    "code": 200,
    "data": {
        "channel-result": [
            {
                "channel-message": {
                    "template-type": null,
                    "template": "",
                    "image-url": "",
                    "upload-type": "",
                    "quick-replies": [],
                    "card-list": [],
                    "channels": []
                },
                "channel-message-alt": {
                    "channels": []
                },
                "channel-instruction": {
                    "channel-name": "default",
                    "template-type": "card",
                    "template": "",
                    "image-url": "",
                    "upload-type": "",
                    "quick-replies": [],
                    "card-list": [
                        {
                            "title": "Welcome to Mind Expression",
                            "sub-title": "This is an example subtitle.",
                            "image-url": "https://mind-expression.s3.amazonaws.com/builder/dev/QlXUT7-1SpOQQH7IUavSOw_mind_intro_poster_20200101.jpg",
                            "buttons": [
                                {
                                    "button-type": "link",
                                    "label": "Go to Website",
                                    "link": "https://mindx.mind.ai",
                                    "message": null
                                }
                            ]
                        }
                    ]
                },
                "channel-instruction-alt": {
                    "channels": [
                        {
                            "channel-name": "default",
                            "template-type": "text",
                            "template": null,
                            "image-url": "",
                            "upload-type": "",
                            "quick-replies": [],
                            "card-list": []
                        }
                    ]
                }
            },
            {
                "channel-message": {
                    "channel-name": "default",
                    "template-type": "text",
                    "template": "Would you like to buy some?",
                    "image-url": "",
                    "upload-type": "",
                    "quick-replies": [],
                    "card-list": []
                },
                "channel-message-alt": {
                    "channels": [
                        {
                            "channel-name": "default",
                            "template-type": "text",
                            "template": null,
                            "image-url": "",
                            "upload-type": "",
                            "quick-replies": [],
                            "card-list": []
                        }
                    ]
                },
                "channel-instruction": {
                    "channel-name": "default",
                    "template-type": "text",
                    "template": null,
                    "image-url": "",
                    "upload-type": "",
                    "quick-replies": [],
                    "card-list": []
                },
                "channel-instruction-alt": {
                    "channels": [
                        {
                            "channel-name": "default",
                            "template-type": "text",
                            "template": null,
                            "image-url": "",
                            "upload-type": "",
                            "quick-replies": [],
                            "card-list": []
                        }
                    ]
                }
            }
        ],
        "result": [
            ""
        ],
        "execution-time": 38,
        "timestamp": 1676945335480,
        "query-id": "ddcd29e6-209e-4896-a0e1-00c16678c331",
        "conversation_id": "527998fc-f03c-47fd-9b7a-0624d5f341f0"
    }
}