Conversation platform integrat...

Bring Your Own conversation platform

14min

Any conversation platform can be integrated with your digital human by following the specifications below. 
The UneeQ Platform will issue POST question requests (what your user has asked your digital human) to an API URL that you define.
Example conversation platform integration
To get started, check out this example conversation platform integration which can connect your digital human to Dialogflow CX, Wolfram Alpha, and Directline among others. This is explained in the following tutorial video:
﻿
Other platform integration examples
﻿Google Dialogflow integration in Ruby﻿
﻿Google Dialogflow integration in Python﻿
Request specification
The UneeQ Platform will POST question requests (what a user has asked your digital human) to your API URL in the format below.
Headers
Key
Value
Content-Type
application/jwt or application/json depending on the body payload type.
Body
JSON
Field
Type
Description
sid
String
A custom field that you can use to set a value identifying this conversation session when . If you do not set a value in this field when you obtain your access token, the field will be an empty string.
fm-custom-data                   
String
Your ad-hoc values as set when you make an initial request for a new session token. See Obtaining an access token for more information.
fm-question
String
The question the user has asked your digital human.
fm-conversation
String
Your value passed to the Platform in any previous response relating to this session. If this field contains a JSON object it will be stringified.
fm-avatar
String
Contextual data the Platform is passing to the conversation platform about the interaction. This field is stringified JSON.
fm-avatar['type']
String
The possible values for 'type' are WELCOMEand  QUESTION WELCOME is sent as the very first request when a new session begins, and is used to indicate that the 'welcome' or beginning intent should be matched and fulfilled. Most NLP engines have a 'start' node, which may need to be programmed to respond to a blank input (as the WELCOME payload does not include any value for fm-question).  All subsequent requests from UneeQ will have QUESTION for the type.
fm-avatar['avatarSessionId']
String
A randomly-generated UUID that identifies the session. This value is unique to each digital human session, and can be used as a conversation identifier. Many NLP engines have a concept of "conversation ID" or "context ID" or "session ID" and this value is often used to create a new conversation identifier within the NLP engine. As this value changes for every new conversation, it cannot be used to identify a returning user. You must persist user-identification within your own platform.
fm-metadata
String
SDK version 2.48.0+ required
Metadata the Platform is passing to the conversation platform, largely about the client.
userSpokenLocale
Language detected when using Speech Recognition STT type
browserDetectedLocales
Language detected from the users browser / device
userTimezone
Timezone detected from the users browser / device
userScreenWidth
User's screen width detected from the users browser / device
userScreenHeight
User's screen height detected from the users browser / device
userAgent
﻿User agent request header﻿
custom
Can be anything the implementer wishes, a stringified json value etc.
Can be set by calling setCustomChatMetadata
This entire metadata field is stringified JSON as shown in the example below
﻿
Body Example
There are two fm-avatar['type'] values: WELCOME and QUESTION
The WELCOME type is sent as the first message when a new session is started.  In this case, the fm-question attribute will be an empty string.
Every request after the first will have the QUESTION type. In this case, the fm-question attribute will be set to the value that the user spoke or typed.
WELCOME:
JSON
{
    "sid": "18220511-b8bb-4164-9d43-dcf4e33e07b1",
    "fm-custom-data": "{}",
    "fm-question": "",
    "fm-conversation":"",
    "fm-avatar": "{\"type\":\"WELCOME\", \"avatarSessionId\": \"5d8e685f-aa66-4fa4-9e1b-37365d497314\"}",
    "fm-metadata": "{\"userSpokenLocale\":\"en-AU\",\"browserDetectedLocales\":\"en-GB\",\"userTimezone\":\"Pacific/Auckland\",\"userScreenWidth\":1977,\"userScreenHeight\":1343,\"userAgent\":\"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/118.0.0.0 Safari/537.36\"},\"custom\":\"{\\\"putWhateverYouWant\\\":\\\"anyValue\\\"}\"}"
}
{
    "sid": "18220511-b8bb-4164-9d43-dcf4e33e07b1",
    "fm-custom-data": "{}",
    "fm-question": "",
    "fm-conversation":"",
    "fm-avatar": "{\"type\":\"WELCOME\", \"avatarSessionId\": \"5d8e685f-aa66-4fa4-9e1b-37365d497314\"}",
    "fm-metadata": "{\"userSpokenLocale\":\"en-AU\",\"browserDetectedLocales\":\"en-GB\",\"userTimezone\":\"Pacific/Auckland\",\"userScreenWidth\":1977,\"userScreenHeight\":1343,\"userAgent\":\"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/118.0.0.0 Safari/537.36\"},\"custom\":\"{\\\"putWhateverYouWant\\\":\\\"anyValue\\\"}\"}"
}
﻿
QUESTION:
JSON
{
    "sid": "18220511-b8bb-4164-9d43-dcf4e33e07b1",
    "fm-custom-data": "{}",
    "fm-question": "Hi, can you please help me?",
    "fm-conversation":"{\"platformSessionId\":\"55b99cc4-7675-44ba-9982-61de7feadf5a\"}",
    "fm-avatar": "{\"type\":\"QUESTION\", \"avatarSessionId\": \"5d8e685f-aa66-4fa4-9e1b-37365d497314\"}",
    "fm-metadata": "{\"userSpokenLocale\":\"en-AU\",\"browserDetectedLocales\":\"en-GB\",\"userTimezone\":\"Pacific/Auckland\",\"userScreenWidth\":1977,\"userScreenHeight\":1343,\"userAgent\":\"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/118.0.0.0 Safari/537.36\"},\"custom\":\"{\\\"putWhateverYouWant\\\":\\\"anyValue\\\"}\"}"
}
{
    "sid": "18220511-b8bb-4164-9d43-dcf4e33e07b1",
    "fm-custom-data": "{}",
    "fm-question": "Hi, can you please help me?",
    "fm-conversation":"{\"platformSessionId\":\"55b99cc4-7675-44ba-9982-61de7feadf5a\"}",
    "fm-avatar": "{\"type\":\"QUESTION\", \"avatarSessionId\": \"5d8e685f-aa66-4fa4-9e1b-37365d497314\"}",
    "fm-metadata": "{\"userSpokenLocale\":\"en-AU\",\"browserDetectedLocales\":\"en-GB\",\"userTimezone\":\"Pacific/Auckland\",\"userScreenWidth\":1977,\"userScreenHeight\":1343,\"userAgent\":\"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/118.0.0.0 Safari/537.36\"},\"custom\":\"{\\\"putWhateverYouWant\\\":\\\"anyValue\\\"}\"}"
}
﻿
Response specification
When you receive a question request, you should respond as per the format below.
Valid Response types
Code
Status
Response
200
OK
{ "answer": ANSWER, "matchedContext": MATCHED_CONTEXT, conversationPayload: CONVERSATION_PAYLOAD }
400
Bad Request
{ "error": ERROR_DESCRIPTION }
403
Forbidden
{ "error": ERROR_DESCRIPTION }
500
Server Error
{ "error": ERROR_DESCRIPTION }
Response field specifications
Field
Type
Description
ANSWER
String
The answer to the question the user has asked the digital human. This is a stringified JSON object as described below.
CONVERSATION_PAYLOAD
String
Any information the conversation platform may need that is used between requests. This value is returned by the Platform in the next request. If this is a JSON object it must be stringified.
MATCHED_CONTEXT
String
Informs the Platform of the intent match the conversation platform made.
ERROR_DESCRIPTION
String
A description of the error which has occurred.
JSON
{
    "answer": "{\"answer\":\"Welcome to UneeQ, how can I help?\",\"instructions\":{}}",
    "matchedContext": "",
    "conversationPayload": "{}"
}
{
    "answer": "{\"answer\":\"Welcome to UneeQ, how can I help?\",\"instructions\":{}}",
    "matchedContext": "",
    "conversationPayload": "{}"
}
﻿
JSON Answer format specification
Field
Type
Description
answer
String
The answer to the question the user has asked the digital human in text.
instructions
String
Any  to be sent, must be a valid JSON object even if empty.
Expected response times
Interactions with digital humans, due to their real time nature are sensitive to latency. Response time is therefore an important factor to take into account when processing requests from the UneeQ Platform. The service level objective for these response times is 200ms at the 95th percentile. The request will generate a web SDK error if the response takes longer than 1000ms, however, the avatar will continue to respond.
﻿
Connect your conversation platform in UneeQ Creator
You can connect your conversation platform by providing your API URL when editing your Persona in the UneeQ Creator. If you don't have access to the Creator, your Customer Success representative can help you get setup, or email [email protected] for assistance connecting your conversation platform.
﻿
Field
Description
Example
API URL
The secure URL you have defined for your conversation platform. This URL must be an https:// address. UneeQ will POST question requests to this URL.
                
