Build Your Own experience

12min

Getting started
UneeQ makes available our uneeq-js SDK, which allows you to integrate a digital human experience into your website or web application according to your standards. The SDK facilitates communication between that web application and the Platform, and allows you to have full control over your Digital Human implementation.
Example web applications
Check out our example React and Node front end applications to get started. The following video demonstrates how to get up and running with our React example:
﻿
Install
You can install our Javascript SDK through npm using npm install uneeq-js.
Initialization
In order to start a conversation with a digital human you need to create a new instance of the Uneeq class with an options parameter.
JS
let uneeq = new Uneeq(options);
uneeq.initWithToken(token);
let uneeq = new Uneeq(options);
uneeq.initWithToken(token);
﻿
The token used in the initWithToken() method is the one time use token received when your chatbot platform requests a token. Obtain an access token﻿ 
The options parameter tells the UneeQ platform all the information it needs to know to start the conversation. It needs to contain the following properties:
Property
Explanation
Example
conversationId
The ID which identifies the Persona that you wish to start a conversation with. You can find your personaId within the Personas area of the . Otherwise, our Customer Success team can provide you with this ID.
48f0d513-f1ab-49c2-92d5-50318dad6041
url
The URL to the region of the UneeQ platform where your Persona is provisioned. You can find a list of our URLs .
﻿
avatarVideoContainerElement
The HTML Div element that the digital human video will be presented in.
document.getElementById('remoteVideo')
localVideoContainerElement
The HTML Div element that the user's local camera will be presented in. If you don't wish to display the user's camera, you can use the value document.createElement('div')
document.getElementById('localVideo')
messageHandler
Your method which handles real-time message objects from the UneeQ platform
fmMessageHandler (a javascript method you have defined)
playWelcome
Play welcome message. Optional boolean. Default is false.
false
sendLocalVideo
Defines whether the users local video stream (camera) should be sent on session start. Boolean. If true, the user will need to allow permission to use their device. Default value is true.
true
sendLocalAudio
Defines whether the users local audio stream (microphone) should be sent on session start. If true, the user will need to allow permission to use their device. Boolean. Default value is true.
true
JS
const options = {
    url: 'https://api.us.uneeq.io',
    conversationId: 'YourPersonaId',
    avatarVideoContainerElement: document.getElementById('your-div-element'),
    localVideoContainerElement: document.getElementById('your-div-element'),
    messageHandler: (msg) => messageHandler(msg),
    playWelcome: false,
    sendLocalVideo: false,
    sendLocalAudio: true
};
const options = {
    url: 'https://api.us.uneeq.io',
    conversationId: 'YourPersonaId',
    avatarVideoContainerElement: document.getElementById('your-div-element'),
    localVideoContainerElement: document.getElementById('your-div-element'),
    messageHandler: (msg) => messageHandler(msg),
    playWelcome: false,
    sendLocalVideo: false,
    sendLocalAudio: true
};
﻿
﻿
Region URLs
When initializing a Digital Human session, you need to provide the URL where your Digital Human is provisioned.
If you have access to the UneeQ Creator, you can find the correct URL in the Deploy > Build your own area.
Otherwise, please contact your Customer Success representative if you're unsure of the region in which your Digital Human has been provisioned.
Region
Connection URL
North America
https://api.us.uneeq.io
Europe
https://api.eu.uneeq.io
Oceania
https://api.au.uneeq.io
﻿
Sending audio
The Javascript SDK allows customers to speak to a digital human using a ‘push to talk’ interaction mode. This means that a user holds a keyboard key for the period of time they wish to talk to the digital human.
To enable this you need to call the startRecording() and stopRecording() methods at the beginning and end of the period of time you want to capture. The example below enables the user to use the spacebar to talk:
JS
window.onkeydown = (e) => {
    if( e.code === 'Space' && !e.repeat ) {
        uneeq.startRecording();
    }
};
window.onkeyup = (e) => {
    if( e.code === 'Space' && !e.repeat ) {
        uneeq.stopRecording();
    }
};
window.onkeydown = (e) => {
    if( e.code === 'Space' && !e.repeat ) {
        uneeq.startRecording();
    }
};
window.onkeyup = (e) => {
    if( e.code === 'Space' && !e.repeat ) {
        uneeq.stopRecording();
    }
};
﻿
﻿
Conversation events
The Javascript SDK allows you to subscribe to messages from the Platform about the current conversation. To subscribe to these messages a method reference should be passed in as a parameter when instantiating the Uneeq class.
JS
let fmMessageHandler = (msg) => {
    console.log('Uneeq Message: ', msg);
   if( msg.uneeqMessageType === 'Ready' ) {
        //The Digital Human is setup and streaming to the end user
    } else if ( msg.uneeqMessageType === 'AvatarQuestionText' ) {
        //Question asked of the Digital Human
    } else if ( msg.uneeqMessageType === 'AvatarAnswer' ) {
        //Response to the question, including meta data.
    }
};
let fmMessageHandler = (msg) => {
    console.log('Uneeq Message: ', msg);
   if( msg.uneeqMessageType === 'Ready' ) {
        //The Digital Human is setup and streaming to the end user
    } else if ( msg.uneeqMessageType === 'AvatarQuestionText' ) {
        //Question asked of the Digital Human
    } else if ( msg.uneeqMessageType === 'AvatarAnswer' ) {
        //Response to the question, including meta data.
    }
};
﻿
The specific payloads of messages are defined in the uneeq-js SDK reference documentation.
﻿
Browser support
The SDK supports Chrome on both Windows 10/11 and MacOS (High Sierra or later) and Safari on MacOS. It also supports Chrome on Android (6.0 and above) and Safari on iOS (11 or higher) for mobile browsers.
The SDK's browser support is actively maintained for the most recent version of these browsers running on the most recent version of the given operating systems unless otherwise specified.
﻿
Error Handling
At times when an error occurs during the session with the Digital Human, you will receive a SessionErrorMessage(error: string). These are not always fatal and could be a temporary error such as an intermittent network connection. However, it is important to monitor these session error messages for any fatal errors so that your experience can cater to these scenarios accordingly. The following error messages are fatal:
Connection Lost Message
When you receive a ConnectionLostMessage(connectionState: PublishSubscribeState) message, this means that a fatal error has occurred and the connection to the Digital Human has been lost. Your user experience should inform the user that their session has ended due to an error.
Session End Message
You may receive a SessionEndedMessage() if a fatal session error message has been received. If you have not called SDK.endSession() and you receive this message, you will need to inform the user that their session has ended due to an error.

