Unblu documentation

With Unblu, your agents and advisors can:

Visitors to your public website as well as known clients using web or mobile apps are connected through the server to agents and advisors at your firm.

Agents can use the built-in web app or custom mobile apps to interact with visitors. Unblu also enables supervisors to organize teams of agents and assign incoming visitor requests to area experts.

All aspects of both visitor- and agent-side interfaces are flexible and fully customizable, allowing integration with your existing web infrastructure while also enabling interaction though other channels such as custom mobile apps, custom web apps and external messenger services.

Live chat enables visitors to communicate with agents on-demand using Unblu’s text chat capability. The live chat feature is designed specifically for situations where the relationship between visitor and agent is anonymous and conversations are relatively short. A typical use-case would be a help desk scenario.

Secure messenger uses the same text chat capability as Live chat but in a different way. With secure messenger, the system is configured to support long-running relationships between an advisor and a client by maintaining a permanent and continuous conversation history.

In addition to text chat, Unblu can provide a channel for video & voice communication. You can use video & voice and live chat simultaneously or switch between the two.

Unblu has the ability to archive all video and voice interactions.

Embedded co-browsing uses DOM capturing to allow visitors to share their view of your Unblu-enabled website with your agents. This can provide agent with valuable context during a conversation and thus enables them to provide more effective assistance.

From a visitor’s perspective, embedded co-browsing looks like this:

For an agent, this is what embedded co-browsing looks like:

Universal co-browsing uses the rendered co-browsing capability to let conversation participants share their view of any website.

Here is what universal co-browsing looks like from the visitor’s perspective:

This is the agent’s view of the same universal co-browsing session:

Document co-browsing also uses the rendered co-browsing capability. In this case, however, it is to allow the conversation participants to simultaneously view a document such as a PDF that one of the parties has uploaded.

Conversation participants can edit documents together. You can also integrate digital signature solutions like DocuSign to conclude agreements entirely online.

Here is what the document co-browsing interface looks like for visitors:

This is what it looks like for agents:

With mobile app co-browsing, you can provide assistance and advice to visitors as they use your organization’s mobile apps. To do so, integrate Unblu into your apps using the Unblu Mobile SDKs for iOS and Android.

This is what mobile app co-browsing looks like in the Agent Desk:

Screen sharing allows your employees and visitors to collaborate using any application they want. They can choose to share their entire desktop or a single application such as Microsoft Excel.

The following pictures show a screen sharing session where an agent is sharing a spreadsheet application with a visitor.

Here is what the session looks like on the visitor’s side. The Individual UI has been minimized to show the entire collaboration layer:

This is what it looks like in the Agent Desk:

The central organizing concept within the Unblu system is that of the conversation. A conversation in Unblu refers to a communication/collaboration session between a visitor and an agent. A conversation may involve text chat, voice and video and co-browsing of websites and documents.

Depending on your specific use-case, a conversation may be short-lived, as between an anonymous website visitor and a support agent, or it may be long-running, as between a client and a trusted advisor. For more information see Conversations.

In Unblu terminology visitor refers to any client, customer or potential customer that engages with your firm online. The term originates from the idea of a website visitor but we generalize this concept so that it can include:

The agent is the person who represents your firm and interacts with the visitor. This can be:

Text Chat in Unblu refers to the text-based messaging between visitor and agent provided by the Unblu system itself. This medium of communication is used to support two distinct features of the Unblu product: Live Chat and Secure Messenger, which we will discuss in the next section.

Voice and Video refers to the real-time audio/video connection between visitor and agent provided by the Unblu system. In terms of product features, Video and Voice comprises a single feature of its own.

Unblu supports video & voice calls with up to six participants.

Co-browsing refers to the functionality that enables visitors and agents to simultaneously view the same web page or electronic document. This category comprises three distinct product features:

Text chat refers to the text messaging functionality of Unblu that provides real-time text communication between visitor and agent. Most commonly the visitor would chat using the standard visitor interface while the agent uses the agent desk. In other cases either or both parties might use mobile apps or the visitor might use an external messenger service. In all these cases the same basic text chat functionality is leveraged.

The text chat capability is employed as part of the product features Live Chat and Secure Messenger.

Video call refers to the real-time audio/video communications capability of Unblu. In the most common case, visitors engage in the video call via the standard visitor interface, and agents use the Agent Desk. In other cases either or both parties might use mobile apps. In all these cases the same basic video call functionality is leveraged. This capability uses the external service Vonage Video API (formerly TokBox) to provide the audio/video link.

Unblu supports video calls with up to six participants.

The video call capability is a distinct product feature called Video & Voice.

DOM capture co-browsing refers to the capability that allows visitors to co-browse on an Unblu-enabled website, sharing their view of the site with an agent. This technology mirrors the visitor webpage by employing Javascript code that copies the structure of the page’s document object model, and other context information, and transmits it to the agent browser where it is reconstructed.

DOM capture co-browsing technology is used as part of Unblu’s embedded co-browsing feature.

DOM capturing only works on web pages that have been instrumented with Unblu. It therefore only works on the website of the Unblu customer. To support co-browsing of any third-party website requires rendered co-browsing.

Rendered co-browsing refers to a technique for providing co-browsing of third-party websites and documents by visitor and agent. It works by rendering the website or document in a browser running on the Unblu server in headless mode The Unblu server streams the resulting video to both visitors' and agents' browsers simultaneously. The browser instance on the server is called headless because it is a process without a user interface. A separate headless browser instance is required for each visitor-agent co-browsing session. The part of the server responsible for spawning and managing the headless browsers is called the rendering service.

This technology is used for two product features: Universal Co-browsing and Document Co-browsing.

See also: Rendering service and Rendered co-browsing.

This is the main server component. It performs the following major functions:

The specifics of the Unblu server setup depend on the deployment model. For details see Unblu server.

