34min

Build Your Own experience

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
|

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 UneeQ Creator. 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 here.
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
|



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

Asia

https://api.sg.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
|



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
|

The specific payloads of messages are defined in the uneeq-js SDK reference documentation.



Browser support

The SDK supports Chrome on both Windows 10 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.