﻿
Mutual TLS
⚠️ Please Note:
Currently, Bring Your Own Conversation Platform does not support Mutual TLS (mTLS).
﻿

Key	Value
Content-Type	application/jwt or application/json depending on the body payload type.

Field	Type	Description
sid	String	A custom field that you can use to set a value identifying this conversation session when . If you do not set a value in this field when you obtain your access token, the field will be an empty string.
fm-custom-data	String	Your ad-hoc values as set when you make an initial request for a new session token. See Obtaining an access token for more information.
fm-question	String	The question the user has asked your digital human.
fm-conversation	String	Your value passed to the Platform in any previous response relating to this session. If this field contains a JSON object it will be stringified.
fm-avatar	String	Contextual data the Platform is passing to the conversation platform about the interaction. This field is stringified JSON.
fm-avatar['type']	String	The possible values for 'type' are WELCOMEand QUESTION WELCOME is sent as the very first request when a new session begins, and is used to indicate that the 'welcome' or beginning intent should be matched and fulfilled. Most NLP engines have a 'start' node, which may need to be programmed to respond to a blank input (as the WELCOME payload does not include any value for fm-question). All subsequent requests from UneeQ will have QUESTION for the type.
fm-avatar['avatarSessionId']	String	A randomly-generated UUID that identifies the session. This value is unique to each digital human session, and can be used as a conversation identifier. Many NLP engines have a concept of "conversation ID" or "context ID" or "session ID" and this value is often used to create a new conversation identifier within the NLP engine. As this value changes for every new conversation, it cannot be used to identify a returning user. You must persist user-identification within your own platform.
fm-metadata	String	SDK version 2.48.0+ required Metadata the Platform is passing to the conversation platform, largely about the client. userSpokenLocale Language detected when using Speech Recognition STT type browserDetectedLocales Language detected from the users browser / device userTimezone Timezone detected from the users browser / device userScreenWidth User's screen width detected from the users browser / device userScreenHeight User's screen height detected from the users browser / device userAgent User agent request header custom Can be anything the implementer wishes, a stringified json value etc. Can be set by calling setCustomChatMetadata This entire metadata field is stringified JSON as shown in the example below

Code	Status	Response
200	OK	{ "answer": ANSWER, "matchedContext": MATCHED_CONTEXT, conversationPayload: CONVERSATION_PAYLOAD }
400	Bad Request	{ "error": ERROR_DESCRIPTION }
403	Forbidden	{ "error": ERROR_DESCRIPTION }
500	Server Error	{ "error": ERROR_DESCRIPTION }

Field	Type	Description
ANSWER	String	The answer to the question the user has asked the digital human. This is a stringified JSON object as described below.
CONVERSATION_PAYLOAD	String	Any information the conversation platform may need that is used between requests. This value is returned by the Platform in the next request. If this is a JSON object it must be stringified.
MATCHED_CONTEXT	String	Informs the Platform of the intent match the conversation platform made.
ERROR_DESCRIPTION	String	A description of the error which has occurred.

Field	Type	Description
answer	String	The answer to the question the user has asked the digital human in text.
instructions	String	Any to be sent, must be a valid JSON object even if empty.

Field	Description	Example
API URL	The secure URL you have defined for your conversation platform. This URL must be an https:// address. UneeQ will POST question requests to this URL.

Google Dialogflow ES

Unsolicited Responses