The rendering service is required for universal co-browsing and document co-browsing. If universal or document co-browsing are not licensed, then this component will not be present. The rendering service works by spawning a headless browser instance for each co-browsing session and then streaming the visual rendering of the webpage or document simultaneously to both agent and visitor. See Rendering service.

The database holds all the persistent data needed by the Unblu server including conversation history and other system state. See Database.

To support some features (video/voice, universal and document co-browsing) Unblu relies on two additional components: TokBox and the TURN server. These are external cloud services to which the Unblu Server connects. They do not reside on your infrastructure. See External components.

The Unblu front end includes multiple types of interfaces and integration points for both visitors and agents. They include:

See Front-end and back-end integration for more details.

Unblu also supports custom integrations on the back end using the Web API and Webhooks as well as chatbot integration using the Bot API. See Web API and webhooks.

The Unblu Financial Cloud is Unblu’s cloud service offering. With this service, you receive an account as a tenant on an Unblu system running on our own infrastructure in a secure data center in Switzerland. Under the hood, the Unblu Financial Cloud setup is a clustered deployment similar to one that a customer might have on-premises (see below), except that all management and maintenance of the system is handled by Unblu.

In this model, the Unblu system is installed on your in-house Kubernetes or OpenShift cluster and managed by your company.

In this model the Unblu server is deployed on a Java application server (like Tomcat) using your own infrastructure, managed by your company. Additionally, the rendering service (if present) runs on a Docker engine, either on the same machine or a separate one.

This is the legacy deployment model for pre-Unblu 5. For Unblu 5 and later this model is available but not recommended.

The following diagram gives an overview of the organization of an on-premises application server deployment:

The standalone deployment allows you to install an Unblu server quickly to your local machine. This can be useful in a number of scenarios including, testing, demos or development.

The details of the Unblu Server architecture depend on whether your installation is a cluster deployment or an application server deployment. For general information on these this topic see Deployment models. Here we will cover the specifics of how the Unblu server differs across the models.

The details of the rendering service architecture depend on whether your installation is a cluster deployment or an application server deployment. For general information on this topic see Deployment models. Here we will cover the specifics of how the Unblu server differs across the models.

The database is external to the Unblu Server: In a cluster deployment it is outside the Unblu cluster and in an application server deployment it is outside the application server (usually on a separate machine). In many cases customers can benefit from leveraging the existing database infrastructure of their organization.

Unblu requires a conventional RDBMS, i.e., a SQL-based DB. The supported systems are:

The database is used to store all persistent data required by the Unblu system. This includes

For details on deploying the database and connecting it to the Unblu Server, see Database configuration.

To support voice and video calls, Unblu relies on an external service called Vonage Video API (formerly TokBox). To enable voice and video, the Unblu server must be configured to connect to this service. This configuration does not involve any additional installation on the server side and is identical across deployment models.

To support universal co-browsing, document co-browsing, and screen sharing, Unblu requires a connection to a TURN server.

A TURN server is a standard mechanism for creating such connections between endpoints that are each behind their own firewall. It does so by providing a common location external to the two communicating parties to which each can establish an outbound connection. The TURN server then provides a bridge creating the end-to-end connection.

In universal and document co-browsing, the TURN server is used to provide a video streaming connection between the rendering service on the one hand and the agent and visitor clients on the other.

The recommended approach is to use the Unblu cloud TURN server service.

On the agent side, Unblu provides the Agent Desk and the Account Configuration interface as web interfaces served from the Unblu server out of the box. They do not require any extra work to get them up and running.

The Unblu Web API exposes the functionality of the Unblu server enabling you to perform actions on the server using JSON over HTTP. While the Web API enables external software to initiate actions in Unblu, the Webhooks feature enables the opposite: It lets the Unblu server initiate actions on external system, in response to events occurring in the server. For details, see Web API and webhooks.

The Bot API enables you to integrate an external chatbot system with Unblu, allowing the bot play the role of an agent in interactions with visitors. Typically the bot will be used to handle more formulaic interactions and information collection. As soon as the bot encounters a question it cannot answer the visitor will be redirected to a human agent. See Bot Integration.

The Unblu Financial Cloud gives you all the advantages typical of cloud services in general:

In addition to these, the Unblu Financial Cloud also offers specific benefits:

The use of cloud software is becoming more widespread in the financial industry as regulations are adapted to the new technology and as customers become more familiar with the advantages inherent in the approach.

Our recommendation to our customers is simple: If your organization can (in terms of compliance) choose the Unblu Financial Cloud, then you should.

For details on how to get started see Unblu Financial Cloud onboarding.

While the Unblu Financial Cloud offers many benefits, Unblu does recognize that many customers will prefer an on-premises installation, for a variety of reasons. If this is the case with your organization, the recommended on-premises solution is the Cluster deployment.

Cluster deployment was introduced with Unblu 5 and continues to be the recommended on-premises model for Unblu 6. Previous to Unblu 5 on-premises installations used the Application server deployment. While this type of installation is still possible with Unblu 5 and 6 it is considered deprecated and is not recommended for production systems.

While the application server approach is not recommended for production systems, it still plays a role in the form of the standalone deployment. In this special case of the application server deployment, the runnable web archive file (WAR) unpacks itself and runs the system on an embedded Jetty application server. See Standalone deployment

A big part of the installation process for all on-premises deployments is the configuration of the Unblu system.

Unblu configuration is governed by a single namespace of configuration parameters. On startup the configuration is read from one or more configuration files. Later, once the system is up and running the same configuration namespace is editable via the Configuration Interface.

In the application server and standalone deployments a single configuration file, by convention called unblu-config.properties, is used.

In the cluster deployment a number of configuration files are used in a series of overlays. Customer level configuration is placed in the file unblu-customer.properties.

Once you have a license agreement in place with Unblu, reach out to the Unblu delivery team to discuss the precise technical details of your project so that Unblu can correctly configure your account for your needs. When configuration is complete, you will receive your account details and be able to login as an administrator.