Property	Explanation	Example
conversationId	The ID which identifies the Persona that you wish to start a conversation with. You can find your personaId within the Personas area of the . Otherwise, our Customer Success team can provide you with this ID.	48f0d513-f1ab-49c2-92d5-50318dad6041
url	The URL to the region of the UneeQ platform where your Persona is provisioned. You can find a list of our URLs .
avatarVideoContainerElement	The HTML Div element that the digital human video will be presented in.	document.getElementById('remoteVideo')
localVideoContainerElement	The HTML Div element that the user's local camera will be presented in. If you don't wish to display the user's camera, you can use the value document.createElement('div')	document.getElementById('localVideo')
messageHandler	Your method which handles real-time message objects from the UneeQ platform	fmMessageHandler (a javascript method you have defined)
playWelcome	Play welcome message. Optional boolean. Default is false.	false
sendLocalVideo	Defines whether the users local video stream (camera) should be sent on session start. Boolean. If true, the user will need to allow permission to use their device. Default value is true.	true
sendLocalAudio	Defines whether the users local audio stream (microphone) should be sent on session start. If true, the user will need to allow permission to use their device. Boolean. Default value is true.	true

Region	Connection URL
North America	https://api.us.uneeq.io
Europe	https://api.eu.uneeq.io
Oceania	https://api.au.uneeq.io

Event handling

SDK Reference