Messages¶

The messages endpoint is used to send text or event. The query messages return structured data in JSON format with responses from the Virtual Agent for different medium.

URL : api.prisme.ai/v1/Messages

Method : POST

Request example¶

With natural langage¶

curl -X POST \
  https://api.prisme.ai/v1/Messages \
  -H 'Authorization: Bearer Prisme_Client_Token' \
  -H 'Content-Type: application/json' \
  -d '{
   "text":"I want to drink a coffee and a tea",
   "userId":"userId",
   "platform":"web"
}'

With event¶

curl -X POST \
  https://api.prisme.ai/v1/Messages \
  -H 'Authorization: Bearer Prisme_Client_Token' \
  -H 'Content-Type: application/json' \
  -d '{
   "event":"TV_WAIKUP",
   "userId":"userId",
   "platform":"speaker"
}'

With payload¶

curl -X POST \
  https://api.prisme.ai/v1/Messages \
  -H 'Authorization: Bearer Prisme_Client_Token' \
  -H 'Content-Type: application/json' \
  -d '{
   "event":"TV_WAIKUP",
    "payload": [{
        "type": "parameters",
        "value": {
            "foo": "bar"
        }
    }],
   "userId":"userId",
   "platform":"facebook"
}'

Using the stream response format¶

You should know that, there is an alternative display mode for the assistant response, we call it stream, this alternative display mode simply replace the content of the items field in the fulfillment response with a stream response.

Those are very similar, however the stream benefits from all the different kind of object that can be used in a workflow, where the old items format is bound to disappear and only supports really basic workflow elements.

In order to receive the stream format you only need to specify a query parameter useStreamFormat and set its value to "true".

curl -X POST \
  https://api.prisme.ai/v1/Messages?useStreamFormat=true \
  -H 'Authorization: Bearer Prisme_Client_Token' \
  -H 'Content-Type: application/json' \
  -d '{
   "event":"ENROLL",
    "payload": [{
        "type": "parameters",
        "value": {
            "army": "Jedi Order"
        }
    }],
   "userId":"userId",
   "platform":"slack"
}'

Headers¶

In the request URL, provide the following headers with values.

Key	Value
Content-Type	application/json
Authorization	Bearer `Prisme_Client_Token`

Query parameters¶

Key	Default value	Required
useStreamFormat	`false`	Optional

Request body¶

The following parameters are used as JSON keys in the POST body.

Parameter	Type	Description	Required
userId	String	ID of the user talking with the Virtual Agent	Required
text	String	Message the user want to send to the Virtual Agent	Required unless you are using event
event	String	Name of the event that is supposed to trigger an intent, will fallback if doesn't exist	Required unless you are using text
payload	Object	Object of media (image, audio...)	Optional
platform	String	Name of the platform used by the user	Required

Success Response¶

Condition : No required parameter missing and Prisme_Client_Token is known by the platform.

Code : 200

Content example with "legacy" format

{
    "id": "ndaCWVgGHCkS9dK9ulmdXhXh5UA",
    "timestamp": "2019-08-09T14:25:21+00:00",
    "sessionId": "CKxym0sXQX",
    "conversationId": "5a4GXmFP8C",
    "query": "I want to drink a coffee and a tea",
    "fulfillment": [
        {
            "source": "TestOfBug",
            "items": [
                {
                    "text": "Here it is",
                    "web": "How do you want to pay",
                    "speaker": "Can you hear me ?  I hope you will enjoy your beverage",
                    "telephony": "Allo ? This will be a great beverage"
                },
                {
                    "text": "How do you want to pay ?",
                    "web": "<ul><li>Credit Card</li><li>Cash</li></ul>"
                },
                {
                    "events": [
                        {
                            "text": "Hey you!",
                            "event": "WELCOME"

                        }
                    ]
                }

            ]
        }
    ],
    "intents": [
        {
            "source": "TestOfBug",
            "name": "Order",
            "confidence": 1,
            "isFallback": false,
            "endConversation": false,
            "slots": {
                "firstBeverage": "coffee",
                "secondBeverage": "tea"
            }
        }
    ],
    "status": {
        "code": 200,
        "errorType": "success"
    }
}

