Synapse

Synapse BYO Conversation Endpoint - Specification

4min

Synapse supports the ability for customers to build an interface to their own conversation service, allowing Synapse to handle tasks like emotion and speech markup, whilst the customer’s application handles the conversation.
When an end user interacts with a digital human which using BYO via Synapse, Synapse will issue a POST request to your endpoint (which you define and control), and will expect to receive a response - Synapse then performs post-processing to add emotion, action, and speech markup, and sends the response for rendering by the digital human.
Request specification
Synapse will send requests to your endpoint using the specification below. Requests are all sent as POST and type application/json, with a payload following the below specification.
Field
Type
Description
sid
String
(SDK only) A value defined by you, to help you identify this conversation session in your own platform, set during a token request when using the SDK (https://docs.uneeq.io/obtaining-an-access-token#BFiF_). Not used for Hosted Experience (will be set to SESSION-ID).
customData
Object
Will contain an object that you declare when starting a conversation, either embedded in a token request when using the SDK (https://docs.uneeq.io/obtaining-an-access-token#BFiF_), or in the customData field when using Hosted Experience (https://docs.uneeq.io/custom-data). This allows you to pass your own key:value pairs that you can use in your conversation service (e.g. to set starting context, such as a user or session identifier). The locale and location fields have specific meanings in Synapse, and both are passed back to you in the userLocale and userLocation fields.
userInput
String
The question the user has asked your digital human.
conversationPayload
String
Will contain whatever value was in the conversationPayload field in your previous response (see below). This field is useful for maintaining session state during a conversation (e.g. the context stack when using an LLM, or a session identifier if using a third-party API). If this field contains a JSON object it will be stringified.
type
String
Will contain either ‘WELCOME’ (if starting a session with playWelcome: true) or ‘QUESTION’. Allows you to differentiate between the first request in a conversation session, and subsequent requests.
uneeqSessionId
String
Set by UneeQ, this is the unique identifier for the user’s conversation session with the digital human. This value is unique to every conversation session and is immutable, so can be used as the unique identifier in your application.
userLocale
String
The value set in locale in customData
userLocation
String
The value set in location in customData
Sample
JS
{
    "sid": "SESSION-ID",
    "customData": {
        "locale": "en-US",
        "location": "38.9124, -77.0917",
        "myCustomField": "Value of myCustomField"
    },
  	"userInput": "What is generative AI?",
  	"conversationPayload": "",
  	"type": "QUESTION",
  	"uneeqSessionId": "18220511-b8bb-4164-9d43-dcf4e33e07b1",
  	"userLocale": "en-US",
  	"userLocation": "38.9124, -77.0917"
}
{
    "sid": "SESSION-ID",
    "customData": {
        "locale": "en-US",
        "location": "38.9124, -77.0917",
        "myCustomField": "Value of myCustomField"
    },
  	"userInput": "What is generative AI?",
  	"conversationPayload": "",
  	"type": "QUESTION",
  	"uneeqSessionId": "18220511-b8bb-4164-9d43-dcf4e33e07b1",
  	"userLocale": "en-US",
  	"userLocation": "38.9124, -77.0917"
}
﻿
Response specification
After receiving and processing a request, your application should respond in the following format.
Response types
Note that while your application can return the following types, Synapse will always generate a ‘friendly’ user facing message - accordingly, you should consider the user experience when handling errors inside your application, and rather than pushing them to the end user (noting that Synapse will intervene and ensure the user always hears the digital human responding, rather than seeing error messages), consider making your application resilient and send informative dialog responses.
Code
Status
Response
200
OK
{ "answer": ANSWER, "instructions": {}, conversationPayload: "" }
400
Bad Request
{ "error": DESCRIPTION }
403
Forbidden
{ "error": DESCRIPTION }
500
Server Error
{ "error": DESCRIPTION }
Body
Field
Type
Description
answer
String
The dialog you want the digital human to speak - Synapse will handle markup, however you can optionally choose to assert your own as per https://docs.uneeq.io/inline-tagging
instructions
Object
Either customData or displayHtml, as per https://docs.uneeq.io/supported-commands
conversationPayload
String
Optional (must be empty string) - anything you send in this field is sent back to your application in the request conversationPayload field with the new request - this allows you to use conversationPayload to store state information such as session IDs or conversation context. If sending JSON, it must be stringified.
Sample
JS
{
    "answer": "Hello! I’m a digital human. How can I help you?",
    "instructions": {
        "displayHtml": {
        "html": "an html string"
        }
  	},
    "conversationPayload": "",
}
{
    "answer": "Hello! I’m a digital human. How can I help you?",
    "instructions": {
        "displayHtml": {
        "html": "an html string"
        }
  	},
    "conversationPayload": "",
}
﻿
﻿

Field	Type	Description
sid	String	(SDK only) A value defined by you, to help you identify this conversation session in your own platform, set during a token request when using the SDK (https://docs.uneeq.io/obtaining-an-access-token#BFiF_). Not used for Hosted Experience (will be set to SESSION-ID).
customData	Object	Will contain an object that you declare when starting a conversation, either embedded in a token request when using the SDK (https://docs.uneeq.io/obtaining-an-access-token#BFiF_), or in the customData field when using Hosted Experience (https://docs.uneeq.io/custom-data). This allows you to pass your own key:value pairs that you can use in your conversation service (e.g. to set starting context, such as a user or session identifier). The locale and location fields have specific meanings in Synapse, and both are passed back to you in the userLocale and userLocation fields.
userInput	String	The question the user has asked your digital human.
conversationPayload	String	Will contain whatever value was in the conversationPayload field in your previous response (see below). This field is useful for maintaining session state during a conversation (e.g. the context stack when using an LLM, or a session identifier if using a third-party API). If this field contains a JSON object it will be stringified.
type	String	Will contain either ‘WELCOME’ (if starting a session with playWelcome: true) or ‘QUESTION’. Allows you to differentiate between the first request in a conversation session, and subsequent requests.
uneeqSessionId	String	Set by UneeQ, this is the unique identifier for the user’s conversation session with the digital human. This value is unique to every conversation session and is immutable, so can be used as the unique identifier in your application.
userLocale	String	The value set in locale in customData
userLocation	String	The value set in location in customData

Code	Status	Response
200	OK	{ "answer": ANSWER, "instructions": {}, conversationPayload: "" }
400	Bad Request	{ "error": DESCRIPTION }
403	Forbidden	{ "error": DESCRIPTION }
500	Server Error	{ "error": DESCRIPTION }

Field	Type	Description
answer	String	The dialog you want the digital human to speak - Synapse will handle markup, however you can optionally choose to assert your own as per https://docs.uneeq.io/inline-tagging
instructions	Object	Either customData or displayHtml, as per https://docs.uneeq.io/supported-commands
conversationPayload	String	Optional (must be empty string) - anything you send in this field is sent back to your application in the request conversationPayload field with the new request - this allows you to use conversationPayload to store state information such as session IDs or conversation context. If sending JSON, it must be stringified.

Synapse

Frequently Asked Questions