With the Unblu Financial Cloud there is, of course, no server installation or configuration to be done on your end. However, you will still need to do some integration work to enable Unblu for visitors on your website. Optionally, you may also want to enable other integrations for visitors, agents or on the back end.

The primary difference, in terms of integration, between an on-premises installation and the Unblu Financial Cloud setup is that the Individual UI integration is subject to certain restrictions in the latter case.

All other integrations and interfaces are the same.

The Unblu Financial Cloud supports single sign-on (SSO) for both agents and visitors. You can choose to implement single sign-on for agents, or for visitors, or for both.

The technical details of SSO in the Unblu Financial Cloud are discussed in the article single sign-on in the Unblu Financial Cloud.

To begin cluster installation you will need the following:

You might want to check the cluster hardware requirements before you start.

Should you not be able to run kustomize, the Unblu delivery team will send you the already built YAML deployment file.

A Kubernetes cluster requires access to the image registry at all times in order to pull images. Should this be prevented by a company policy, you can use a company internal registry as a proxy. Products such as Artifactory can be used to either manually push images or download images transparently in the background.

Access credentials to the Unblu image registry will usually be provided as a gcr-secret.yaml YAML file. Please apply this file to your cluster before you perform the installation.

Unblu stores all data in a relational database. The credentials to access the database need to be passed to Unblu as a secret named database.

The database secret is used to populate the user configuration. Consequently, you don’t need to manually declare those parameters in the configuration file unblu-customer.properties. In other words you do not need the following lines in unblu-customer.properties:

Other database related configuration is part of unblu-customer.properties file and follows the Unblu configuration standard. Please refer to the section Database configuration for more details.

The Unblu delivery team will send a compressed archive containing a set of files. The listing below assumes that you’ve extracted the bundle into a folder called unblu-installation.

Before deploying Unblu into a cluster, you may want to adjust the following in kustomization.yaml.

Instead of updating the kustomization.yaml that was delivered to you, we recommend to create a new one and separate your customizations from our deliveries.

Upgrading an existing Unblu installation implies the following steps:

For simple configuration updates the first step may be omitted, for Unblu release upgrades all steps are mandatory.

Once you have completed an OpenShift installation, you can check the installation with the following procedure.

The listed instructions must all succeed in order for the smoke test to be successful. Perform the tests immediately after installation to ensure that you don’t miss important log messages.

As an example, here we will describe the installation process on Tomcat.

There are a number of scenarios where it can be useful to deploy an Unblu server quickly to your local machine. For example: testing, demos, development etc. A standalone deployment can be used for these situations.

The Unblu server is available as a WAR file. The file functions both as a traditional WAR file for application server deployment and as an executable JAR file for standalone deployment.

To run Unblu in standalone mode any reasonably modern machine should be sufficient. For example, a machine with the following specs will do the job:

You will also need

and finally, you’ll need the installation package from Unblu, which shuld be provided to you by Unblu delivery. It consists of

As a customer you will typically receive access to a downloadable file with a name like product.com.unblu-<version>-<guid>.war.

The Unblu WAR file can also be used as a executable JAR. An embedded jetty based web server is used in that case. Standalone mode is not suitable for production use.

The embedded Jetty web server will automatically select a TCP port in the range from 6060 to 7070. To manually select the TCP port add -Dport= on the command line.

Unblu is compatible with the database platforms listed below. The version number indicates the oldest version of the database platform supported by Unblu.

Before setup you must ensure the following prerequisites are in place:

These recommendations should be regarded as a starting point. We cannot know how your system may evolve and therefore cannot define exact specifications for your particular needs. Your hardware requirements will be a direct function of the types and volume of data stored.

The above hardware specification should provide capacity for roughly 50,000 sessions per week. This is equivalent to 200 sessions per agent per week for 250 agents.

Unblu uses two distinct database users to operate:

Upon initial setup of the system, the server must be started with the admin user configured so that the DB structure can be established. Once set up, the server will use the regular user, ensuring that security policies can be adhered to. The admin user may then be removed from the Unblu server configuration. To do so, proceed as follows:

Below you will find configuration examples for each database type. For the sake of convenience all users and schemas listed here are called unblu. You may use any name you wish.

A relational database is not an ideal location to store larger binary files such as documents that participants upload to a conversation. We therefore recommend that you use Amazon S3 or a compatible service (e.g. min.io).

All of the settings below can be added at the schema level. For example, the statistics database can become very large over time, so you may want to use a separate server for the statistics database.

Connection and pool parameters can be added to the configuration file. In such a case, all other schemas would use the default connection pool.

Rendered co-browsing refers to the specific co-browsing technology that underlies the Universal Co-browsing and Document Co-browsing product features of Unblu.

For each rendered co-browsing session the Unblu server opens a headless browser on the server. The browser is referred to as "headless" because it is run without its own user interface. However, the visual result of its rendering process is captured and then streamed via WebRTC to both the visitor’s and agent’s browser.

Both the visitor’s and agent’s browsers display the video stream from the headless browser in a "browser-within-a-browser". The rendered content appears within the inner "browser".

Two separate communication channels, one from the visitor back to the headless browser and one from the agent back to the headless browser allow either party to control the headless browser with keyboard and mouse.

The Universal Co-browsing and Document Co-browsing product features are simply two applications of the rendered co-browsing technology. In the first case the headless browser is used by agent and visitor to view any accessible website or web application while in the second case the headless browser is used by agent and visitor to view a document that has been uploaded to the server by one of the parties.

On the server side, the Rendering Service is responsible for managing the headless browsers. Each headless browser runs inside its own container (in the sense of software container, such as Docker).

In clustered Unblu installations each of these containers is in turn run within its own Kubernetes pod. For each rendered co-browsing session, a new pod is spun up in the cluster by the rendering service. When a session ends the pod is removed.