Content example with "stream" format

{
    "id": "JeAReNJucU3msuRYvnBRXoeVipt",
    "timestamp": "2021-12-08T17:32:01+01:00",
    "sessionId": "ysRYBCgbze",
    "contexts": [],
    "status": {
        "code": 200,
        "errorType": "success"
    },
    "fulfillment": [
        {
            "source": "Voodoo Woodoo",
            "sourceId": "Tl71GA9trh",
            "items": [
                {
                    "text": "Bienvenue, comment puis-je vous aider ?",
                    "type": "text"
                },
                {
                    "content": {
                        "text": "This is a custom payload, how does it looks?",
                        "type": "cheerful"
                    },
                    "type": "payload"
                },
                {
                    "questions": [
                        {
                            "say question": {
                                "labels": "Password",
                                "output": "password",
                                "required": true,
                                "entity": "ggwg/any",
                                "display": {
                                    "type": "password"
                                }
                            }
                        }
                    ],
                    "buttons": [
                        {
                            "say button": {
                                "type": "event",
                                "text": "Valider",
                                "value": "s3_contact_submit"
                            }
                        }
                    ],
                    "type": "form"
                }
            ]
        }
    ],
    "intents": [
        {
            "source": "Voodoo Woodoo",
            "name": "Welcome Intent",
            "confidence": 1,
            "isFallback": false,
            "endConversation": false,
            "slots": {}
        }
    ],
    "conversationId": "YHLF3qwyuW"
}

Response body¶

The following parameters are send in the response body.

Parameter	Type	Description
query	String	Message the Virtual Agent received from the user if there was a `text` parameter in the request body
fulfillment	Array	List of different Virtual Agent fulfillment
intents	Array	List of intents that are returned Virtual Agents
actions	Deprecated
text	Deprecated
textToSpeech	Deprecated

Fulfillment¶

Parameter	Type	Description
items	Array	Sorted list of items from one Virtual Agent to display in that order

Items¶

Legacy format¶

Parameter	Type	Description
text	String	Default response, simple string
web	String	Response for web purpose, can contain HTML
speaker	String	Response for speaker purpose, can contain SSML
telephony	String	Response for telephony purpose
links	Object	Object that redirect to a web page. It has parameters : `text` Text display to the user, and `value` Website to redirect to
button	Object	Object that send a text request to the Virtual Agent after a button click. It has parameters : `text` Text display to the user, and `value` Query sent to the Virtual Agent
event	Object	Object that trigger an intent with an event name. It has parameters : `text` Text display to the user, and `value` Name of the event to send to the Virtual Agent
cards	Array	List of cards to display to the user. It can contain parameters : `title`, `text`, `image`, `links`, `buttons` and `event`

Stream format¶

Each stream object will be defined by a type field. For each type the stream element object might have a different structure. Here is the different current types :

Parameter	Type	Description
text	String	`text` will be a simple string
richText	String	`text` will be a string that may contain html tags
link	Object	Object that redirect to a web page. It has parameters : `text` Text display to the user, and `value` Website to redirect to
button	Object	Object that send a text request to the Virtual Agent after a button click. It has parameters : `text` Text display to the user, and `value` Query sent to the Virtual Agent
event	Object	Object that trigger an intent with an event name. It has parameters : `text` Text display to the user, and `value` Name of the event to send to the Virtual Agent
card	Array	List of cards to display to the user. It can contain parameters : `title`, `text`, `image`, `links`, `buttons` and `event`
panel	Array	The value will be a `richText` that should be displayed in the side of the actual conversation
file	Array	A file an its URL
form	Array	A form with each different parameters that shall be filled in
group	Array	Describes a group of other stream elements (such as a group of `card`)
payload	Array	This is a free format, you can find anything in there...

Intent¶

Parameter	Type	Description
source	String	Name of the Virtual Agent that found this intent
name	String	Name of the Intent
confidence	String	Confidence score for the intent. Goes from 0 to 1 with 1 as the maximum confidence
isFallback	Boolean	True if the intent is a fallback intent
endConversation	Boolean	True if the conversation with the user just finished
slots	Object	Object with entities names as keys and entity values as value