Unblu documentation

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 audio and video communication with up to six participants. You can use audio, video, and live chat simultaneously or switch between the two.

Unblu lets you archive all audio and video 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’s 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 Floating Visitor 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, audio 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.

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

Unblu supports audio and video 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 Unblu’s real-time audio and video communication capabilities. 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 a call service provider to provide the audio and video link.

Unblu supports video calls with up to six participants.

The video call capability is a distinct product feature called audio and video.

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’s 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’s 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 setup depend on the deployment model. For details see Unblu Collaboration Server.

The Rendering Service is required for universal co-browsing, document co-browsing, conversation recording, and the whiteboard. This component isn’t present if your organization hasn’t licensed at least one of these features. 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 the agent and the visitor. See Rendering Service.

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

To support some features (audio and video calls, 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 Collaboration Server connects. They don’t 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 Unblu web API and webhooks as well as chatbot integration using the bot API. See Web API and webhooks.

The Unblu Cloud is Unblu’s cloud service offering. With this service, you receive an account as a tenant on an Unblu system running on Unblu’s own infrastructure in a secure data center. Under the hood, the Unblu 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 Collaboration 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 architecture depend on whether your installation is a cluster deployment or an application server deployment. For general information on this topic, see Deployment models. This section describes how the architecture differs between the cluster and application server 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 audio and video calls, Unblu relies on call service providers. The Collaboration Server must be configured to connect to one of the supported services.

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 Unblu web API enables external software to initiate actions in Unblu, webhooks enable the opposite: they let the Unblu server initiate actions on external systems in response to events occurring in Unblu. 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 Cloud gives you all the advantages typical of cloud services in general:

In addition to these, the Unblu 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 Cloud, then you should.

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

While the Unblu 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. Prior 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 isn’t recommended for production systems.

Running Unblu on an application server isn’t recommended for production systems. It can be useful during development, though. This is referred to a standalone deployment. In a standalone deployment, the runnable web archive file (WAR) unpacks itself and runs the Unblu Collaboration Server on an embedded Jetty application server. For more information, 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 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 Cloud setup is that the Floating Visitor UI integration is subject to certain restrictions in the latter case.

All other integrations and interfaces are the same.

The Unblu 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 Cloud are discussed in the article single sign-on in the Unblu Cloud.

To begin cluster installation you will need the following:

Your cluster must satisfy the following requirements:

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.

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 the following:

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 an executable JAR. An embedded, Jetty-based web server is used in that case.

The embedded Jetty web server will automatically select a TCP port in the range from 6060 to 7070. To specify the TCP port yourself, 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).

Alternatively, you can use Google Cloud Storage.

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.

The audit log stores its entries in the table audit_table. The table may be in a separate database schema or on a different database server entirely. If you choose to store the audit log on a different database server, it must be the same type of database server as the database used by the Unblu server.

There are properties for the audit log database configuration that you can use to override the standard database configuration properties:

For example, if you don’t specify com.unblu.storage.database.audit.url, the audit logs will use the value specified in com.unblu.storage.database.url.

For information on possible database migration issues, see the dedicated article on the subject.

Rendered co-browsing refers to the specific co-browsing technology that underlies the universal co-browsing, document co-browsing, the whiteboard, and conversation recording 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 runs 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.

Universal co-browsing_ and document co-browsing are simply two of the product features that rely on 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’s a real-time peer-to-peer video and audio communications technology that’s now built into most browsers, requiring no plugins to work.

In the rendered co-browsing case there are 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 more information on WebRTC, refer to webrtc.org.

At its core WebRTC is a peer-to-peer system, meaning that it’s 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 behind 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. Adding a TURN server maintains the end-to-end encryption of video content. However, the IP addresses of any participants using it are exposed to the TURN server.

Considering the two deployment issues above:

Therefore, from an operational perspective, we recommend the Unblu Cloud TURN server.

The code snippet below shows how you can apply different behavior when within a universal co-browsing session.

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.

There are cases where you may no longer want the Floating Visitor UI to be available to a visitor. When an agent has been able to answer a visitor’s questions, you might want to remove the Unblu functionality from the page that the visitor is on. You can accomplish this using the Visitor JS API. Please review the documentation on the deinitialize() method for further details.

The Visitor JS API allows you to load, access, and control the Floating Visitor UI inside your website. The API directly accesses and communicates with the loaded Unblu code. Any interaction with the API is reflected in the Floating Visitor UI. For example, if a conversation is opened via the API, it will also be visible in the Floating Visitor 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 Floating Visitor 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.

The Embedded JS API is based on the Visitor JS API and provides similar functionality.

For information on how to integrate the JS APIs with your website, see:

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 pages directly from your Unblu server. Those pages describe the JS APIs as they are available on your server. To make the pages available, enable com.unblu.server.resources.enableDocResources.

You can find your local documentation pages at the following addresses:

For the JavaScript API:

For the Embedded JavaScript API:

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 article Floating Visitor 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:

Refer to the separate requirements sections for Android and iOS.

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

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, refer to iOS mobile SDK integration.