In an application server installation (and indeed in a standalone installation, though this is rarely used) the containers are hosted within a Docker environment within which the rendering service can add and remove headless browser containers on demand.

WebRTC is the technology used to stream the view from the headless browser to both visitor and agent. It is a real-time peer-to-peer video and audio communications technology that is now built into most browsers, requiring no plugins to work (though, on IE 11 a plugin is required).

In the rendered co-browsing case we have at least three peers participating:

One video stream is established from the headless browser to the visitor and another from the headless browser to the agent. There are also two signal channels (implemented separately from WebRTC) in the reverse direction that allow either party to control the browser through keystrokes and mouse input.

For full details on WebRTC and how it works, see webrtc.org.

The browser requirements for WebRTC, and therefore for any feature that requires it (universal co-browsing, document co-browsing) are the same as for Unblu as a whole (see Browser Requirements), with the additional restriction that Internet Explorer is not supported.

At its core WebRTC is a peer-to-peer system, meaning that it is designed to connect two WebRTC endpoints (like two browsers) directly to each other and stream audio and video back and forth without any intervening server. However, for true peer-to-peer communication to work, both parties must be accessible to each other on the same network. In most real-world scenarios involving communication across the internet firewalls and network address translation devices typically prevent this. In the rendered co-browsing scenario this is definitely the case, since:

Taken together, all these restrictions mean that for all practical purposes true peer-to-peer connection for rendered co-browsing would be impossible since it would involve unacceptable security practices like opening up ports in a corporate firewall.

Luckily, WebRTC supports techniques for navigating around these kinds of network restrictions. The specific mechanism used in our case is to connect the WebRTC peers via something called a TURN server.

The TURN server is a specialized server that resides at a publicly accessible network address on the internet. WebRTC peers use the TURN server as an intermediary to communicate with each other.

The types of network restrictions that we discussed above, and that prevent true peer-to-peer communication, typically apply to incoming connections. For example, a typical firewall might prevent all incoming traffic expect HTTP requests on port 80 and HTTPS requests on port 443. However, such a firewall would usually allow outgoing requests from inside the firewall and, crucially, also permit the transit of the responses to those requests back through the firewall.

This means that a component inside a firewall can establish a connection to something outside, as long as:

A TURN server provides exactly this kind of target for both parties in a WebRTC session. Even if neither party can receive unsolicited connections, they can both initiate connections. The TURN server is purposely located on the internet in such a way that it can accept connections.

So, the WebRTC parties both initiate a connection with the TURN server and the TURN server bridges the gap and connects the parties.

Depending on your deployment model and your other requirements there are three options for deploying the TURN Server for rendered browsing:

WebRTC is always end-to-end encrypted. This means that all the data flowing back and forth between the communicating parties is encrypted the entire way.

In some cases, a TURN server can be configured to add a technical participant to a conversation in order to record and archive the conversation. If this is done, then necessarily the encryption between the two original parties is interrupted.

For example, this is an option with the TokBox system that underlies Unblu voice and video service. However, the Unblu cloud TURN server does not support archiving and therefore does provide true end-to-end encryption.

Considering the two deployment issues above it should be clear that

Therefore, from an operational perspective, the Unblu cloud TURN server is the better choice.

When an Unblu-enabled website is initially requested by a visitor’s browser the returned page includes not just the normal website code but also extra code that implements the Unblu visitor interface. This extra Unblu client code is often called the Unblu snippet. It can be included in your website code by either static inclusion or dynamic injection.

As discussed earlier, embedded co-browsing works by capturing the state of the DOM of the Unblu-enabled website on the visitor browser and transferring that state to the agent browser.

Once the DOM has been rebuilt on the agent browser, there are typically additional resources (stylesheets, images, etc.) that the browser must request to complete the rendering of the visitor’s view.

In many cases, these resources will be inaccessible without authentication and authorization, for example, if they are part of a bank’s e-banking site. In normal circumstances, such as in the case of the visitor browser, this does not present a problem since that browser will already be signed in to the site. However, co-browsing is a special case. The agent browser will not have the same authorization as the visitor browser and yet, in order to properly render the visitor’s view, it needs access to the protected resources.

Since uploading the resources from the visitor browser is considered unsafe and would usually be too slow, Unblu solves this problem with the SecureFlow Manager, a software component installed in a proxy in front of the website server that caches the resources and uploads them on demand to the Unblu server, from where the agent browser can successfully request them and build an accurate rendition of the visitor’s view.

The Visitor JS API allows you to load, access and control the Individual UI inside your website. The API directly accesses and communicates with the loaded Unblu code. Any interaction with the API is reflected in the visitor’s Individual UI. For example, if a conversation is opened via the API, it will also be visible in the Individual UI.

The Visitor JS API can only perform actions that the current visitor has the right to perform. For example, if a visitor is allowed to end a conversation, this may be done via the API. If not, an API call to end the conversation will fail with an error.

The visitor JS API is meant to be used for actions directly connected to the current visitor and that visitor’s usage of the Individual UI. This includes things like automatically starting a conversation or starting a call within a conversation that the visitor is already part of.

For actions that require rights beyond those the local visitor has, or that should be independent of the visitor’s UI, consider using the Unblu Web API either directly in JS or via custom REST services provided by your own server.

For information on how to integrate the Visitor JS API with your website, please refer to the Unblu Visitor JavaScript API reference documentation. The reference documentation is updated with the changes of the latest Unblu version.

The reference documentation includes examples to help get you started. Additional examples are available from our GitHub repository.

If you are running an older version of Unblu, you might prefer to view the documentation page directly from your Unblu server. That page describes the JS API as it is available on your server.

You can find your local documentation page at the following address:

The SecureFlow Manager (SFM) is an optional part of the Unblu product, separate from the Unblu server itself. It is designed for site-embedded deployments. These are on-premises installations where the Unblu server and the Unblu-enabled website are both hosted within your company network and exposed to the internet via a web application firewall or other reverse proxy.

