Setting up audio and video with Vonage

Requirements

For more information on the technical requirements to conduct video calls, refer to Network requirements for audio and video.

Audio and video configuration

To enable audio and video calls on the Unblu server, you must first retrieve a video API key and secret from the Unblu delivery center and add them to your account configuration. Next, enable audio and video calls by setting the following configuration properties:

com.unblu.messenger.callEnabled: Set to true to enable audio and video calls in Unblu.
com.unblu.conversation.call.callServiceProvider: The call service provider to use for audio and video calls. Set this property to OPENTOK.
com.unblu.conversation.call.tokbox.apiKey: Enter your Vonage Video API key.
com.unblu.conversation.call.tokbox.apiSecret: Enter your Vonage Video API secret.
Select other options as required. See the Conversation call section of the configuration properties reference for an overview of the available options.

Additional configuration steps in on-premises installations

If you’re using video chat with an on-premises installation of Unblu, make sure the Unblu server can connect to https://api.opentok.com. If it must use a forward proxy to reach the site, add the proxy’s details to your configuration.properties file:

com.unblu.conversation.call.tokbox.proxyUrl defines the proxy’s URL. The value consists of:
- The proxy’s type; at present, only HTTP is supported.
- The username and password that Unblu should use when accessing the proxy.
- The proxy’s hostname and port.
  
  The value of the configuration property must be provided in the format http://<username>:<password>@<host>:<port>;. Omit <username>:<password>@ if your proxy doesn’t require authentication.
com.unblu.conversation.call.tokbox.proxyAuthScheme specifies the authentication scheme used. The possible values are BASIC, DIGEST, NTLM, KERBEROS and SPNEGO

Routing client internet traffic

If you’re concerned about transmitting data that could be used to determine your clients' location, use an IP proxy to mediate between the Vonage servers and the video call client applications. To do so, provide the address of the proxy that client applications should use in the configuration property com.unblu.conversation.call.tokbox.clientProxyUrl. The value must be provided in the format http://<username>:<password>@<host>:<port>;. Omit <username>:<password>@ if the proxy doesn’t require authentication.

The IP proxy is used for all traffic other than the media streams of the actual video call. This includes calls to the Vonage Video API, Websocket connections, and log traffic. You must therefore ensure that the proxy you specify is capable of handling calls of these kinds. It must also be capable of handling CORS HTTP headers.

A media server can also be configured to add a technical participant to a conversation so as to record and archive the conversation. If this is done, then necessarily the encryption between the two original parties is interrupted.

Vonage IP whitelisting

Vonage maintains a list of IP address blocks used by the components of their Video API. If you want to limit network traffic related to audio and video calls to these address blocks, set the configuration property com.unblu.conversation.call.tokbox.enableIpWhitelist to true. The value is taken into account when Unblu initiates a session using the Vonage client SDKs.

Before you activate Vonage IP whitelisting, contact a member of the Unblu support team so they can check that your account meets all the requirements.

For more information, refer to Vonage’s IP list documentation.

Vonage Video API server SDK

Once you have set up Unblu to use Vonage, your agents and visitors can initiate sessions. Like any other communication, audio and video calls take place within the context of a conversation. Thus, a conversation must exist before the Unblu Collaboration Server can initiate an audio or video call.

The Collaboration Server calls the Vonage Video API to create a session with the Vonage cloud. It specifies whether to archive the call or not according to your configuration. This choice in turn determines whether the connection between the clients is routed via the Vonage cloud or relayed directly between clients.

Initiating a session

Sessions are initiated using the Vonage Video API server SDK. This requires the Collaboration Server to first create an OpenTok client (if none exists yet) by calling com.opentok.OpenTok.Builder(int apiKey, String apiSecret). The parameter values are taken from the corresponding Unblu configuration properties com.unblu.conversation.call.tokbox.apiKey and com.unblu.conversation.call.tokbox.apiSecret, respectively. If Unblu must access the Vonage cloud via a proxy, the details necessary to do so are also retrieved from the relevant configuration properties.

Once a client is available, the session is created by calling com.opentok.OpenTok.createSession(SessionProperties properties). The SessionProperties object passed as an argument contains only the following information:

The type of session as specified in com.unblu.conversation.call.tokbox.sessionType
Whether all calls should be archived or not. This is defined in com.unblu.conversation.call.tokbox.enableArchiving.
If you enabled vonage-ip-whitelisting, the value of the Session object’s ipWhitelist property is YES.

The call returns a com.opentok.Session object which contains the session ID, which uniquely identifies the session.

The session ID is stored in the tokboxSessionId property of the conversation. It can be used to retrieve archived calls relating to a conversation; refer to the article on call archiving for further details.

Generating a token

Once the Collaboration Server receives the session ID from the Vonage server, it generates a token for each participant in the call and sends it to the participants' respective clients, that is, their browsers or mobile apps. It does so by calling com.opentok.Session.generateToken(TokenOptions options) for each participant in turn. The options argument in the method call always specifies that the token should be valid for 30 seconds and that the participant should be added to the session with the publisher role.

The call returns a string containing the token. The participant’s client can redeem this token to join the session and thus participate in the call.

Establishing a connection to the session

The clients use their token to establish a connection to the session in the Vonage cloud. This allows them to publish audio and video streams to the session. Other participants can then subscribe to these streams.

These steps are all handled by the relevant Vonage client SDK.

Video chat limitations

If a visitor navigates to a new page inside the Unblu-instrumented web page, the video connection is disrupted while the page loads and automatically re-establishes a connection as soon as possible. To work around this, visitors can use the pop-out feature.
The video chat can only be displayed in one browser window or tab. If the visitor has several tabs or windows open and they belong to the same Unblu conversation, the video chat stays in one window. If the user wants to transfer the video chat to a different window, they can do so in the chat user interface.
Currently, Unblu only supports up to six concurrent video chat participants.
Video background blurring is only supported on Google Chrome, Microsoft Edge, and Mozilla Firefox. Safari isn’t suppported.
Enabling video background blurring increases the CPU usage on participant’s computers by 20—30%, irrespective of whether the participant’s background is actually blurred or not.
Due to limitations of the Vonage Video API, media settings dialog always requests access to both the camera and the microphone if video background blurring is disabled.