For Android integration, refer to 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, refer to the Firebase documentation. Depending on the operating system you are targeting, 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 a WebView that behaves like any other such element. This allows the UI to be displayed everywhere, and to be integrated into other views with ease.

Although the content displayed is flexible, it does require space to render properly. The view element should therefore take up the entire width of the screen. You should also let it fill a large share of the screen’s height.

The content of the view element isn’t loaded from scratch each time the view’s reattached to the view hierarchy. It preserves its state while it isn’t visible or attached to the view hierarchy.

You can embed Unblu within other elements, but you can’t add external views to the Unblu view element.

This section describes how the 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 text-based, such as email, SMS, WhatsApp.

One external messenger can be represented as multiple external messenger channels inside Unblu server. For example, 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 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:

If you add one or more dialog bots to the onboarding, reboarding, or offboarding process, the messages exchanged during the process will appear as part of a bot thread. To find out more about bot threads, please read the relevant section of our documentation on bot threads and the concierge and the conversation states ONBOARDING, REBOARDING, and OFFBOARDING.

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.

If your bot answers questions visitors enter as free text, it has to parse the text to determine whether it can answer the question. The longer the text the visitor entered, the harder this gets. Long texts can reduce the number of questions the bot can answer. This, in turn, reduces the benefits using a bot provides your organization.

The configuration property com.unblu.conversation.message.chatTextInputMaxLength lets you limit the length of the messages conversation participants can enter. However, it limits the length of all messages, not just those sent in conversations with bots. Furthermore, it’s set in the CONVERSATION or CONVERSATION_TEMPLATE scope, so you have to set it in the template of any conversation that the bot might join.

To limit the length of messages in a bot dialog, you can use the web API endpoint bots/restrictDialogCounterpart after receiving the bot.dialog.opened webhook event. The endpoint requires you to provide the dialog token of the current dialog and the maximum permissible length of a message. The limit only applies to the dialog you call the endpoint for and is reset once you hand off the dialog to an agent or the next bot.

You can change the maximum permissible length during a dialog. This is useful if, for example, you first want to give your bot a chance to answer simple enquiries. For these questions, you might limit the maximum permissible length to, say, 150 characters. When the bot decides it won’t be able to resolve the issue, it can ask the client for a detailed description before handing the conversation off to an agent. For this, you could increase the maximum length to a much larger value such as 1000 characters.

Unblu displays a hint informing the visitor of how many characters they can still enter. Use the configuration property com.unblu.conversation.messaging.ui.charactersRemainingHintThreshold to specify when Unblu should display the hint.

Most of your calls to web API endpoints will come from some backend system. You can, however, make calls from the browser, provided you satisfy two requirements:

Even if you meet these requirements, calling the web API may not be the appropriate way to achieve your goal:

While the Unblu web API is useful for making changes to the Unblu server, it isn’t 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’re 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 Unblu web API reference. They can be grouped according to the entities they’re related to:

For more information on using webhooks with Unblu, see Webhooks technical details.

The web API and a complete list of webhooks are fully documented in the Unblu 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 Unblu 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’s running. Those are available at this location:

The documents are dynamic and display only the endpoints available to the user currently logged in, depending on the entry path used. They’re 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 users 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.

Besides 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. Global settings (valid for all accounts) and texts 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’s 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’s possible to set settings and texts 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 subteams. Unblu supports a maximum of 1000 teams. It’s also possible to not use teams at all, as there is always a default team that’s 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’re not externally managed, or if the ADMIN role is authorized to override external entity management.

Users can’t 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.

Integrating Unblu in the visitor website requires some configuration.

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 parameters used to configure the API before initializing Unblu. Every account has an API key "default" that can be used. For some more advanced scenarios (other configurations on different visitor websites) it might be useful 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 isn’t used from unexpected visitor websites.

Named areas are an additional way to change the behavior of Unblu on the visitor website. It’s a way to create subdivision 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’s 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.

Every resource in Unblu is assigned a minimum level of trust that is required to access it. There are three trust levels, each of which is associated with a different entry path.

From least to most trusted, the levels of trust are:

Requests for a resource on the Unblu server must have a way of demonstrating that they are entitled to access the resource. In other words, a request must be able to signal to the Unblu server which of level of trust it should be assigned.

To do so, Unblu associates the path prefix of each request’s URL with a certain level of trust. This is referred to as the request’s entry path.

The entry paths associated with the different trust levels are specified in the following configuration properties:

The path prefixes must be different. If two or more path prefixes are the same, you will not be able to launch the Unblu server.

You should also ensure that path prefixes don’t overlap, for example by setting one prefix to /foo and another to /foobar. Doing so may result in unexpected behavior.

For a request to succeed against a resource, the request itself must have at least the same trust level as the resource it is requesting.

The ability to determine the level of trust required to complete an HTTP request does not provide security in and of itself. Rather, it enables you to provide security for the Unblu server in the wider context of your company network.

The path prefix used for each entry path is associated with a single level of trust. This neatly partitions the URL space used by the Unblu server along the lines of the levels of trust.

