57min

Bring Your Own conversation platform

Any conversation platform can be integrated with your digital human by following the specifications below. The UneeQ Platform can 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:



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
Your value identifying this conversation session as set when obtaining an access token.
fm-custom-data
String
Your ad-hoc values as set when when obtaining an access token.
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 may contain "{\"type\":\"WELCOME\"}" if the Platform is requesting the conversation platform provide a message to greet the user to start the interaction. If this field contains a JSON object it will be stringified.
JSON
|



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
|

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 instructions 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 help@uneeq.com for assistance connecting your conversation platform.

Document image
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).