English

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.

EndpointAuthentication

/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"
    }
}
PreviousGlossary

Last updated