Comment on page

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
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
1
“Authorization”: “bWluZC1haTpyZWFsam9obmRvZQ==”
2
“X-Conversation-Id”: NULL
3
“UUID”: “cab64bcd-9e97-424e-b786-30b617615e02”
Request Payload
1
{
2
    "query": null,
3
    "query-id": "1c4339cd-d53a-489e-85f3-50a14d1da658",
4
    "timestamp": 1676943114143
5
}
Response Example
1
{
2
    "description": "Created",
3
    "code": 202,
4
    "data": {
5
        "channel-result": null,
6
        "result": [
7
            "Hello, how may I help you?"
8
        ],
9
        "execution-time": 79,
10
        "timestamp": 1676940742565,
11
        "query-id": "ddcd29e6-209e-4896-a0e1-00c16678c331",
12
        "conversation_id": "408b6dca-fc5e-4be7-b5a9-cfa9d6c61a3c"
13
    }
14
}
Handshaking with Input Query Example
Request Header
1
“Authorization”: “bWluZC1haTpyZWFsam9obmRvZQ==”
2
“X-Conversation-Id”: NULL
3
“UUID”: “cab64bcd-9e97-424e-b786-30b617615e02”
Request Payload
1
{
2
    "query": "Hello",
3
    "query-id": "1c4339cd-d53a-489e-85f3-50a14d1da658",
4
    "timestamp": 1676943114143
5
}
Response Example
1
{
2
    "description": "Created",
3
    "code": 202,
4
    "data": {
5
        "channel-result": [
6
            {
7
                "channel-message": {
8
                    "channel-name": "default",
9
                    "template-type": "text",
10
                    "template": "Hello from Mind Expression",
11
                    "image-url": "",
12
                    "upload-type": "",
13
                    "quick-replies": [],
14
                    "card-list": []
15
                },
16
                "channel-message-alt": {
17
                    "channels": [
18
                        {
19
                            "channel-name": "default",
20
                            "template-type": "text",
21
                            "template": null,
22
                            "image-url": "",
23
                            "upload-type": "",
24
                            "quick-replies": [],
25
                            "card-list": []
26
                        }
27
                    ]
28
                },
29
                "channel-instruction": {
30
                    "channel-name": "default",
31
                    "template-type": "text",
32
                    "template": "Hi there",
33
                    "image-url": "",
34
                    "upload-type": "",
35
                    "quick-replies": [],
36
                    "card-list": []
37
                },
38
                "channel-instruction-alt": {
39
                    "channels": [
40
                        {
41
                            "channel-name": "default",
42
                            "template-type": "text",
43
                            "template": null,
44
                            "image-url": "",
45
                            "upload-type": "",
46
                            "quick-replies": [],
47
                            "card-list": []
48
                        }
49
                    ]
50
                }
51
            }
52
        ],
53
        "result": [
54
            ""
55
        ],
56
        "execution-time": 79,
57
        "timestamp": 1676940742565,
58
        "query-id": "ddcd29e6-209e-4896-a0e1-00c16678c331",
59
        "conversation_id": "408b6dca-fc5e-4be7-b5a9-cfa9d6c61a3c"
60
    }
61
}
Normal Conversation Example
Request Header
1
“Authorization”: “bWluZC1haTpyZWFsam9obmRvZQ==”
2
“X-Conversation-Id”: “4355d048-2438-405d-aac5-c04ce7086dcf”
3
“UUID”: “cab64bcd-9e97-424e-b786-30b617615e02”
Request Payload
1
{
2
    "query-id": "ddcd29e6-209e-4896-a0e1-00c16678c331",
3
    "query": "Can I upgrade my mobile package?",
4
    "timestamp": 1615862988000
5
}
Response Example
1
{
2
    "description": "Created",
3
    "code": 202,
4
    "data": {
5
        "channel-result": [
6
            {
7
                "channel-message": {
8
                    "channel-name": "default",
9
                    "template-type": "text",
10
                    "template": "Hello from Mind Expression",
11
                    "image-url": "",
12
                    "upload-type": "",
13
                    "quick-replies": [],
14
                    "card-list": []
15
                },
16
                "channel-message-alt": {
17
                    "channels": [
18
                        {
19
                            "channel-name": "default",
20
                            "template-type": "text",
21
                            "template": null,
22
                            "image-url": "",
23
                            "upload-type": "",
24
                            "quick-replies": [],
25
                            "card-list": []
26
                        }
27
                    ]
28
                },
29
                "channel-instruction": {
30
                    "channel-name": "default",
31
                    "template-type": "text",
32
                    "template": "Hi there",
33
                    "image-url": "",
34
                    "upload-type": "",
35
                    "quick-replies": [],
36
                    "card-list": []
37
                },
38
                "channel-instruction-alt": {
39
                    "channels": [
40
                        {
41
                            "channel-name": "default",
42
                            "template-type": "text",
43
                            "template": null,
44
                            "image-url": "",
45
                            "upload-type": "",
46
                            "quick-replies": [],
47
                            "card-list": []
48
                        }
49
                    ]
50
                }
51
            }
52
        ],
53
        "result": [
54
            ""
55
        ],
56
        "execution-time": 79,
57
        "timestamp": 1676940742565,
58
        "query-id": "ddcd29e6-209e-4896-a0e1-00c16678c331",
59
        "conversation_id": "408b6dca-fc5e-4be7-b5a9-cfa9d6c61a3c"
60
    }
61
}
Response Example (with Quick Reply)
1
{
2
    "description": "Created",
3
    "code": 202,
4
    "data": {
5
        "channel-result": [
6
            {
7
                "channel-message": {
8
                    "channel-name": "default",
9
                    "template-type": "quick_reply",
10
                    "template": "How are you today?",
11
                    "image-url": "",
12
                    "upload-type": "",
13
                    "quick-replies": [
14
                        {
15
                            "label": "Good",
16
                            "message": "I'm good, thanks.",
17
                            "type": "message",
18
                            "image-url": null,
19
                            "url": null
20
                        },
21
                        {
22
                            "label": "Not good",
23
                            "message": "Not so good, I'm afraid.",
24
                            "type": "message",
25
                            "image-url": null,
26
                            "url": null
27
                        }
28
                    ],
29
                    "card-list": []
30
                },
31
                "channel-message-alt": {
32
                    "channels": [
33
                        {
34
                            "channel-name": "default",
35
                            "template-type": "text",
36
                            "template": null,
37
                            "image-url": "",
38
                            "upload-type": "",
39
                            "quick-replies": [],
40
                            "card-list": []
41
                        }
42
                    ]
43
                },
44
                "channel-instruction": {
45
                    "channel-name": "default",
46
                    "template-type": "text",
47
                    "template": "Hello from Mind Expression.",
48
                    "image-url": "",
49
                    "upload-type": "",
50
                    "quick-replies": [],
51
                    "card-list": []
52
                },
53
                "channel-instruction-alt": {
54
                    "channels": [
55
                        {
56
                            "channel-name": "default",
57
                            "template-type": "text",
58
                            "template": null,
59
                            "image-url": "",
60
                            "upload-type": "",
61
                            "quick-replies": [],
62
                            "card-list": []
63
                        }
64
                    ]
65
                }
66
            }
67
        ],
68
        "result": [
69
            ""
70
        ],
71
        "execution-time": 79,
72
        "timestamp": 1676945014202,
73
        "query-id": "ddcd29e6-209e-4896-a0e1-00c16678c331",
74
        "conversation_id": "527998fc-f03c-47fd-9b7a-0624d5f341f0"
75
    }
76
}
Response Example (with Card)
1
{
2
    "description": "Ok",
3
    "code": 200,
4
    "data": {
5
        "channel-result": [
6
            {
7
                "channel-message": {
8
                    "template-type": null,
9
                    "template": "",
10
                    "image-url": "",
11
                    "upload-type": "",
12
                    "quick-replies": [],
13
                    "card-list": [],
14
                    "channels": []
15
                },
16
                "channel-message-alt": {
17
                    "channels": []
18
                },
19
                "channel-instruction": {
20
                    "channel-name": "default",
21
                    "template-type": "card",
22
                    "template": "",
23
                    "image-url": "",
24
                    "upload-type": "",
25
                    "quick-replies": [],
26
                    "card-list": [
27
                        {
28
                            "title": "Welcome to Mind Expression",
29
                            "sub-title": "This is an example subtitle.",
30
                            "image-url": "https://mind-expression.s3.amazonaws.com/builder/dev/QlXUT7-1SpOQQH7IUavSOw_mind_intro_poster_20200101.jpg",
31
                            "buttons": [
32
                                {
33
                                    "button-type": "link",
34
                                    "label": "Go to Website",
35
                                    "link": "https://mindx.mind.ai",
36
                                    "message": null
37
                                }
38
                            ]
39
                        }
40
                    ]
41
                },
42
                "channel-instruction-alt": {
43
                    "channels": [
44
                        {
45
                            "channel-name": "default",
46
                            "template-type": "text",
47
                            "template": null,
48
                            "image-url": "",
49
                            "upload-type": "",
50
                            "quick-replies": [],
51
                            "card-list": []
52
                        }
53
                    ]
54
                }
55
            },
56
            {
57
                "channel-message": {
58
                    "channel-name": "default",
59
                    "template-type": "text",
60
                    "template": "Would you like to buy some?",
61
                    "image-url": "",
62
                    "upload-type": "",
63
                    "quick-replies": [],
64
                    "card-list": []
65
                },
66
                "channel-message-alt": {
67
                    "channels": [
68
                        {
69
                            "channel-name": "default",
70
                            "template-type": "text",
71
                            "template": null,
72
                            "image-url": "",
73
                            "upload-type": "",
74
                            "quick-replies": [],
75
                            "card-list": []
76
                        }
77
                    ]
78
                },
79
                "channel-instruction": {
80
                    "channel-name": "default",
81
                    "template-type": "text",
82
                    "template": null,
83
                    "image-url": "",
84
                    "upload-type": "",
85
                    "quick-replies": [],
86
                    "card-list": []
87
                },
88
                "channel-instruction-alt": {
89
                    "channels": [
90
                        {
91
                            "channel-name": "default",
92
                            "template-type": "text",
93
                            "template": null,
94
                            "image-url": "",
95
                            "upload-type": "",
96
                            "quick-replies": [],
97
                            "card-list": []
98
                        }
99
                    ]
100
                }
101
            }
102
        ],
103
        "result": [
104
            ""
105
        ],
106
        "execution-time": 38,
107
        "timestamp": 1676945335480,
108
        "query-id": "ddcd29e6-209e-4896-a0e1-00c16678c331",
109
        "conversation_id": "527998fc-f03c-47fd-9b7a-0624d5f341f0"
110
    }
111
}
​

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.

Reference - Previous

Glossary

Last modified 7mo ago

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

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

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-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.

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.

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

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.

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.

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-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.