The SFM is designed to be integrated into this reverse proxy component. From this position in the network, it can serve two different purposes that enhance the functionality of your Unblu installation:

As discussed in the section Individual UI web integration, you must include the Unblu JavaScript snippet on pages where you wish to enable Unblu. There are two ways to accomplish this:

The SecureFlow Manager is one mechanism that can be used to perform dynamic injection. An alternative would be to inject the snippet using a tag management system. See Dynamic injection with tag management for further details.

Protected resource forwarding enhances the effectiveness of embedded co-browsing. It helps to ensure that pages your visitors and agent are co-browsing look as similar as possible to all participants.

When a visitor requests a page from your Unblu-enabled website, this is roughly what happens:

The visitor’s ability to access the original HTML document and all the subsidiary resources often depends on their having the proper permissions (in an e-banking portal, for example) in the form of a cookie that is transmitted on each request.

How does embedded co-browsing fit into the picture outlined above?

This is the problem that the SecureFlow Manager’s protected resource forwarding is designed to address. It does so by intercepting referenced resources as they transit the reverse proxy on their way to the visitor. It then forwards these resources to the Unblu server’s Resource History. Unblu can then use them, in conjunction with the DOM that it already has, to reconstruct the visitor’s view of the webpage for the agent.

The following diagram depicts the flow of data.

Unblu provides out-of-the-box SecureFlow Manager implementations for the following reverse proxy products:

Before installing the SecureFlow Manager on your specific reverse proxy product (see links below) it will help to understand some aspects of SFM configuration that apply across all products.

As discussed above, the SecureFlow Manager has two responsibilities: code injection and resource forwarding. The precise way that a specific SFM installation performs these functions is based on a set rules that are defined as part of its configuration.

The configuration of the SFM is actually done in the UI of the Unblu server. The Unblu server then translates these configuration settings into an SFM-specific format and this file is provided to the SFM component.

Specific installation instructions for different reverse proxies are available on the following pages:

Please refer to the individual requirements sections for Android and iOS.

The following features of Unblu are available when interacting with the SDKs:

The visitor SDK additionally provides the following features:

The following features are available in co-browsing sessions:

The diagram below shows how the mobile SDKs are integrated into the Unblu environment. Additionally it shows the OpenTok and Firebase Server which are used inside the SDKs via their libraries.

The following configuration properties are important for the mobile SDKs:

For iOS integration, please see iOS mobile SDK integration.

For Android integration, please see Android mobile SDK integration.

To go directly to the SDKs' API documentation, use the following links:

The following configuration properties need to be set for mobile devices to be able to send and receive mobile push notifications from the Unblu server via Firebase Cloud Messaging:

For more information on Firebase Cloud Messaging, please refer to the Firebase documentation. Depending on the operating system you are targeting, please review the Firebase documentation on setting up a Firebase Cloud Messaging client on Android or iOS.

Unblu-specific information is available in the sections iOS mobile SDK integration and Android mobile SDK integration.

The Unblu UI is implemented as an overlaying window. This allows the UI to be displayed either as an actual overlay or visually embedded within another view. As this approach is different from most UIs in Android and iOS, the following pointers should help you integrate Unblu into your app.

This section describes how the visitor/agent SDK can be integrated into an Android app. It describes step by step from adding the AAR files to use the API, whereby it gives some hints to get a good user experience and avoid some common pitfalls.

This section describes how the visitor/agent SDK can be integrated into an iOS app. It describes step by step from adding the framework files to use the API, whereby it gives some hints to get a good user experience and avoid some common pitfalls.

At the moment Unblu provides a generic way to integrate external messengers. An external messenger can be any communication tool which is basically text based, e.g. Email, SMS, WhatsApp.

One external messenger can be represented as multiple external messenger channels inside Unblu server. E.g. In WhatsApp a company can have two business accounts. For each account a channel would be created inside the Unblu server. Those channels are named CustomExternalMessengerChannel. In the future there will be also be tighter integrations of some messengers like WhatsApp into the product.

A conversation is always linked to one channel. Either to Unblu internally itself or to one external messenger channel. This can not be changed afterwards. It means if a conversation should be continued via Unblu internal messaging, a new conversation needs to be created.

Unblu allows integration of different bot types using webhooks and the Unblu Web API. An integration of a bot usually will look something like this:

The center "Bot Integration" piece connects the actual bot framework (like RASA, Microsoft Bot Framework, etc.) with the Unblu server. Webhooks received from the Unblu server are translated into a format understandable by the bot framework and messages and actions from the bot framework are translated to the correct Web API calls on the Unblu server. This allows for the integration of any existing bots into Unblu.

Unblu supports several bot types which may be divided into two groups: dialog bots and conversation-observing bots.

Dialog bots are bots that have a one to one dialog with a visitor during the onboarding, reboarding or offboarding phase of that person.

Conversation-observing bots are bots that can listen to any message in any conversation (or even other webhook events that the Unblu server sends) and chime in when they please.

To participate in a conversation and write messages, a bot always needs a "person" that will represent it. This includes things like the name and the avatar that will be displayed when the bot writes messages.

Like humans, a bot must first join a conversation with their person (giving them an active participation) to enable them to send messages in that conversation. While this is done automatically for dialog bots, it must be done via separate Web API calls for the conversation-observing bots.

Bot persons can be created and updated using the Person API. Different bot backends may share the same bot person.

These bots use generally available webhooks from the Unblu server to detect a situation in which they want to contribute to a conversation.

The integration of this sort of bot uses a rather low-level API that allows a very flexible integration of bots into any conversation. Unblu provides Web APIs to join a conversation with a bot-person and then write different types of chat messages in the name of that bot-person.

When adding a bot to a conversation, one can choose whether the bot’s participant should be visible or hidden. A visible participant behaves like a normal human participant. Hidden participants, on the other hand, will not be displayed in the list of participants (e.g. in the title bar), and no messages are displayed when they join or leave the conversation.

