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.
/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
Engine URL - You can get this on the integration page. This is the main URL you will use to access the API’s endpoint.
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
How to get Header & Body using Mindscript in Mind Expression
Request Example
HTTP Header
HTTP Body
Mindscript code Example
The following code can be added to the Program Logic(Before/After)
of the Mind Expression.
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
Request Payload
Response Example
Handshaking with Input Query Example
Request Header
Request Payload
Response Example
Normal Conversation Example
Request Header
Request Payload
Response Example
Response Example (with Quick Reply)
Response Example (with Card)
Last updated