You can make use of this partitioning to restrict access to Unblu’s resources. The Unblu server should be set up behind a reverse proxy that enforces the following rules:

Since any organization installing Unblu on-premises will almost certainly already have some type of reverse proxy in place, Unblu’s entry path concept can take advantage of your existing security infrastructure.

The diagram below depicts the key elements related to the entry path concept and authentication in a typical on-premises installation:

By default, the SYSTEM entry path is disabled. However, the SecureFlow Manager and the Rendering Service needed for universal, document co-browsing, and screen sharing both require that it be enabled.

If you need or want to enable the SYSTEM entry path, set the configuration property com.unblu.systementrypath.enabled to true. Once SYSTEM is enabled, it is essential that you restrict access to the SYSTEM entry path. This can be done by enabling basic authentication configuration properties and com.unblu.systementrypath.basicHTTPAuthenticationPassword, or by implementing protection outside of Unblu (e.g. in a reverse proxy).

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 won’t 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:

You can remove the directives granting access to the domains of the call service providers you don’t use. For example, if Vonage isn’t your call service provider, remove opentok.com and tokbox.com from the set of directives for the Agent Desk. 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 isn’t possible to include them in a meta tag.

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 causes 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.

The superadmin user must always be part of the default team "none". If the user’s a member of any other team, they can’t log in to the Agent Desk.

The Floating Visitor UI consists of four major elements:

The Embedded Visitor UI provides a way of integrating Unblu into your website or single-page application (SPA) so that messaging remains the main focus and content.

To add the Embedded Visitor UI to a page, we provide a custom HTML element. It can be placed anywhere on a page and can be sized any way you like to integrate seamlessly with your UI.

For more information, see the Embedded Visitor UI guide and the Unblu Embedded JavaScript API reference documentation.

The Visitor Desk is a special instance of the Floating Visitor UI that’s hosted on its own page served from the Unblu Server, it’s not integrated into your company web page. The Visitor Desk is used for special cases where an agent wants to send a link to a specific visitor allowing that visitor to communicate through Unblu without actually having to go to the company website.

The way Unblu’s collaborative features are presented can be individualized to fit the page they’re integrated in and corporate design of the customer using configuration properties. This includes theming like colors, button shapes etc., the position of the UI, the texts displayed and the features available for the visitor and much more.

Additionally further customization like the usage of a self-built UI for the Unblu Launcher Button or the PIN-Input can be achieved using the JavaScript APIs.

Unblu syncs the active conversations on a device level. This means a visitor will always be inside of the same conversation for all the tabs they have open in one browser. This makes tab-switching easy since the visitor will always be where they left off on an other tab.

The state of the UI, e.g. If the conversation panel is open or collapsed is stored per tab and will always be restored to the same state when navigating or refreshing as long as the tab stays open.

This category includes all use cases where a visitor has a question and actively uses Unblu to start a conversations. This may be:

These requests will end up in the agents inbound queue and picked up by the next available agent. Typically the full Unblu UI is used for these use cases since the visitor needs the UIs to start conversations and may want to open a past conversation to review the information inside it.

Here the conversation usually starts with a telephone call outside of Unblu. At some point the agent would like to see the visitors screen, starts a new PIN conversation and tells the visitor the PIN via the phone connection.

Depending on the exact use case the visitor will either enter the PIN into a custom UI implemented in the website and the conversation is entered via the Unblu Visitor JS API. In this case the Unblu Launcher Button and Conversation Panel may not be displayed and only the collaboration space and the collaboration layer controls panel will be visible to the visitor.

Alternatively the fully Unblu UI may be used to enter the PIN and join the conversation.

These are conversations where an agent wants to present some content to a visitor and then invite them either by email or by providing them with a generated PIN.

After opening the Conversation Panel they will see the Overview Page. If it is their first interaction using Unblu, they will only see some welcome text, if an agent is available as well as different possibilities to start a new or join an existing conversation. However if they have had previous conversations, all active and past conversations will be accessible from the overview.

From the conversation overview the visitor can navigate to the PIN-Entry page. (This may also be done automatically using the Visitor JS API.) Here the visitor can enter a PIN provided by an agent and will then be automatically navigated into the conversation.

When a visitor opens or joins a conversation, they will always be in one of the conversation views. During a conversation files may always be shared by dragging them onto the Conversation Panel independent which conversation view is active.

The Service status shows the available capacity related to different named areas. Depending on the different filters used for the languages, it also shows capacity for different languages.

This section displays the capacity per agent and their availability. Supervisors can only view the availability of agents in their teams. Admins can see the availability of all the agents of an account.

The config property com.unblu.agentavailability.busyStateSessionLimit defines each agent’s capacity. When they have one active session, the available capacity is reduced by one. If an agent’s status is "away", they aren’t available.

This section shows the ongoing sessions of the agents. For supervisors, only the sessions of their teams are displayed. For admins, all the sessions of the account are displayed.

This section displays the currently used filters for the inbound queues of the agents. It is typically used in combination with the other sections to check, for example, which agents have a certain filter active.