Unsolicited Responses

9min
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.
You can send multiple unsolicited response payloads to the UneeQ /speak endpoint and they will be queued for processing. In this way you can continuously cause the digital human to speak as though reading from a teleprompter.
﻿
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.
Hostnames
To send a request to the UneeQ unsolicited responses (/speak) endpoint, you must use the appropriate host for your region:
Region
Region URL
North America
https://api.us.uneeq.io
Europe
https://api.eu.uneeq.io
Oceania
https://api.au.uneeq.io
Request specification
Instruct the digital human for a given sessionId to speak.
POST
Request
Path Params
sessionId
required
String
Customer session Id of the current conversation.
Header Parameters
Content-Type
optional
String
"application/json"
Body Parameters
answer
required
String
The text you set for the digital human to speak.
answerAvatar
optional
String
A stringified JSON containing the instructions* for the digital human.
sessionIdJwt
optional
String
Customer session Id encrypted using the customer JWT secret.
Node.js
Ruby
React
Python
import React, { useState } from "react";
import axios from "axios";
import jwt from "jsonwebtoken";
import "./Unsolicited.css";
import logo from "../../logo.png";

const initialState = {
    sessionId: '',
    jwtToken: '',
    spokenText: ''
}

export default function Unsolicited() {

    const [
        { sessionId, jwtToken, spokenText },
        setState
      ] = useState(initialState);

      const clearTextState = () => {
        setState({
            sessionId,
            jwtToken,
            spokenText: ''
        });
      };

      const clearState = () => {
        setState({...initialState})
      }
    
      const onChange = e => {
        const { name, value } = e.target;
        setState(prevState => ({ ...prevState, [name]: value }));
      };

    function sendUnsolicitedResponse() {
        const signedToken = jwt.sign({"sessionId":sessionId}, jwtToken);
        const body = {
            answer: spokenText,
            answerAvatar: "{}",
            sessionIdJwt: signedToken
        };
        const url = `https://api.us.uneeq.io/api/v1/avatar/${sessionId}/speak`;
        axios.post(url, body)
          .then((response) => {
            clearTextState();
            console.log(sessionId, jwtToken, spokenText)
            console.log(response);
          }) 
          .catch((error) => {
            alert(error);
            clearState();
            console.log(error);
          });
    }

    const handleSubmit = (e) => {
        e.preventDefault();
        sendUnsolicitedResponse();
        console.log(sessionId, jwtToken, spokenText)
    }

    // Creates three text input fields within a form that allows a user to input the
    // Persona ID, JWT Secret, and a message for the digital human to speak
    // The purpose of this component is to allow manual testing 
    return (
        <div className="App">
            <header className="App-header">
                <img src={logo} className="App-logo" alt="logo" />
            </header>
            <div className="App-content mt-10">
                <form onSubmit={handleSubmit}>
                    <ul>
                        <li className="form-row">
                            <label htmlFor="jwtToken" className="inputFieldLabels">JWT Token</label>
                            <input
                                className=""
                                id="jwtToken"
                                value={jwtToken}
                                name="jwtToken"
                                type="text"
                                onChange={onChange}
                            />
                        </li>
                        <li className="form-row">
                            <label htmlFor="sessionId" className="inputFieldLabels">Session ID</label>
                            <input
                                className=""
                                id="sessionId"
                                value={sessionId}
                                name="sessionId"
                                type="text"
                                onChange={onChange}
                            />
                        </li>
                        <li className="form-row">
                            <label htmlFor="spokenText" className="inputFieldLabels">Spoken Text</label>
                            <textarea
                                className="resize"
                                id="spokenText"
                                value={spokenText}
                                name="spokenText"
                                type="textarea"
                                onChange={onChange}
                            />
                        </li>
                        <li className="form-row">
                            <input 
                                type="submit" 
                                value="SEND UNSOLICITED RESPONSE" 
                                className="bg-transparent hover:bg-purple-500 text-purple-700 font-semibold hover:text-white py-2 px-4 border border-purple-500 hover:border-transparent rounded" 
                            />
                        </li>
                    </ul> 
                </form>
             </div>
         </div>
    );
}
import React, { useState } from "react";
import axios from "axios";
import jwt from "jsonwebtoken";
import "./Unsolicited.css";
import logo from "../../logo.png";

