29min

Unsolicited responses

An unsolicited response is the action of a digital human speaking without a direct request from the end user, in other words, when a digital human speaks without a question being asked.

It should be noted that the digital human speaks an unsolicited response only if it is silent. They do not interrupt the user while they are asking questions or when the digital human is speaking.

UneeQ's platform exposes an API which allows for this kind of response push model - it is authenticated based on customer's JWT secret and is not accessible via the SDK.



Sending an unsolicited response

In order to make a digital human speak, an unsolicited response and instructions can be sent to the UneeQ server via an HTTP POST request.



Request specification

Get a cake by its ID
GET
Code examples
Params
Node.js
|
200
404
|

Digital human instructions *



⚠️ If answerAvatar is null or empty, it will be automatically populated with the answer value. You can specify "{}" in answerAvatar if you wish to avoid this.

⚠️By default your answer value will be automatically populated in the AvatarAnswerContentMessage content property, unless you instruct to displayHTML in your request via answerAvatar, in which case the HTML content will be populated.



SessionIdJWT

This is obtained by encrypting the following JSON with the customer JWT secret:

JSON
|

Below are sample javascript codes to generate the sessionIdJWT in two different ways:



Encode using the node JWT library

Encode without using an external library



Response format specification

The response will be JSON with a content type of application/json.

Code
Status
Response
Reason
204
No Content

Successfully sent unsolicited response
400
Bad Request
{ "error": ERROR_DESCRIPTION }
Request body/headers are invalid
401
Unauthorized
{ "error": ERROR_DESCRIPTION }
sessionIdJWT is invalid
403
Forbidden
{ "error": ERROR_DESCRIPTION }
Authorization failed
406
Not Acceptable
{ "error": Avatar response queue limit reached }
A message has been requested to speak when 5 existing messages are yet to be delivered
500
Server Error
{ "error": ERROR_DESCRIPTION }
Error encountered on server



Response limit explained

Currently, the API accepts a maximum of 25 messages to be queued at a time. If more than 25 messages are queued to be spoken, the API returns a 406 Not Acceptable until the existing messages have been dropped, i.e have been spoken by the digital human completely.



Security

This API is secured by verifying that the payload has a sessionId signed using the JWTSecret. This makes sure that the request is coming from a valid client.

This API should always be driven by a backend service, rather than a Front-end app.