Dialog bots allow tapping into the onboarding, reboarding or offboarding process of a person into or out of a conversation.

Unblu provides a tailored API to participate in this process allowing maximum focus on integrating the underlying bot framework with Unblu and minimum overhead of API calls:

Adding a dialog bot to the onboarding process precludes fast onboarding, because Unblu doesn’t know whether the bot will ask the visitor to answer any questions. This does not mean that the onboarding process will be slower than usual; it merely means that Unblu won’t be able to complete the onboarding process without the visitor opening the conversation.

While the Unblu Web API is useful for making changes to the Unblu server, it is not always ideal for cases where the external system must respond to events generated by the server, since this would involve constantly polling the server to check for changes. The Unblu webhooks provide an alternative mechanism for such use cases.

Webhooks are user-defined HTTP callbacks. They are usually triggered by some event, such as pushing code to a repository or a comment being posted to a blog. When the event occurs, the source site makes an HTTP request to the URL configured for the webhook. Users can configure webhooks in such a way that events on one site invoke behavior on another site.

The webhook mechanism in Unblu lets you register a URL of your choosing to be called by the Unblu server when a specific event occurs. The listening system can then be configured to respond appropriately. For example, an incoming message from a customer could trigger a notification being displayed in the relationship manager’s CRM interface.

Unblu webhooks can be configured either via the Account Configuration interface or the WebhookRegistrations service of the Web API. The available events that can be listened for are documented in the Webhook Events section of the Web API reference. They can be grouped according to the entities they are related to:

The Web API and webhooks are fully documented in the Web API reference.

The same information is also served from your installed Unblu server and can be found at <unblu-server>/unblu/servicesdocumentation. This server-bundled documentation is, of course, aligned with the version of Unblu that you are running.

Additionally, the Web API specification is available in the Open API format to allow for easier integration with third party software. The OpenAPI Specification is a standard way to describe REST web services in a machine-readable format (JSON or YAML).

The Unblu OpenAPI file can be used with other tools supporting this standard, to visualize the endpoints, to perform calls on the Unblu Server or to generate code that can be integrated into your calling application.

The Unblu Server provides one specification file per API version corresponding to the Unblu version that is running. Those are available at this location:

The documents are dynamic and display only the endpoint available to the user currently logged in, depending on the call origin used. They are also available either in YAML (default) or JSON format depending on the Accept header or an optional format query parameter (with value JSON or YAML).

Only user with the superadmin role can manage accounts and can access configuration information (settings, user management, site integration, …​) across multiple accounts. In order to preserve privacy and to be compliant with regulation such as GDPR, a superadmin can not access to conversation content or to any other visitor information of other accounts. Working on data of other accounts is called impersonation.

The configuration page for superadmin is called Global Server Settings and can be accessed with the user menu on the top right corner.

Under Manage accounts, a superadmin can see a list all accounts, create new one and delete existing accounts. To configure a specific account in the list, click on the arrow symbol next to the account name. This causes the current user (the superadmin) to impersonate the admin of that account and opens that account’s configuration page. There, the superadmin can change the configuration settings of the account as if they were the normal admin of that account.

Beside account management the Global Server Settings page is also the place where the current license can be checked and updated by uploading a new file. As well, global settings (valid for all accounts) and translations can also be configured here. The values configured here will be valid for all accounts, unless another value is set at the account level.

The superadmin also has access to some assistance and maintenance tools:

The account overview gives you general information about the current account. You can see the product features available for this account (even if a feature is activated with the global server licence it is possible to prevent its usage at the account level) and you can perform some account modification (account name, account avatar, etc.)

At account level, it is possible to set settings values and translations values that will be valid for the entire account. Some of those configurations can be overridden to a specific value at one of the sublevels (if you want a specific configuration for a given team or for a given named area).

Unblu does user management with the user entity and the team entity (to group users together).

Teams are organized in a tree where each team can be assigned 0 or more sub-teams. It is also possible to not use teams at all, as there is always a default team that is hidden from the user-interface.

Each user belongs to one (and only one) team. Each user also has one (and only one) role, such as REGISTERED_USER for a regular agent.

Different roles have different permissions when managing users. For example, admins can manage users and teams, and supervisors can manage users, in the Account Configuration interface. However, users and teams can only be created, updated, and deleted within Unblu if they are not externally managed, or if the ADMIN role is authorized to override external entity management.

Users cannot create a user with a higher role. This applies to all roles in the system. For other role-based restrictions on user management, please review the descriptions of the various user roles.

To integrate Unblu into the visitor website, some configuration is requested.

An API key is requested to be able to load Unblu from a visitor webpage. If this page is instrumented with the snippet, the API key is part of the URL used to load the snippet. If the page is instrumented using the JS-API, the API key is one of the mandatory parameter used to configure the API before initializing Unblu. Every account has an API key "default" that can be used. For some more advanced scenario (other configurations on different visitor websites) it might be use-full to create additional API Keys.

If the Unblu server is deployed to a different domain than the visitor webpage, which is typically the case when using a cloud solution, then this domain must be declared in the domain section. This ensures that, for a given account, Unblu is not used from unexpected visitor websites.

Named areas are an additional way to change the behavior of Unblu on the visitor website. It is a way to create sub-division of the website. If you are instrumenting the website of a bank, you might want to create named areas for the different services offered by the bank (credit-card, loans & mortgages, investments…) and connect the corresponding pages with the related named area. It is then possible to have different configuration for a named area (other look-and-feel, different concierge flows, …​) Agents can filter incoming chat request based on the named area coupled with the page it was started from.

There are 2 types of named areas, based either on domains or meta tags. If a named area is coupled with a domain, then all pages of the domain will we considered to be part of this named area. With the meta-tag option: a Meta Tag ID is associated with the named area. If you are using the snippet to instrument your must put an additional <meta> tag containing the Meta Tag ID into your HTML If you are using the JS-API or the Mobile SDK you can pass this value to configure the API before initializing Unblu.