const initialState = {
    sessionId: '',
    jwtToken: '',
    spokenText: ''
}

export default function Unsolicited() {

    const [
        { sessionId, jwtToken, spokenText },
        setState
      ] = useState(initialState);

      const clearTextState = () => {
        setState({
            sessionId,
            jwtToken,
            spokenText: ''
        });
      };

      const clearState = () => {
        setState({...initialState})
      }
    
      const onChange = e => {
        const { name, value } = e.target;
        setState(prevState => ({ ...prevState, [name]: value }));
      };

    function sendUnsolicitedResponse() {
        const signedToken = jwt.sign({"sessionId":sessionId}, jwtToken);
        const body = {
            answer: spokenText,
            answerAvatar: "{}",
            sessionIdJwt: signedToken
        };
        const url = `https://api.us.uneeq.io/api/v1/avatar/${sessionId}/speak`;
        axios.post(url, body)
          .then((response) => {
            clearTextState();
            console.log(sessionId, jwtToken, spokenText)
            console.log(response);
          }) 
          .catch((error) => {
            alert(error);
            clearState();
            console.log(error);
          });
    }

    const handleSubmit = (e) => {
        e.preventDefault();
        sendUnsolicitedResponse();
        console.log(sessionId, jwtToken, spokenText)
    }

    // Creates three text input fields within a form that allows a user to input the
    // Persona ID, JWT Secret, and a message for the digital human to speak
    // The purpose of this component is to allow manual testing 
    return (
        <div className="App">
            <header className="App-header">
                <img src={logo} className="App-logo" alt="logo" />
            </header>
            <div className="App-content mt-10">
                <form onSubmit={handleSubmit}>
                    <ul>
                        <li className="form-row">
                            <label htmlFor="jwtToken" className="inputFieldLabels">JWT Token</label>
                            <input
                                className=""
                                id="jwtToken"
                                value={jwtToken}
                                name="jwtToken"
                                type="text"
                                onChange={onChange}
                            />
                        </li>
                        <li className="form-row">
                            <label htmlFor="sessionId" className="inputFieldLabels">Session ID</label>
                            <input
                                className=""
                                id="sessionId"
                                value={sessionId}
                                name="sessionId"
                                type="text"
                                onChange={onChange}
                            />
                        </li>
                        <li className="form-row">
                            <label htmlFor="spokenText" className="inputFieldLabels">Spoken Text</label>
                            <textarea
                                className="resize"
                                id="spokenText"
                                value={spokenText}
                                name="spokenText"
                                type="textarea"
                                onChange={onChange}
                            />
                        </li>
                        <li className="form-row">
                            <input 
                                type="submit" 
                                value="SEND UNSOLICITED RESPONSE" 
                                className="bg-transparent hover:bg-purple-500 text-purple-700 font-semibold hover:text-white py-2 px-4 border border-purple-500 hover:border-transparent rounded" 
                            />
                        </li>
                    </ul> 
                </form>
             </div>
         </div>
    );
}
Responses
200
400
{"status":"BAD_REQUEST","message":"Session has already ended","timestamp":"2022-06-28T00:31:12Z"}
{"status":"BAD_REQUEST","message":"Session has already ended","timestamp":"2022-06-28T00:31:12Z"}
﻿
In the example above, when a 200 OK message is returned with no body, the request has succeeded and the digital human should have spoken the text passed. 
You may see a status 200 with a message that indicates a failure such as the example in the 400 response above, stating that the session has already ended.  In this case, the avatarSessionId used belongs to a terminated session. Start a new session with your digital human, and retrieve the new avatarSessionId to try again.
﻿Digital Human Behavior﻿ *
⚠️ 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
{"sessionId":"<customer-session-id>"}
{"sessionId":"<customer-session-id>"}
﻿
Below are sample javascript codes to generate the sessionIdJWT in two different ways:
Encode without using an external library
JS
function base64url(source) {
	// Encode in classical base64
	encodedSource = CryptoJS.enc.Base64.stringify(source);

	// Remove padding equal characters
	encodedSource = encodedSource.replace(/=+$/, '');

	// Replace characters according to base64url specifications
	encodedSource = encodedSource.replace(/\+/g, '-');
	encodedSource = encodedSource.replace(/\//g, '_');

	return encodedSource;
}

var header = {
	"typ": "JWT",
	"alg": "HS256"
};

var data = {
	"sessionId": "<customer-session-id>"
};

var secret = "<customer-JWT-secret>";

// encode header
var stringifiedHeader = CryptoJS.enc.Utf8.parse(JSON.stringify(header));
var encodedHeader = base64url(stringifiedHeader);

// encode data
var stringifiedData = CryptoJS.enc.Utf8.parse(JSON.stringify(data));
var encodedData = base64url(stringifiedData);

// build token
var token = encodedHeader + "." + encodedData;

// sign token
var signature = CryptoJS.HmacSHA256(token, secret);
signature = base64url(signature);
var signedToken = token + "." + signature;


const payload = JSON.stringify({
        answer: "Is it there anything else I can help you with?",
        answerAvatar: JSON.stringify({"instructions": {
            "expressionEvent": [
                {
                "start": 0.1,
                "value": 1,
                "duration": 3,
                "expression": "browsUpDown"
                },
                {
                "start": 3,
                "value": -1,
                "duration": 3,
                "expression": "browsUpDown"
                }
            ]
        }}),
        sessionIdJwt: signedToken
    });

function base64url(source) {
	// Encode in classical base64
	encodedSource = CryptoJS.enc.Base64.stringify(source);

	// Remove padding equal characters
	encodedSource = encodedSource.replace(/=+$/, '');

	// Replace characters according to base64url specifications
	encodedSource = encodedSource.replace(/\+/g, '-');
	encodedSource = encodedSource.replace(/\//g, '_');

	return encodedSource;
}

var header = {
	"typ": "JWT",
	"alg": "HS256"
};

var data = {
	"sessionId": "<customer-session-id>"
};

var secret = "<customer-JWT-secret>";

// encode header
var stringifiedHeader = CryptoJS.enc.Utf8.parse(JSON.stringify(header));
var encodedHeader = base64url(stringifiedHeader);

// encode data
var stringifiedData = CryptoJS.enc.Utf8.parse(JSON.stringify(data));
var encodedData = base64url(stringifiedData);

// build token
var token = encodedHeader + "." + encodedData;

// sign token
var signature = CryptoJS.HmacSHA256(token, secret);
signature = base64url(signature);
var signedToken = token + "." + signature;


const payload = JSON.stringify({
        answer: "Is it there anything else I can help you with?",
        answerAvatar: JSON.stringify({"instructions": {
            "expressionEvent": [
                {
                "start": 0.1,
                "value": 1,
                "duration": 3,
                "expression": "browsUpDown"
                },
                {
                "start": 3,
                "value": -1,
                "duration": 3,
                "expression": "browsUpDown"
                }
            ]
        }}),
        sessionIdJwt: signedToken
    });
﻿
Encode using a JWT library
JWT libraries are available for many languages. Below we show three examples for common web application languages.
﻿
Node.js
Python
Ruby
// Install package https://www.npmjs.com/package/jsonwebtoken
npm install jsonwebtoken
// Install package https://www.npmjs.com/package/jsonwebtoken
npm install jsonwebtoken
﻿
Synchronous Sign with default (HMAC SHA256)
Node.js
Python
Ruby
var jwt = require('jsonwebtoken');
var token = jwt.sign({ sessionId: '<customer-session-id>' }, '<customer-JWT-secret>');
var jwt = require('jsonwebtoken');
var token = jwt.sign({ sessionId: '<customer-session-id>' }, '<customer-JWT-secret>');
﻿
﻿
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 25 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.
Region	Region URL
North America	https://api.us.uneeq.io
Europe	https://api.eu.uneeq.io
Oceania	https://api.au.uneeq.io
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 25 existing messages are yet to be delivered
500	Server Error	{ "error": ERROR_DESCRIPTION }	Error encountered on server
Bring Your Own conversation platform
Digital Human Behavior