Customizing the conversations is an important way change the experience for the visitor.

Supervisors can also access the “Account Configuration” page but the scope of their actions is limited.

There are two levels of configuration: the Account level and the Global Server level. The Account level provides settings for managing a single Unblu account. The Global Server level provides settings for managing things at the server machine level, which may include multiple Accounts. The Account Configuration main page looks like this:

The Global Server Configuration main page looks like this:

When an anonymous visitor launches the Unblu interface on a public website, an ephemeral identity will be automatically generated on the Unblu system for that user and assigned the ANONYMOUS_USER role.

When a customer is authenticated by a protected web application such as an e-banking portal, that authentication is also used by the Unblu server. The user is assigned the WEBUSER role. Users with the WEBUSER role cannot access the Agent Desk.

The REGISTERED_USER role is used for agents using Unblu in your organization. This role grants access to the basic functions of the Agent Desk.

The SUPERVISOR role provides access to the team management functions of the agent desk as well as to the functions enabled by the REGISTERED_USER role.

The ADMIN role grants access to the account-related functions of the Account Configuration interface. In addition, users with this role have access to the same Agent Desk functions as users with the SUPERVISOR role.

The TECHNICAL_ADMIN role is intended for IT specialists who are not authorized to access personally identifiable information (PII) stored in Unblu. The role entails a number of limitations compared to the ADMIN role:

In addition to the permissions granted with the ADMIN role, the SUPER_ADMIN role grants access to the Global Server Configuration interface, enabling users to create and manage accounts on the Unblu server.

When not impersonated into another account, users with the SUPER_ADMIN role can:

When impersonated into another account, users with the SUPER_ADMIN role have the same privileges as if they were in their own account. This may raise concerns about unwarranted access to PII. The configuration property com.unblu.storage.management.limitedImpersonatedSuperAdminUserManagementEnabled addresses these concerns by limiting what SUPER_ADMIN users can do when managing users and teams in another account. When the configuration property is set to true, a SUPER_ADMIN who is impersonated into another account:

The default value of the configuration property is false.

As the role descriptions above suggest, Unblu’s roles are hierarchical in nature: permissions granted to a role further down the hierarchy are inherited by roles further up in the hierarchy. For example, since administrators are able to create teams, superadministrators can, too.

By and large, permission inheritance makes configuration management easier. It can, however, also lead to roles being granted access to features that you don’t want them to have. For this reason, access to some features can be granted to roles individually.

The picture above shows the setting that specifies which roles may delete conversations. As you can see, superadministrators may not do so even though administrators may.

The features that you can grant access to on a per-role basis all have configuration properties whose key begins com.unblu.permission.roleAllowed. Access to the feature to delete conversations, for example, is determined by the configuration property com.unblu.permission.roleAllowed.deleteConversations.

Clearly then, in order to judge the trust level of a request, the Unblu server needs a way of determining the origin of the request. This is done simply: The calling component embeds its call origin in the path prefix of the request URL.

Specifically,

These default path prefixes can be changed via the configuration properties:

Contrast the following two scenarios:

This pattern of distinguishing request URLs by path prefix is used across all requests to the Unblu server.

An immediate question that comes to mind is: "How can relying on the form of the request URL improve security?" After all, any client could potentially construct a query using any path prefix.

In fact, the point of the call-origin system is not really to provide security, but to enable the provision of security, in the larger context of your Unblu server installation.

With call origin enabled, the Unblu server’s URL space is partitioned according to trust level. Enforcing those trust levels requires the framework around the server to ensure that requests requiring a specific trust level only originate from sources that meet that level. To this end, you must set up a reverse proxy in front of the Unblu server that enforces the following restrictions:

Since any organization installing Unblu on-premises will almost certainly already have some type of reverse proxy in place, Unblu’s call-origin system can take advantage of this pre-existing security infrastructure.

The following diagram depicts the key elements related to call origin and authentication of a typical on-premises installation:

By default, the Unblu CSP response headers are turned off. To use the Unblu CSP headers, set com.unblu.contentsecuritypolicy.mode to ON.

Activating CSP improves the security of Unblu by limiting access to resources that comply with the policies you specify. However, sometimes a policy may have unintended side-effects. It may block access to resources that are, in fact, required for your application to function correctly. If you would first like to see whether activating the Unblu CSP headers would result in problems, set com.unblu.contentsecuritypolicy.mode to REPORT_ONLY. Unblu will then send Content-Security-Policy-Report-Only headers rather than Content-Security-Policy headers. Violations of the CSP directives will be displayed in the console of your browser’s developer tools, but the resource will still be loaded. This way, you can verify that all the content security policy directives you have specified will not block access to required resources.

The sets of CSP directives Unblu provides are:

The directives for embedded content include the * wildcard for CSS, fonts, images, and media. This is the default value of the setting com.unblu.contentsecuritypolicy.allowedDomainsForUiResources. If you wish to make the directive more restrictive, simply change the value of this setting accordingly. For example, if static resources for your public website are retrieved from imgs.static.company.com and resources.company.com, you can make the CSP directive more restrictive by one of the following means:

If you do not use Unblu’s video and voice features at present, you can also remove the directives granting access to the domains opentok.com and tokbox.com from the set of directives for the Agent Desk. Simply delete all values of the setting com.unblu.contentsecuritypolicy.tokboxDomains in the Global Server Configuration interface. (This must be done by a user with the superadministrator privileges.)

The Unblu CSP headers are always delivered as HTTP response headers. It is not possible to include them in a meta tag.

Internet Explorer does not support the CSP response header.

Please consult the following resources for further information on the Content-Security-Policy HTTP response header:

There are two ways to set the initial password for the superadmin user, depending on the configuration property com.unblu.storage.superAdminPassword:

If the superadmin password is lost, a new one can be generated by setting the configuration property com.unblu.storage.resetSuperAdmin to true and restarting the collaboration server. This will cause Unblu to generate a new random password and store it in the file credentials.txt, as if no value for the password had been provided during initial setup.

Once the server has restarted, set the aforementioned property to false again, retrieve the password from the file, then delete the file from where it was generated.

When you are on an Unblu-enabled website, all you can see of Unblu to start with is the launcher button. On the web page pictured below, the launcher button is located in the lower right-hand corner of the screen:

By default, clicking on the launcher button opens the Individual UI conversation panel. The panel displays the overview page:

What exactly you see on the overview page depends on a number of factors, such whether it is your first time using Unblu, whether any agents are available to engage with you, and which features of Unblu are available on the page you are currently viewing.

The overview page in the picture above displays five different methods to get in touch with an agent (the actual texts used on your organization’s website may differ):

When you select Chat to a support agent, the conversation panel displays the chat panel. In the example below, the Unblu account has been configured in such a way that the concierge guides visitors through the onboarding process. If active, the concierge asks you some standard questions, e.g. what your name, or which topic you assistance with, before handing your chat request over to an actual agent. Unblu refers to this preparatory work to start a conversation as the onboarding process.

Once you have completed the onboarding process, you can enter messages in the text field at the bottom of the chat panel and send them using the send message button . The messages you receive are shown in the same view, so you can review the entire conversation thread.

If you hover over a message, the copy icon appears. This allows you easily to copy the contents of a message.

The conversation thread also contains system messages with information about what has happened during the conversation, e.g. when a participant joined or left the conversation, or when a participant launched a video call. In the picture above, Sven joined the conversation is such a system message.

Call support launches an audio call with your organization; Video call launches a video call. If the visitor has to go through an onboarding process — to ensure that they have accepted the terms and conditions for the service, for example — the actual call will be started once they have successfully completed the process.

Starting a call launches the call view. Since both audio and video calls use the call view, we will discuss the two conversation types together, pointing out differences where they exist.

The picture below shows the call view of a call in progress.

The main area of the call view is dedicated to the other people in the call. A video call may have up to six participants.

Enter PIN allows you to join a conversation initiated by an agent.

The agent provides you with a PIN, e.g. on the phone, and you enter the PIN in the Individual UI. The PIN is validated once you enter the last digit.

If you enter an invalid PIN, an error message appears beneath the field:

If, on the other hand, you enter the correct PIN before it expires, collaboration starts immediately.

The kind of collaboration that starts is determined by the type of invitation the agent created in the agent desk. In the picture below, the agent invited the visitor to join an embedded co-browsing session. Note the green frame around the tab being shared.

At the top of the screen, the collaboration control states what is being shared and who is sharing it. If you are the one sharing content, the control element provides a button to stop sharing.

The nubs on the left of the collaboration controls allow you to move the controls if they are in the way. Simply grab them with the cursor and move the controls to the left or right. Release them once you happy with the new location of the controls.

If you are collaborating on an embedded co-browsing session, the Individual UI is collapsed, but you can open it and send messages. What’s more, the Individual UI doesn’t appear on the agent’s view of the website you are co-browsing, so they can still see the whole of the page you are on, even if you are typing them a message.

Share Website is a way for you to request an embedded co-browsing session directly. Once an agent answers your request, the collaboration space opens. You and the agent can start collaborating immediately.

To access the Agent Desk, agents must be authenticated. Unblu offers a variety of ways to authenticate users. One way is a traditional login form that asks for your username and password:

Your organization may have opted for a different authentication method. For further information on the various authentication methods available, please consult the authentication page.

The Agent Desk is made up of three areas:

Once you have been authenticated, the Agent Desk opens in the inbox view.

The inbox provides access to all of the conversations you are currently participating in. The conversations are grouped in two tabs, My Conversations and Secondary Conversations.

Each conversation listing provides several useful pieces of information about the conversation:

In the picture above, the agent is the assignee in two conversations, one with Sven, one with Maria. The green badge on each visitor’s avatar shows that they are online. The badge on the My Conversations tab indicates that the Agent has three unread messages in total. There are two unread messages in the conversation with Maria and one in the conversation with Sven.

In the picture of the Secondary Conversations tab below, the Agent Chris Johnson has invited the Agent to join a conversation with the client Viktor Rabe. Chris is online (as indicated by the green badge), but Viktor isn’t. In the top bar of the Agent Desk, you can also see three open conversation views: one with Sven, one with Maria, and one with Viktor and Chris.

The Inbox menu item sports a badge which displays the sum of unread messages in the My Conversations and Secondary Conversations tabs.

To rejoin a conversation, simply click on its listing in the inbox.

For more information on the options available once you answer a conversation, see the section Conversation panel below.

The queue displays all conversations that you could join as the assignee. Like in the inbox, the items in the queue contain useful information about each conversation:

Above the queue, you can see how many conversations are waiting in the queue, and the average time visitors' conversations have been waiting in the queue.

The picture below shows a queue with just one waiting conversation. The toast in the lower left-hand corner of the Agent Desk appears when a request is added to your queue.

The icon to the left of the visitor’s name indicates the type of conversation request.

The effect of clicking on Answer for a conversation in the queue depends on the type of conversation request you are answering. As a rule, the Agent Desks opens the most appropriate view for the request at hand. For example, if you respond to a live chat request, the conversation panel will display the messaging view.

In the upper left-hand corner of the conversation panel, you will see one or more avatars representing the other participants in the conversation. Clicking on a participant’s avatar displays a dropdown containing information on that participant:

In the image above, the user has not been authenticated, so the lock icon in the About section of the dropdown is open. If the user’s authenticated identity had been propagated — because they launched a chat from within e-banking, say — the lock icon would be closed, and their propagated username would be displayed.