of 3

Documentation

Unblu 7 (latest)

This is the main Unblu documentation site.

In the following sections we will introduce you to the Unblu product suite, how it works and how to get started using it.

1. Introduction

1.1. Overview

Unblu is a software suite that lets agents and advisors at your firm engage and interact with your website visitors, customers or clients through multiple online channels. This enables a level of help, advice and relationship-building that was previously only possible face-to-face.

1.2. Why Unblu?

Unblu software is designed specifically with the requirements of financial institutions in mind.

  • Unlike most screen-sharing and co-browsing solutions, with Unblu, website visitors and clients never have to download any extra software to their computers. This enhances security.

  • All communication channels are fully secured.

  • All data resides either on your own infrastructure or in a secure cloud in Switzerland, subject to Swiss financial data regulations.

With Unblu, your agents and advisors can:

  • Help visitors to your website through text chat or video and voice.

  • Securely conduct and keep track of long-running conversations and relationships with clients via text chat, video and voice, through your website or through a dedicated mobile app.

  • Co-browse with website visitors and mobile app users, seeing what they see on their screen, providing valuable context when helping them navigate your website or other online resources.

  • Securely share documents with visitors and clients.

Unblu is Citrix ready. It’s compatible with Citrix’s Virtual Apps and Desktops service, Virtual Desktops, Workspace app, and Virtual Apps.

1.3. How does Unblu work?

Unblu consists of a central server that handles the communication and collaboration between the various parties. The server can be installed on-premises, or you can use the Unblu Cloud.

1.3.1. Visitors

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.

1.3.2. Agents

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.

1.4. Product features

Unblu consists of the following product features:

The communication features Live chat and Video & voice can be used in conjunction with the co-browsing features to provide a richer, more effective user experience. For example, a relationship manager may conduct a video call with a prospective client. When the time comes to sign a contract, they can launch a document co-browsing session to fill in the contract with the client and thus bring the transaction to a successful conclusion.

You can choose to license all of the features or just a subset.

1.4.1. Live chat

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.

1.4.2. Secure messenger

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.

1.4.3. Video & voice

In addition to text chat, Unblu can provide a channel for video & voice communication with up to six participants. 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.

1.4.4. Embedded co-browsing

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:

Visitor view of an embedded co-browsing session
Figure 1. Embedded co-browsing in the floating visitor UI

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

Agent view of an embedded co-browsing session
Figure 2. Embedded co-browsing in the Agent Desk

1.4.5. Universal co-browsing

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:

Visitor view of a universal co-browsing session
Figure 3. A universal co-browsing session in the floating visitor UI

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

Agent view of a universal co-browsing session
Figure 4. A universal co-browsing session in the Agent Desk

1.4.6. Document co-browsing

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:

Visitor view of a document co-browsing session
Figure 5. A document co-browsing session as seen in the floating visitor UI

This is what it looks like for agents:

Agent view of a document co-browsing session
Figure 6. A document co-browsing session as seen in the Agent Desk
Using document co-browsing with files types other than PDF relies on third-party services and involves uploading the files to the servers of those third parties.

1.4.7. Mobile app co-browsing

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:

Mobile app co-browsing in the Agent Desk

1.4.8. Screen sharing

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:

Visitor view of a screen sharing session

This is what it looks like in the Agent Desk:

Agent view of a screen sharing session

1.5. Basics

In this section we will discuss the basic concepts underlying the Unblu system and take a look at some of the key elements of the product.

1.5.1. Conversation

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, video & voice 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.

1.5.2. Visitor

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:

  • Anonymous visitors to your public corporate site.

  • Signed-in users on your service site (for example, e-banking).

  • Clients with whom your representatives have long-running relationships.

1.5.2.1. Visitor interface

The point of contact with the visitor is called the visitor interface. The default and most commonly used one is the Floating Visitor UI web integration. This is a web component that comes out-of-the-box as part of Unblu. It is deployed by integrating its component code with your existing website. It can also be customized to suit your branding and the functionality you wish to expose.

The screenshot below depicts an example of an Unblu-enabled site. Notice that the site includes a launcher button in the bottom right corner:

screen visitor launcher

Clicking on the launcher button opens the floating visitor UI. From here the visitor can begin interacting with an agent at your firm. In this example we see the visitor using text chat to ask for assistance:

screen visitor need assistance

The floating visitor UI also supports video, voice and co-browsing. We will see how these work in later sections. In addition, Unblu also supports custom extensions to the floating visitor UI using the JavaScript APIs and custom mobile apps built with the Mobile SDK. See Front-end interfaces and integrations for more details.

1.5.3. Agent

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

  • A help desk agent who assists website visitors on-demand.

  • An agent who engages with existing e-banking customers to provide information about products or processes at your institution.

  • A relationship manager who has an established relationship with a client and who periodically provides in-depth financial advice.

1.5.3.1. Agent Desk

The Agent Desk is the main interface that Unblu provides for agents. It is a conventional web app served by the Unblu server.

Here we see that the message from the visitor appears in the queue of the agent desk, to wait for an agent to pick it up.

screen agent queue

An agent picks up the conversation from the queue and responds to the visitor.

screen agent how help

Here we see a text chat interaction. The Agent Desk also supports video, voice and co-browsing.

In addition to the web-based Agent Desk, some agent-side tasks can be done via custom mobile apps built with the Mobile SDK. See also, Front-end interfaces and integrations.

1.5.3.2. Teams and supervisors

Agents can be organized into teams with specific people designated as supervisors. Supervisors manage teams and allocate incoming requests to area specialists. Unblu provides specific interfaces for these functions. For example, here we see the Agent Monitor part of the Agent Desk:

agent desk elements 5
1.5.3.3. Administrators and accounts

In addition to agents and supervisors, Unblu also defines the roles of administrator (or admin) and superadministrator (or superadmin).

A single Unblu installation can support multiple tenants or accounts. An admin is responsible for a single account and has rights to configure that account. A superadmin is responsible for the entire Unblu installation and has even more rights,relating to configuring and running the server as a whole.

Unblu provides interfaces for all of these configuration and administration tasks. (see Configuration). For example, here is the Account Settings page:

screen account settings

1.5.4. Text chat

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.

1.5.5. Video & voice

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.

1.5.6. Co-browsing

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:

Embedded co-browsing

Enables the visitor to share with the agent the Unblu-enabled page that they are on.

Universal co-browsing

Enables the visitor or agent to share and simultaneously view a third-party website (not Unblu-enabled).

Document co-browsing

Enables the visitor or agent to share and simultaneously view an electronic document.

1.6. Technical capabilities

In this section we will explore the key technical capabilities of Unblu that support the various product features. Often a single technical capability supports more than one feature, depending on how it is configured. The capabilities are:

  • Text chat

  • Video call

  • DOM-capture co-browsing

  • Rendered co-browsing

Note that these capabilities are defined in terms of the technologies used to implement them and do not align precisely with the set of Unblu product features as seen from a business user’s perspective. Later we will see how the product features are constructed from the technical capabilities. here we examine the capabilities themselves.

1.6.1. Text chat

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.

1.6.2. Video call

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.

1.6.3. DOM capture co-browsing

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.

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

2. Architecture

2.1. Overview

The details of your Unblu setup will differ depending on which deployment model and which optional elements you choose. However, the underlying architecture of the system is essentially the same across all variants.

In this section we will explain this common architecture at an abstract level and then examine how it is actually implemented for each deployment model and how the various optional pieces fit in.

2.2. Elements of the system

An Unblu installation can be divided into the following principal components:

  • Unblu server

  • Rendering service

  • Database

  • External services

  • Front end interfaces and integrations

  • Back end integrations

The following diagram shows how these pieces fit together:

Basic System Components
Figure 7. Basic system components

2.2.1. Unblu server

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

  • User authentication and authorization

  • Managing the communication between the visitor interface and the agent desk via chat, video and voice.

  • Managing embedded co-browsing.

  • Mediating universal and document co-browsing.

  • Managing the configuration settings.

  • Serving the web-based agent desk and admin interface.

  • Providing client and server integration APIs

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

2.2.2. Rendering service

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.

2.2.3. Database

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

2.2.4. External system components

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.

2.2.5. Front-end interfaces and integrations

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

  • Interfaces that are already built-in to the product: Agent Desk, Visitor Desk, Admin Interface, Config Interface.

  • Pre-built components that require integration: Floating Visitor UI, Embedded Visitor UI.

  • APIs and SDKs for building your interfaces: JS API, Visitor and Agent Mobile SDK, External Messenger API.

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

2.2.6. Back-end integrations

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.

2.3. Deployment models

Unblu supports four different deployment models:

  • The Unblu Cloud service

  • On-premises cluster

  • On-premises application server

  • Standalone on a local machine

2.3.1. Unblu Cloud

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.

2.3.1.1. Getting started with the Unblu Cloud

The Unblu delivery team can help get you up and running on the Unblu Cloud. For details see Unblu Cloud onboarding.

2.3.2. On-premises cluster

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

For Unblu 5 and later, cluster deployment is the recommended on-premises deployment model. The application server deployment model that was used for previous versions (see below) is still functional in Unblu 5 and later, but is deprecated. See Recommendations.
2.3.2.1. Kubernetes and OpenShift

Unblu supports all recent versions of the open-source Kubernetes cluster orchestration system as well as the commercial OpenShift variant of Kubernetes. All references to Kubernetes therefore apply to OpenShift as well. Where differences exist, these are noted.

2.3.2.2. About Kubernetes

Kubernetes is a cluster orchestration system designed to simplify the deployment of applications across multiple machines in a cluster. To do this a number of abstractions are employed to insulate the Kubernetes user from the details of the implementation. A quick review of these may help with later discussion of how the Unblu cluster works.

Node

The abstraction representing the physical machine (i.e. a computer). In practice a node may be either a real physical machine or a virtual machine. From the Kubernetes point of view, this distinction is hidden by the abstraction. Nodes are building blocks of the cluster in the sense that a "cluster" is so-called because it is a cluster (an interconnected group) of nodes.

Container

A lightweight environment for isolating running processes within a single physical or virtual machine. Kubernetes uses container technology (like Docker, for example) to organize the running processes in the cluster.

Pod

The essential abstraction used within Kubernetes to enable scalability. A pod is a component that holds one or more containers and constitutes the unit which can be replicated to scale up performance within a cluster. Applications are written to be deployed within pods so that multiple replicas of a pod can be spawned to increase computing power. When more performance is needed the Kubernetes admin can increase the number of pods and Kubernetes takes care of spreading these running processes across the available compute nodes.

2.3.2.3. Cluster system overview

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

Cluster System Components
Figure 8. Cluster system components
2.3.2.4. Getting started with on-premises cluster

The installation of Unblu on a Kubernetes cluster requires that you get access to the install scripts from the Unblu delivery team. For details see Cluster deployment.

2.3.3. On-premises application server

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:

Application Server System Components
Figure 9. Application server system components
2.3.3.1. Getting started with on-premises application server

The installation of Unblu on an application server requires the deployment of the Unblu WAR file, which is available from the Unblu delivery team. For details see Application server deployment.

2.3.4. Standalone 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.

2.3.4.1. Getting started with standalone deployment

To install Unblu in standalone mode you will use the same WAR file as is used in application server deployment. In this case, however, the file doubles as an executable JAR file. When run it unpacks itself and deploys Unblu into an embedded application server. For details see Standalone deployment.

2.4. Unblu server

The Unblu Server is the central component of the Unblu installation. It manages company and user accounts, coordinates all communication (text chat, video, voice), manages co-browsing, serves the agent desk and admin web interfaces, and provides the connection points for API integrations.

2.4.1. Differences across deployment models

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.

2.4.1.1. Cluster architecture

In the earlier, more abstract depiction (Basic System Components) the Unblu server appears as a single component. In the diagram below we see that in a cluster deployment it is composed of a number of separate entities within the cluster.

Unblu Server Cluster System Components
Figure 10. Unblu server cluster system components

Unblu uses the Kubernetes cluster orchestration system. Both Kubernetes itself and the OpenShift variant of Kubernetes are supported. In this system components are deployed in units called pods. Components that require modest resources typically may consist of a single pod while components that require more computing resource can be deployed as multiple replicas of a pod. Some components consist of a fixed number of replicas. Others can be scaled by adding additional replicas as needed.

The Unblu Server consist of the following components, each deployed in one or more pods.

2.4.1.1.1. Unblu server components
Collaboration Server

The core of the Unblu server functionality. This component typically consists of two or more pods.

This component can be scaled by allocating more pods. This ability to increase capacity on demand is one of the key reasons that the cluster model is recommended over the application server model (the other reason is the similar ability to scale the Rendering service).
Kafka

A data streaming and messaging platform that is used to synchronize across the multiple Unblu server core pods in the cluster. The Kafka component is always composed of three pods. See Kafka.

Zookeeper

A system for sharing configuration data across the individual Unblu server pods. The Zookeeper component is always composed of three pods. See Zookeeper.

Prometheus

A metrics collection and alerting system that is used to monitor the cluster. It typically occupies a single pod in the cluster. See Prometheus.

Grafana

Grafana provides visualization of the metrics collected by Prometheus. It typically occupies a single pod in the cluster. See Grafana.

Alert manager

Provides alerts to an external observation service to enable tracking of server behavior. It typically occupies a single pod in the cluster.

Kubernetes Ingress (OpenShift Route)

Incoming requests from agent or visitor web clients are handled by a load balancer which then distributes the request among the Unblu server pods. This component can also be configured to act as a cache. The load balancer and cache can be either external to the cluster or deployed as one or more pod within the cluster.

Proxy

This component provides the SecureFlow Manager with access to upload resources from your Unblu enabled website. It typically consists of one pod.

2.4.1.2. Application server architecture

In the earlier, more abstract depiction (Basic System Components) the Unblu server appears as a single component. In the diagram below we see that in an application server deployment it is implemented as a Unblu server component running within an application server.

Unblu Server Application Server System Components
Figure 11. Unblu server application server system components

Unblu supports most standard Java application servers (Tomcat, JBoss/WildFly, Jetty, GlassFish, Oracle WebLogic, IBM WebSphere, etc.). For more details see Deployment models.

2.5. Rendering service

The rendering service is used to support the universal and document co-browsing features. If your installation does not support one or both of these features, the rendering service will not be present.

When a visitor and agent start a universal or document co-browsing session, the rendering service creates a dedicated headless browser instance (i.e., a browser without a visible user interface shell) for that session. The browser process is used to produce a video rendering of the target document or website which is then streamed to both visitor and agent. One such headless browser instance is spawned for each individual visitor-agent co-browsing session.

2.5.1. Differences across deployment 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.

2.5.1.1. Cluster model

In the cluster model each headless browser instance is run within a separate a Kubernetes pod. As more sessions are started more pods are deployed. The Kubernetes system allocates the pods appropriately across the cluster automatically, spreading the processing load across the available compute resources.

If a customer finds that the rendering service is hitting resource limits regularly, additional compute nodes can be added to the cluster easily. One key advantage of the clustering model over the application server model with respect to the rendering service is precisely this ability to scale the capacity of the system horizontally. This is one of the reasons that the cluster deployment is the recommended setup for Unblu.

In the earlier diagram (Basic System Components) the rendering service appears as a single component. In the diagram below we see that in a cluster deployment it is composed of a number of separate pods, each running a single browser in headless mode.

Rendering Service Cluster System Components
Figure 12. Rendering service cluster system components
2.5.1.2. Application server model

In the application server model the rendering service spawns each headless browser in a dedicated Docker container running on a Docker Engine on the same machine as the Unblu server running in the application server. As more sessions are started more containers are deployed within the Docker Engine.

If a customer finds that the rendering service is hitting resource limits regularly, the server can be scaled vertically (i.e., more memory and disk space can be added) but unlike the clustering case, horizontal scaling is not possible. This is one of the disadvantages of the application server model in comparison to the clustering model and one of the reasons that cluster deployment is the recommended setup for Unblu.

In the earlier diagram (Basic System Components) the rendering service appeared as a single component. In the diagram below we see that in an application server deployment it is composed of a number of docker engine holding a number of containers, each running a single headless browser.

Rendering Service Application Server System Components
Figure 13. Rendering service application server system components

2.6. Database

The Unblu requires an RDBMS to store all persistent data.

Some personally identifiable information (PII) is stored in the Unblu database. This must be taken into consideration when deciding on the deployment details of the database.

2.6.1. Database location

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.

2.6.2. Supported databases

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

  • Oracle 12c, release 2 (12.2.0.1) or later

  • Microsoft SQL Server 2016 or later

  • MySQL 5.7 or later

  • PostgreSQL 10 or later

  • MariaDB 10.2 or later

2.6.3. Stored data

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

Configuration data
  • Users

  • Teams

  • Named areas,

  • API keys

  • Canned responses

  • Conversation templates

  • Tenant accounts

  • Configuration settings

Operational data
  • Conversation state data

  • Text messages exchanged during conversations

  • Documents shared during document co-browsing

2.6.4. Deployment

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

2.7. External components

2.7.1. Vonage Video API

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.

2.7.1.1. Data security

All video and voice calls through the Unblu system traverse the Vonage Video API service. This includes both the actual video and audio streams as well as signalling data used to establish connections. All data is encrypted, both in transit and at rest.

If you wish to archive video and voice calls, the media stream must be decrypted on the Vonage server as part of the archiving process. However, it is immediately re-encrypted, and no unencrypted media stream is ever transmitted on the open internet.

Please review our page on Voice & Video Chat archiving and the Vonage security page for further details.

2.7.1.2. Archiving

Vonage Video API supports encrypted archiving of voice and video sessions. The service can be configured to automatically upload archive data to your own storage as required.

Please review the page on Voice & Video Chat archiving for more information.

2.7.1.3. Administration

The Vonage Video API service is provided through Unblu. Unblu handles the account relationship with Vonage to provide you with a seamless experience. Vonage Video API usage is billed through Unblu.

2.7.2. TURN server

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.

2.7.2.1. Data security

All video traffic related to universal and document co-browsing traverses the TURN server. However, all data is always encrypted.

2.7.2.2. No archiving

Universal co-browsing, document co-browsing, and screen sharing sessions are ephemeral. They are not archived.

2.7.2.3. Administration

The Unblu cloud TURN server is configured and administered by Unblu. Its operation is transparent to you as a customer. There is no charge for data transmitted during universal co-browsing, document co-browsing, or screen sharing.

2.8. Front-end interfaces and integrations

Unblu provides a number of interfaces and interface integration points for both visitors and agents. These include the built-in web interface available out-of-the-box that’s used by agents and administrators, the floating visitor UI web component intended for integration with your website, and APIs and SDKs that enable additional interface channels.

2.8.1. Visitor-side integrations

2.8.1.1. Floating Visitor UI

On the visitor side, the primary interface in most installations is the floating visitor UI.

Before V7, the floating visitor UI was called the Individual UI.

The floating visitor UI is a web component provided by Unblu that is deployed by integrating it into your website. A website in which it is integrated is referred to as "Unblu-enabled".

The floating visitor UI is sometimes referred to as the "snippet" because it is included in the page of your website as a snippet of HTML containing a <script> tag that loads the required JavaScript code. For most customers, the floating visitor UI is the default method through which visitors connect to Unblu. See Floating Visitor UI web integration.

2.8.1.2. Embedded Visitor UI

The embedded visitor UI is a web component provided by Unblu that is deployed by placing the it directly inside your DOM tree with no floating overlay. Its size and position are defined by the website.

It provides visitors with a familiar way to send longer form messages that they already know today from applications like secure email.

2.8.1.3. JavaScript APIs

Unblu offers a JavaScript APIs that you can use within your website to add functionality above and beyond that provided by the integrated visitor UIs. See JavaScript APIs.

2.8.1.4. Visitor Mobile SDK

Using the Visitor Mobile App SDK, you can build custom mobile apps for your visitors to use that support the same features as the floating visitor UI. See Mobile SDK.

2.8.2. Visitor-side built-in interface

2.8.2.1. Visitor Desk

The Visitor Desk is a version of the floating visitor UI that is not integrated into your website. Rather, it is served directly from the Unblu server. It appears as a floating visitor UI in front of a neutral background.

The Visitor Desk is typically used when an agent wants to give a visitor access to Unblu outside the context of any particular webpage. They do so by sending the visitor a link to the Visitor Desk.

2.8.3. Agent-side integration

2.8.3.1. Custom agent mobile app using Mobile SDK

Using the Agent Mobile App SDK, you can build custom mobile apps for your agent.

2.8.4. Agent-side built-in interfaces

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.

2.8.4.1. Agent Desk

The Agent Desk is a conventional desktop browser web application served directly by the Unblu server.

2.8.4.2. Account Configuration interface

The Account Configuration interface is a conventional desktop browser web application served directly by the Unblu server.

2.9. Back-end integrations

In addition to providing many options for front-end integrations (see Front End Interfaces and Integrations) Unblu also enables back end integrations using the Web API, Webhooks and the Bot API.

2.9.1. Web API and webhooks

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.

2.9.2. Bot integration

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.

3. Installation and deployment

3.1. Overview

Previously, in Architecture, we saw how the Unblu system is structured and how the various deployment models affect that structure. In this section we will explain what to consider when choosing which model to use and how to actually perform the installation, deployment or onboarding.

3.2. Recommendations

The first decision to make when adopting Unblu is whether to choose a managed cloud solution or an on-premises solution.

3.2.1. The Unblu Cloud

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

  • Lower IT costs.

  • Costs are part of operational, not capital, expenditure.

  • Always up-to-date software. No installation. No updates.

  • Easy scalability.

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

  • The physical and legal security of Swiss hosting

  • ISO 27001: 2013 certified

  • Compliant with FINMA Guidelines of Circular 2008/7

  • Compliant with SFBC Circular 2005/2 No. 87

  • The technical reliability stemming from Unblu’s expertise in our own product and infrastructure

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.

3.2.2. The on-premises option

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.

3.2.2.1. Single-node cluster

The cluster deployment model has numerous advantages over the older application server model. However, some customers may be concerned about the amount of infrastructure investment required. They may prefer to use single machine rather than the multiple machines typical of a Kubernetes cluster.

You can run Unblu on an application server running a single machine. However, Unblu’s recommendation is to still employ the cluster deployment but to use a single-node cluster.

With the single-node cluster you still only need a single machine, but you have the advantage of being able to seamlessly scale the system later as your needs grow. In addition, the cluster approach also provides you with the following:

  • Health checks automatic restart of components.

  • Metrics and alerting.

  • The ability to easily add a rendering service (if you initially start without this feature).

In short, the single-node cluster is best choice for a "starter" installation that you can later expand.

3.2.3. Standalone

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.

3.3. Configuration files

3.3.1. Overview

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.

3.4. Unblu Cloud onboarding

This section describes the process of onboarding to the Unblu Cloud.

3.4.1. Unblu delivery

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.

3.4.2. Integrations

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.

3.4.2.1. Floating Visitor UI integration

With the Unblu Cloud solution, the following restrictions exist with respect to integrating the floating visitor UI into your company website:

  • The SecureFlow Manager isn’t available, so neither dynamic injection of the client-side code nor protected resource upload are supported.

  • The site-embedded server setup isn’t supported.

In other words, with the Unblu Cloud, your floating visitor UI web integration has the following features:

  • Static injection of client code

  • No protected resource upload

  • Cross-origin server setup

3.4.2.2. Other interfaces and integrations

All other interfaces and integrations work just as they do with an on-premises setup.

  • On the visitor side, the JavaScript API, Visitor Mobile SDK and External Messenger API are fully supported.

  • On the agent side, the Agent Desk and Configuration Interface are available out-of-the-box as usual, and the Agent Mobile SDK is supported.

  • On the back end, the Web API, Webhooks and Bot API are also fully supported.

3.4.3. Single sign-on

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.

3.5. Cluster deployment

3.5.1. Prerequisites

To begin cluster installation you will need the following:

  • A running Kubernetes cluster. This may be an existing cluster already used in production at your organization, a newly installed cluster, or a cloud cluster managed by your organization. (This is distinct from Unblu’s own cloud offering, the Unblu Cloud.) Unblu supports both standard Kubernetes and OpenShift.

  • The Kustomize configuration management tool (this may be already included in your Kubernetes installation as it is integrated into kubectl since 1.14).

  • The Unblu Kustomize bundle used to deploy the software. This will be provided to you by the Unblu delivery team.

  • Access to the Unblu container image registry (gcr.io/unblu-containerrepo-public) to pull the images.

Your cluster must satisfy the following requirements:

  1. You have at least 3 nodes. If you don’t, Unblu’s anti-affinity rules prevent a successful deployment.

  2. You don’t enforce a thread limit, or your thread limit is at least 4096. If you have a lower thread limit, Unblu will run in to errors under load.

    Note that OpenShift 4 enforces a default thread limit of 1024.

  3. You have a working Ingress Controller. The OpenShift Router works fine, too.

  4. Unblu must be able to request persistent volumes using a PersistentVolumeClaim. If it can’t, the pre-configured monitoring stack won’t work.

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.

3.5.2. Access to the Unblu image registry

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.

Listing 1. Create a namespace and apply the image pull secret (Kubernetes)
kubectl create namespace unblu-test
kubectl apply -f gcr-secret.yaml --namespace=unblu-test
Listing 2. Create a project and apply the image pull secret (OpenShift)
oc new-project unblu-test \
    --description="Unblu Test Environment" \
    --display-name="unblu-test"
oc project unblu-test
oc apply -f gcr-secret.yaml

3.5.3. Database secret

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.

Listing 3. Database secret
kind: Secret
apiVersion: v1
metadata:
  name: database
type: Opaque
stringData:
  DB_USER: unblu
  DB_PASSWORD: unblu_password
  DB_ADMIN_USER: unblu_admin
  DB_ADMIN_PASSWORD: admin_password

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:

Listing 4. When using the secret, the following lines are not needed in unblu-customer.properties
com.unblu.storage.database.user=unblu
com.unblu.storage.database.password=<pwd>
com.unblu.storage.database.adminUser=unblu_admin
com.unblu.storage.database.adminPassword=<pwd>

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.

3.5.4. Performing the installation

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.

Listing 5. Build a kustomize bundle and apply the YAML to a cluster
kustomize build unblu-installation > unblu.yaml
kubectl apply -f unblu.yaml

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

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

namespace: customer (1)

bases: (2)
- unblu-kubernetes-base/collaboration-server
- unblu-kubernetes-base/renderingservice
- unblu-kubernetes-base/k8s-ingress
- unblu-kubernetes-base/k8s-prometheus
- unblu-kubernetes-base/grafana

resources: [] (3)

patchesStrategicMerge: [] (4)

configMapGenerator:
- name: collaboration-server-config
  behavior: merge
  files:
    - unblu-customer.properties (5)

secretGenerator:
- name: ingress-tls (6)
  behavior: merge
  files:
    - certs/tls.crt
    - certs/tls.key
  type: "kubernetes.io/tls"

images: (7)
  - name: gcr.io/unblu-containerrepo-public/collaborationserver-public-centos7
    newName: example.com/unblu/collaborationserver-dev-centos7
  - name: gcr.io/unblu-containerrepo-public/headless-browser-public-ubuntu1804
    newName: example.com/unblu/headless-browser-private-ubuntu1804
  - name: gcr.io/unblu-containerrepo-public/nginx-public-centos7
    newName: example.com/unblu/nginx-private-centos7
  - name: gcr.io/unblu-containerrepo-public/haproxy-public-centos7
    newName: example.com/unblu/haproxy-private-centos7
  - name: gcr.io/unblu-containerrepo-public/coturn-public-centos7
    newName: example.com/unblu/coturn-private-centos7
1 Change the namespace (Kubernetes) or project (OpenShift) to be used.
2 Add or remove base modules, depending on your environment or license.
3 Deploy custom components as part of Unblu.
4 Patch some values of the deployment.
5 Add the configuration file unblu-customer.properties to the deployment.
6 Add the TLS certificate as a secret to be used for the Ingress or Route.
7 Rewrite the images source to a new registry.

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.

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

namespace: unblu-production

bases:
- unblu-delivery

3.5.5. Update an existing installation

Upgrading an existing Unblu installation implies the following steps:

  1. Remove the existing deployment from the cluster using clean.sh.

  2. Apply the new deployment, identical to a new installation.

  3. Database patches are automatically applied when the Unblu server starts.

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

Listing 6. clean.sh for Kubernetes
#!/usr/bin/env bash

NAMESPACE="demo-latest"

read -p "Do you really want to clean environment \"$NAMESPACE\"? (y/N) " -n 1 -r
if [[ ! $REPLY =~ ^[yY]$ ]]
then
  exit 1
fi

echo ""
echo "Dropping Unblu"
kubectl delete deployment,pod -n $NAMESPACE -l "component = collaboration-server"
kubectl delete statefulset,pod -n $NAMESPACE -l "component in (kafka, zookeeper)" \
  --force --grace-period=0
kubectl delete deployment,statefulset,pod,service,configmap,persistentvolumeclaim,secret \
  -n $NAMESPACE -l "app = unblu"

read -p "Do you want to drop the metrics platform (Prometheus, Grafana) as well? (y/N) " -n 1 -r
echo

if [[ $REPLY =~ ^[yY]$ ]]
then
  kubectl delete deployment,pod,service,configmap,persistentvolumeclaim,secret \
    -n $NAMESPACE -l "app in (grafana, prometheus)"
fi

echo "Finished"
Listing 7. clean.sh for OpenShift
#!/usr/bin/env bash

oc whoami &>/dev/null
if [ "$?" != "0" ]
then
  echo "You are not logged in to any openshift cluster. Please login first (oc login) and select the correct project"
  exit 1
fi

if [[ ! $1 = "-f" ]]
then
  read -p "Do you want to delete the contents of $(oc project -q) (y/N) " -r
  echo

  if [[ ! $REPLY =~ ^[nNyY]?$ ]]
  then
    echo "Unexpected answer. Exiting"
    exit 2
  fi

  if [[ ! $REPLY =~ ^[yY]$ ]]
  then
    exit 0
  fi
fi

echo "Dropping Unblu"
oc delete deployment,pod -l "component = collaboration-server"
oc delete statefulset,pod -l "component in (kafka, zookeeper)" --force --grace-period=0
oc delete deployment,statefulset,pod,service,configmap,persistentvolumeclaim,secret -l "app = unblu"

read -p "Do you want to drop the metrics platform (Prometheus, Grafana) as well? (y/N) " -n 1 -r
echo

if [[ $REPLY =~ ^[yY]$ ]]
then
  oc delete deployment,pod,service,configmap,persistentvolumeclaim,secret -l "app in (grafana, prometheus)"
fi

echo "Finished"

3.5.6. Smoke test of an OpenShift installation

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.

3.5.6.1. OpenShift deployment status
CLI

oc status

Success criteria

No errors reported.

Example

In an example project on server https://example.intranet.ch:443.

$ oc status

svc/alertmanager - 10.1.1.130:80 -> 9093
  deployment/alertmanager deploys docker.io/prom/alertmanager:v0.16.1
    deployment #1 running for 6 days - 1 pod

svc/blackbox-exporter - 10.1.1.246:80 -> 9115
  deployment/blackbox-exporter deploys docker.io/prom/blackbox-exporter:v0.14.0
    deployment #1 running for 6 days - 1 pod

svc/collaboration-server - 10.1.1.113:9001
  deployment/collaboration-server deploys gcr.io/unblu-containerrepo-public/collaborationserver-centos7:6.0.0-beta.1
    deployment #1 running for 4 days - 1 pod

svc/glusterfs-dynamic-bd5fa376-fb0a-11e9-8274-00ffffffffff - 10.1.1.59:1
svc/glusterfs-dynamic-bd66cca4-fb0a-11e9-8274-00ffffffffff - 10.1.2.62:1
svc/glusterfs-cluster - 10.1.1.255:1

svc/grafana - 10.1.1.56:80 -> 3000
  deployment/grafana deploys docker.io/grafana/grafana:6.2.2
    deployment #1 running for 6 days - 1 pod

svc/haproxy - 10.1.1.9:8080
  deployment/haproxy deploys gcr.io/unblu-containerrepo-public/haproxy-public-centos7:1.9.5-0,docker.io/prom/haproxy-exporter:v0.10.0
    deployment #1 running for 6 days - 2 pods

svc/kafka-hs (headless):9092
svc/kafka - 10.1.1.66:9092
  statefulset/kafka manages gcr.io/unblu-containerrepo-public/collaborationserver-centos7:6.0.0-beta.1
    created 4 days ago - 3 pods

https://example.intranet.ch (redirects) to pod port 8080-tcp (svc/nginx)
  deployment/nginx deploys gcr.io/unblu-containerrepo-public/nginx-public-centos7:1.0,docker.io/nginx/nginx-prometheus-exporter:0.3.0
    deployment #1 running for 6 days - 2 pods

svc/prometheus - 10.1.1.108:80 -> 9090
  deployment/prometheus-server deploys docker.io/prom/prometheus:v2.10.0
    deployment #1 running for 6 days - 1 pod

svc/prometheus-kube-state-metrics - 10.1.1.121:80 -> 8080
  deployment/prometheus-kube-state-metrics deploys docker.io/kube-state-metrics:v1.5.0
    deployment #1 running for 6 days - 0/1 pods

svc/zookeeper-hs (headless) ports 2888, 3888
svc/zookeeper - 10.1.1.249:2181
  statefulset/zookeeper manages gcr.io/unblu-containerrepo-public/collaborationserver-centos7:6.0.0-beta.1
    created 4 days ago - 0/3 pods growing to 3

1 info identified, use 'oc status --suggest' to see details.
3.5.6.2. Unblu server startup status
CLI

$ oc logs <collaborationserverpod name>
for Unix/Linux systems:
$ oc logs $(oc get pods -l component=collaboration-server -o name | cut -d '/' -f 2) | grep "ready for requests"

Success criteria

A message containing "ready for requests" must exist in the logs.

Example
$ oc logs collaboration-server-123

{"message":"Initializing Timer ","logger":"org.eclipse.gemini.blueprint.extender.internal.support.ExtenderConfiguration$1","severity":"INFO","user":"","client":"","page":"","request":"","execution":"","thread":"Start Level: Equinox Container: a46608a9-4214-4f0e-871a-a24812ffffff","@timestamp":"2019-11-01T13:55:15.463Z"}
{"message":"all bundles (247) started in 64039ms ","logger":"com.unblu.platform.server.core.UnbluPlatform","severity":"INFO","user":"","client":"","page":"","request":"","execution":"","thread":"RxComputationThreadPool-1","@timestamp":"2019-11-01T13:55:15.753Z"}
{"message":"Removed down state INITIALIZING. New states [ENTITY_CONFIGURATION_IMPORTING] ","logger":"com.unblu.platform.server.core.UnbluPlatform","severity":"INFO","user":"","client":"","page":"","request":"","execution":"","thread":"RxComputationThreadPool-1","@timestamp":"2019-11-01T13:55:15.753Z"}
{"message":"No entity import source configured ","logger":"com.unblu.core.server.entityconfig.internal.EntityConfigImport","severity":"INFO","user":"","client":"","page":"","request":"","execution":"","thread":"RxComputationThreadPool-1","@timestamp":"2019-11-01T13:55:15.756Z"}
{"message":"Removed down state ENTITY_CONFIGURATION_IMPORTING. New states [] ","logger":"com.unblu.platform.server.core.UnbluPlatform","severity":"INFO","user":"","client":"","page":"","request":"","execution":"","thread":"RxComputationThreadPool-1","@timestamp":"2019-11-01T13:55:15.756Z"}
{"message":"product.com.unblu.universe.core 6.0.0-beta.1-WjNnGKRa ready for requests ","logger":"com.unblu.platform.server.core.UnbluPlatform","severity":"INFO","user":"","client":"","page":"","request":"","execution":"","thread":"RxComputationThreadPool-1","@timestamp":"2019-11-01T13:55:15.756Z"}
{"message":"disabling the agentAvailability auto updating due to request inactivity ","logger":"com.unblu.core.server.livetracking.agent.internal.AgentAvailabilityService","severity":"INFO","user":"","client":"","page":"","request":"","execution":"","thread":"AgentAvail-timer","@timestamp":"2019-11-01T14:55:03.814Z"}
{"message":"unsupported language: en-US falling back to en ","logger":"com.unblu.platform.server.clientsupport.internal.AbstractEntryPointWrapperServlet","severity":"WARN","user":"","client":"","page":"","request":"ROxknrGXQCuse2Q3CMFu2Q","execution":"","thread":"qtp1897380042-37","@timestamp":"2019-11-05T16:13:49.036Z"}
{"message":"unsupported language: en-US falling back to en ","logger":"com.unblu.platform.server.clientsupport.internal.AbstractEntryPointWrapperServlet","severity":"WARN","user":"","client":"","page":"","request":"TXaZh7OxRhW2N6tFtRHJ9g","execution":"","thread":"qtp1897380042-42","@timestamp":"2019-11-05T16:13:49.067Z"}
{"message":"enabling agentAvailability auto updating ","logger":"com.unblu.core.server.livetracking.agent.internal.AgentAvailabilityService","severity":"INFO","user":"","client":"","page":"","request":"TXaZh7OxRhW2N6tFtRHJ9g","execution":"","thread":"qtp1897380042-42","@timestamp":"2019-11-05T16:13:49.087Z"}
{"message":"unsupported language: en-US falling back to en ","logger":"com.unblu.platform.server.clientsupport.internal.AbstractEntryPointWrapperServlet","severity":"WARN","user":"","client":"","page":"","request":"_Drn9FNIRaODTCAqZiuSug","execution":"","thread":"qtp1897380042-37","@timestamp":"2019-11-05T16:14:07.306Z"}
{"message":"unsupported language: en-US falling back to en ","logger":"com.unblu.platform.server.clientsupport.internal.AbstractEntryPointWrapperServlet","severity":"WARN","user":"superadmin","client":"","page":"","request":"G5UzUttIRmCkc3QXUbR3Pw","execution":"","thread":"qtp1897380042-39","@timestamp":"2019-11-05T16:14:09.965Z"}
{"message":"sessionItem prepared: TrackingItem type: TRACKINGLIST status: OPEN id: null details: accountId=wZvcAnbBSpOps9oteH-Oxw&status=OPEN&type=AGENTFORWARDING session: hPAkysS1Qqa7V5DVLrth7w node: collaboration-server-559b6487c8-qzqkx node instance: 1x2j3Qn_T--dszMYT_MI8g created: Tue Nov 05 16:14:11 UTC 2019  ","logger":"com.unblu.core.server.collaboration.CollaborationSession","severity":"INFO","user":"","client":"","page":"","request":"UR8u7Fh6TJCRaeJfKBPmxA","execution":"CollaborationSessionStore","thread":"RxCachedThreadScheduler-1 - CollaborationSessionStore -  $ FixedContextScheduler#CollaborationSessionStore $ ","@timestamp":"2019-11-05T16:14:11.554Z"}
3.5.6.3. Check browser access
Browser
  • Open a browser and open the agent desk domain. For example https://example.intranet.ch:443/app/desk.

  • Perform login.

Success criteria

Unblu displays the login screen and after login, the agent desk. There are no errors in the browser console.

3.5.6.3.1. JavaScript demo page and documentation

If you need to use the Unblu JavaScript demo page, you can activate it by setting com.unblu.server.resources.enableDemoResources to true. If you also want the Unblu docs available locally, set com.unblu.server.resources.enableDocResources to true.

3.6. Application server deployment

Unblu can be deployed on any Java application server (i.e., any server that functions as a Java Servlet Container, implementing the Java Servlet API). You should consult your application server documentation to get the specific installation directions.

3.6.1. Deploying Unblu on Tomcat

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

At present, Unblu is not compatible with Tomcat 10, which targets Jakarta EE rather than Java EE. Unblu is compatible with Jakarta EE 8; it is not compatible with Jakarta EE 9 or 10. Deploy Unblu on Tomcat 9.
3.6.1.1. Preparation

To begin with, you will need the following:

  • Suitable hardware on which to deploy the application server. See System Requirements.

  • Java 11 Unblu only targets long-term support (LTS) versions of Java. See Oracle’s Java SE Support Roadmap for further information.

  • An installed Tomcat server. Consult the Tomcat documentation for details on installation.

  • The Unblu WAR file, typically called product.com.unblu-<version>-<guid>.war

  • The Unblu properties file, typically called unblu-config.properties

The Unblu files should be provided to you by the Unblu delivery team.

3.6.1.2. Deployment
In Tomcat terminology $CATALINA_HOME is the Tomcat home directory. If your Tomcat is properly installed, this environment variable should point to the location of the Tomcat installation.
3.6.1.2.1. Configuration file

To ensure that Unblu starts up properly upon deployment, you need to install the unblu-config.properties file so that Tomcat reads it on startup. The recommended way of doing this is:

  1. Copy unblu-config.properties to $CATALINA_HOME/conf

  2. In the file $CATALINA_HOME/bin/catalina.sh insert the following line at the top of the file:

    export JAVA_OPTS="$JAVA_OPTS -Dcom.unblu.propertyoverlay=file:///$CATALINA_HOME/conf/unblu-conf.properties"

Once you have made this change, restart Tomcat.

3.6.1.2.2. Context path

In Tomcat (and other application servers), applications have a context path. This is simply the URI path (relative to the hostname of the server) where you point your browser to access the application. An application can be deployed either to the root context or a non-root context.

Assuming that the server is at http://<tomcat>/ then a typical non-root context for an Unblu install would be

`\http://<tomcat>/unblu/`

Alternatively, if Unblu were deployed to the root context then its URI would be identical to that of the Tomcat server itself:

`\http://<tomcat>/`
3.6.1.2.3. Non-root context deployment

To deploy to a non-root context, the simplest method is:

  1. Rename the WAR file to <path>.war where path is the relative path at which you wish to deploy Unblu. Following the above example, we would simply rename the WAR file to unblu.war.

  2. Ensure that Tomcat is running and copy the WAR file to the directory $CATALINA_HOME/webapps/. Tomcat should automatically unzip the WAR file and deploy the application. After a delay Unblu should be accessible at http://<tomcat>/unblu.

  3. Once deployed, you can safely delete the original WAR file $CATALINA_HOME/webapps/unblu.war.

3.6.1.2.4. Root context deployment

In Tomcat the root context app is found in the directory $CATALINA_HOME/webapps/ROOT. By default this directory contains the Tomcat server management application. To install another app at this location you need to replace the contents of that directory with the app you want to deploy. If you still want to keep the Tomcat management apps you have to first rename the existing ROOT folder. Assuming you want to keep the management apps, the following is the easiest way to deploy Unblu to the root context:

  1. Stop Tomcat.

  2. Rename $CATALINA_HOME/webapps/ROOT to something else, like $CATALINA_HOME/webapps/mgmt.

  3. Copy the Unblu WAR file to $CATALINA_HOME/webapps/` as ROOT.war.

  4. Restart Tomcat.

  5. Once deployed you can safely delete the original WAR file $CATALINA_HOME/webapps/ROOT.war.

3.6.1.2.5. Database

You can either use the approach outlined in the database configuration section or use the datasource provided by the application server to connect Unblu to a relational database.

Listing 8. Configure Unblu to use a datasource provided by the application server
com.unblu.storage.database.datasourceFactory=USE_PROVIDED
com.unblu.storage.database.datasourceName=jdbc/Unblu (1)
1 JNDI name of the datasource
3.6.1.2.6. Docker for rendered co-browsing

If you want your Unblu system to support either universal or document co-browsing (both types of rendered co-browsing) then you will need to provide access from the Unblu server to Docker host (either on the same machine or another). Unblu will use the Docker host to spawn headless browsers for the rendered browsing sessions. See Rendered co-browsing for more details.

See com.unblu.headlessbrowser.server.core.DockerClientConfiguration for information on how to enable the connection to the Docker host.

3.6.1.2.7. Check the server logs

After starting Tomcat, switch to the folder you configured for logging. You will find 3 files:

  • unblu.datestamp.log

  • unblu-fatal.datestamp.log

  • unblu-session.datestamp.log

Check the file unblu.datestamp.log to see whether the server started normally or if there are any configuration or DB connectivity issues.

3.6.1.2.8. Accessing the Unblu server

If you deployed Unblu in root context, then:

If you deployed Unblu in a non-root context (let’s say as unblu.war), then:

For more on internal and public entry paths, see Entry paths.

3.6.1.2.9. Test whether Unblu is running correctly

If Unblu is running correctly, you will see the login screen for the agent view. Log in with the username unblu and the password secret.

3.6.1.2.10. JavaScript demo page and documentation

If you need to use the Unblu JavaScript demo page, you can activate it by setting com.unblu.server.resources.enableDemoResources to true. If you also want the Unblu docs available locally, set com.unblu.server.resources.enableDocResources to true.

3.7. Standalone deployment

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.

Standalone mode isn’t suitable for production use.

3.7.1. Requirements

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:

  • 1 recent CPU core running at 2.4GHz

  • 4 GB RAM

  • 10 GB hard drive space

You will also need the following:

  • Java 11

  • The Unblu installation package, consisting of the following elements:

    • The Unblu WAR file.

    • A valid Unblu license key.

    • Optionally, an Unblu properties file.

3.7.2. Deployment

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.

Listing 9. Start Unblu with default configuration
java -jar product.com.unblu-<version>-<guid>.war

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:

java -Dport=7070 \
     -jar product.com.unblu.war
3.7.2.1. Command line options

When running the executable JAR, The following command line options are available:

Listing 10. Options and description
-e,--export <arg>   Type of export. Possible options: 'ear' or 'wjar'
-h,--help	          Display this help message
-l,--list           Format of output: ( version: build: branch: )
-m,--migrationOnly  use to shutdown the product after database migration is complete
-o,--output <arg>   File to write the exported product to. If not given, output will default to STDOUT.
-p,--product <arg>  ID of the product to start, for example product.com.unblu.enterprise (default) (1)
-t,--test           Include test bundles into the product execution/export (not available in production versions).
-d,--diag           Include diagnostics bundles in the product execution/export (not available in production versions).
1 The --product switch is also available via System Properties and JNDI.

These options are placed after -jar product.com.unblu-<version>-<guid>.war:

java
     -jar product.com.unblu-<version>-<guid>.war \
     --help
3.7.2.2. Configuration

All configuration can be placed in a separate file such as unblu-config.properties.

Listing 11. unblu-config.properties
com.unblu.runtime.jetty.port=7777

# Create a superadmin on db setup
com.unblu.storage.createSuperAdmin=true
com.unblu.storage.superAdminUsername=
com.unblu.storage.superAdminPassword=superadmin

If you don’t specify the property com.unblu.storage.superAdminUsername, Unblu will generate a random superadmin username based on a WebUUID.

Listing 12. Start Unblu using unblu-config.properties
java -Dcom.unblu.propertyoverlay=unblu-config.properties \
    -Dport=7070 \
    -jar product.com.unblu-<version>-<guid>.war

If you need to use the Unblu JavaScript demo page, you can activate it by setting com.unblu.server.resources.enableDemoResources to true. If you also want the Unblu docs available locally, set com.unblu.server.resources.enableDocResources to true.

3.8. Database configuration

Unblu requires a relational database to persist configuration and operational data.

It is possible to run the Unblu server with an embedded in-memory database, but this is only to be used for development and testing.

Some personally identifiable information (PII) is stored in the Unblu database. This must be taken into consideration when deciding on the deployment details of the database.

3.8.1. Compatible databases

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

  • Oracle 12c, release 2 (12.2.0.1)

  • Microsoft SQL Server 2016

  • MySQL 5.7

  • PostgreSQL 10

  • MariaDB 10.2

3.8.2. Database setup

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

  • The database must be created by a database administrator with elevated privileges. The initial database creation must be performed manually and may differ slightly between database types.

  • The default charset must be UTF-­8.

  • You must create the database users used by Unblu; see below for further details.

  • The initial DB size requirement is less than 20MB (but see the following section for a proviso).

    The database will grow as the system is used and session audit trails are logged. These sessions only add a small amount of data (typically less than 20KB per session) to the database if the information stored is purely text.

3.8.2.1. Document sharing and database size

Document sharing can increase the size of your database considerably. Files can be uploaded via the file manager and stored in the database, a cloud storage system such as AWS S3, or in the file system. If you configure Unblu to store files in the database, the 20MB size requirement we made above will be insufficient.

If you expect a large number of documents, we recommend that you either configure a Remote Blob Store (RBS) in the database or use Amazon AWS S3 or a compatible service to store documents.

3.8.3. Server recommendations

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.

  • Recent Quad-core Architecture

  • 16 GB Ram

  • 200 GB disk (SSD)

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.

3.8.4. Database users

Unblu uses two distinct database users to operate:

  1. An admin user with database owner (DBO) privileges

    They must have the rights to execute the following statements: CREATE, ALTER, DROP, INSERT, UPDATE, DELETE, SELECT.

  2. A regular database user with the rights to execute INSERT, UPDATE, DELETE, SELECT on the tables created by the above user

Listing 13. Unblu database users
com.unblu.storage.database.user=unblu (1)
com.unblu.storage.database.password=<user-pwd>
com.unblu.storage.database.adminUser=unblu_admin (2)
com.unblu.storage.database.adminPassword=<admin-pwd>
1 The regular users with DML permissions.
2 The admin user with DDL permissions.

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:

  1. Stop the collaboration server.

  2. Remove com.unblu.storage.database.adminUser and com.unblu.storage.database.adminPassword[].

  3. Set com.unblu.storage.database.dbSetupEnabled to false.

  4. Restart the collaboration server.

Updates to the collaboration server usually require updates to the database. When they do, you have to enable the database admin user again in the configuration of the collaboration server. If you don’t, the database migration will be run using the regular database user, which will result in errors.

3.8.5. Configuring different database types

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.

In all of the cases below, the user and schema (and schema, depending on the type of database) must be created manually before you set up Unblu.
3.8.5.1. PostgreSQL
Listing 14. Create the unblu database and users
create database unblu;

-- activate database: \c unblu
create user unblu with password '<user-pwd>';
create user unblu_admin with password '<admin-pwd>';
grant usage, create on schema public to unblu_admin;

-- run as unblu_admin
alter default privileges for user unblu_admin in schema public grant select, update, insert, delete on tables to unblu;
alter default privileges for user unblu_admin in schema public grant usage, select on sequences to unblu;

The example configuration below connects to the database unblu and relies on the default schema public which does not need to be created.

Listing 15. Unblu PostgreSQL configuration
com.unblu.storage.database.platform=org.eclipse.persistence.platform.database.PostgreSQLPlatform
com.unblu.storage.database.driver=org.postgresql.Driver
com.unblu.storage.database.url=jdbc\:postgresql\://<server>\:5432/unblu (1)
com.unblu.storage.database.user=unblu
com.unblu.storage.database.password=<user-pwd> (2)
com.unblu.storage.database.adminUser=unblu_admin
com.unblu.storage.database.adminPassword=<admin-pwd> (3)
com.unblu.storage.database.schema=public
com.unblu.storage.database.liquibaseSchema=public
1 Replace <server> with your database hostname or IP address.
2 Replace <user-pwd> with the password of the unblu user.
3 Replace <admin-pwd> with the password of the unblu_admin user.
3.8.5.1.1. Transparent encrypted SSL connection

This additional configuration setting enables the connection to use SSL encryption (connecting a SSL-enabled database).

Listing 16. Unblu PostgreSQL SSL configuration
com.unblu.storage.database.jdbcProperties=\
  sslmode\=verify-ca,\
  sslrootcert\=path/to/root-ca.pem.crt,\ (1)
  sslcert\=path/to/client-cert.pem.crt,\ (1)
  sslkey\=path/to/client-key.pem.pk8 (1)
1 Replace the values with valid paths and filenames

Your certificates must be binary DER encoded, and the key file must be a binary DER encoded key (e.g. PKCS #8). You can convert PEM files to the PKCS #8 format as follows:

Listing 17. Commands to convert PEM files to PKCS #8
# Create key file
openssl pkcs8 -topk8 \
  -in KEY_FILE.pem -inform pem \
  -out KEY_FILE.pem.pk8 -outform der \ -nocrypt

# Create certificate file
openssl x509 \
  -in CERT_FILE.pem \
  -out CERT_FILE.pem.crt -outform DER

For further information on PostgreSQL encryption options, please consult the "Encryption Options" section of the PostgreSQL documentation.

3.8.5.2. Oracle
Please review the script below with an Oracle database administrator before using it.
Listing 18. Create the Unblu schema and permissions
ALTER SESSION SET "_ORACLE_SCRIPT" = TRUE;
CREATE USER UNBLU_DBO IDENTIFIED BY dbo_secret;
CREATE USER UNBLU IDENTIFIED BY secret;

GRANT CONNECT, CREATE TABLE TO UNBLU_DBO;
GRANT ALTER ANY TABLE TO UNBLU_DBO;
GRANT RESOURCE TO UNBLU_DBO;
GRANT UNLIMITED TABLESPACE TO UNBLU_DBO;

GRANT CONNECT TO UNBLU;

The script above sets up and configures two users, an admin user called UNBLU_DBO for Liquibase upgrades and a non-admin user called `UNBLU`for all other Unblu functionality.

During the Liquibase migration, the UNBLU user is silently granted the same rights as UNBLU_DBO on all tables. This is done to ensure that the Unblu collaboration server doesn’t fail to start up because UNBLU hasn’t yet been granted access to all of the tables they need.

Listing 19. Unblu Oracle configuration
com.unblu.storage.database.platform=org.eclipse.persistence.platform.database.OraclePlatform (1)
com.unblu.storage.database.driver=oracle.jdbc.driver.OracleDriver
com.unblu.storage.database.url=jdbc\:oracle\:thin\:@<server>\:1521\:xe (2)
com.unblu.storage.database.user=unblu
com.unblu.storage.database.password=<user-pwd> (3)
com.unblu.storage.database.schema=UNBLU_DBO
com.unblu.storage.database.liquibaseSchema=UNBLU_DBO
com.unblu.storage.database.adminUser=unblu_dbo
com.unblu.storage.database.adminPassword=<admin-pwd> (4)
1 Use Oracle12Platform for Oracle 12 and later.
2 Replace <server> with your database hostname or IP address. Change the SID or service name if required.
3 Replace <user-pwd> with the password of the unblu user.
4 Replace <admin-pwd> with the password of the unblu_admin user.

For a deeper insight into encrypting the database connection, please consult SSL With Oracle JDBC Thin Driver.

For a deeper insight into "Transparent Data Encryption" (TDE), please consult chapter 2 of the Oracle Database Advanced Security Guide.

3.8.5.3. MySQL
Consult the configuration section before creating the user and database.

To create the unblu database and users on MySQL 8.0.x, run the following commands:

Listing 20. Create the unblu database and users for MySQL 8.0.x
CREATE DATABASE unblu DEFAULT CHARACTER SET = utf8mb4 DEFAULT COLLATE utf8mb4_unicode_ci;

CREATE USER 'unblu'@'%' IDENTIFIED BY 'secret';
CREATE USER 'unblu_admin'@'%' IDENTIFIED BY 'admin_secret';

GRANT SELECT,UPDATE,INSERT,DELETE ON unblu.* TO 'unblu'@'%';
GRANT SELECT,UPDATE,INSERT,DELETE,CREATE,ALTER,DROP,INDEX,REFERENCES ON unblu.* TO 'unblu_admin'@'%';

For older versions of MySQL, run the following commands:

Listing 21. Create the unblu database and users for MySQL versions before 8.0.x
CREATE DATABASE unblu DEFAULT CHARACTER SET = utf8 DEFAULT COLLATE utf8_general_ci;

GRANT SELECT,UPDATE,INSERT,DELETE ON unblu.* TO 'unblu'@'%' IDENTIFIED BY 'secret';
GRANT SELECT,UPDATE,INSERT,DELETE,CREATE,ALTER,DROP,INDEX,REFERENCES ON unblu.* TO 'unblu_admin'@'%' IDENTIFIED BY 'admin_secret';

For all versions of MySQL, set the following Unblu configuration properties:

Listing 22. Unblu MySQL configuration
com.unblu.storage.database.platform=org.eclipse.persistence.platform.database.MySQLPlatform
com.unblu.storage.database.driver=com.mysql.jdbc.Driver
com.unblu.storage.database.url=jdbc\:mysql\://<server>\:3306/unblu (1)
com.unblu.storage.database.jdbcProperties=connectTimeout\=60000,socketTimeout\=60000,useUnicode\=yes,characterEncoding\=UTF-8,useLegacyDatetimeCode\=false,serverTimezone\=UTC,autoReconnectForPools\=true (2)
com.unblu.storage.database.user=unblu
com.unblu.storage.database.password=<user-pwd> (3)
com.unblu.storage.database.schema=unblu
com.unblu.storage.database.liquibaseSchema=unblu
com.unblu.storage.database.adminUser=unblu_admin
com.unblu.storage.database.adminPassword=<admin-pwd> (4)
1 Replace <server> with your database hostname or IP address.
2 For MySQL 8, replace useUnicode=yes with useUnicode=true.
3 Replace <user-pwd> with the password of the unblu user.
4 Replace <admin-pwd> with the password of the unblu_admin user.
In MySQL a schema is synonymous with a database. You can substitute the keyword SCHEMA instead of DATABASE in MySQL SQL syntax, for example using CREATE SCHEMA instead of CREATE DATABASE.
3.8.5.3.1. Configuration

We have observed four issues that can occur when using the default MySQL or MariaDB configuration applying to both Linux and Windows.

Before creating the schema you must override the MySQL defaults using the instructions below.

3.8.5.3.1.1. Character set
Listing 23. my.cnf (Unix) or my.ini (Windows)
[mysqld]

character-set-server=utf8mb4

This change is required because emojis require 4 bytes and the default MySQL can only handle 3 bytes. Without it, an SQL exception will occur when users enter emojis in a chat.

3.8.5.3.1.2. Max allowed packet size

Ensure that the value of max_allowed_packet is slightly more than twice as large as the Unblu setting com.unblu.filemanager.maximumUploadSize. This is necessary because of MySQL’s text-based wire protocol, which encodes binary values as text.

To support larger files being uploaded to Unblu, set max_allowed_packet to a higher value. The maximum file size is 1 Gigabyte (1G).

Listing 24. my.cnf (Unix) or my.ini (Windows)
[mysqld]

max_allowed_packet=<size> (Example: 16M)

You can check the current maximum file size by running the following query:

Listing 25. Access the current maximum file size
SHOW VARIABLES LIKE 'max_allowed_packet';
3.8.5.3.1.3. Network write timeout

To support uploading large files to Unblu, set net_write_timeout to a higher value. The default timeout is 60 seconds. In our test environment, this was not sufficient to handle files 15MB large.

Listing 26. my.cnf (Unix) or my.ini (Windows)
[mysqld]

net_write_timeout=<seconds> (Example: 180)
Listing 27. Access the current network write timeout
SHOW VARIABLES LIKE 'net_write_timeout';
3.8.5.3.1.4. SQL mode

Unblu requires that the MySQL parameters NO_ZERO_IN_DATE and NO_ZERO_DATE NOT be active. If they are active, an error will occur during setup and/or migration.

Listing 28. my.cnf (Unix) or my.ini (Windows)
[mysqld]

sql_mode=ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION

In the example above, remove the section NO_ZERO_IN_DATE,NO_ZERO_DATE. (If you are running MySQL 8, you will also have to remove NO_AUTO_CREATE_USER, since it is not supported by MySQL 8.) Then restart the MySQL server.

Run the query below to check if the problem exists in your system:

Listing 29. Query to run to determine MySQL Server SQL modes
SHOW VARIABLES LIKE 'sql_mode';
3.8.5.4. MariaDB

MariaDB is a fork of MySQL and still largely compatible with MySQL. The configuration in Unblu is slightly different though.

Please consult the configuration section of MySQL before creating the user and database.
Listing 30. Create the unblu database and users
CREATE DATABASE unblu DEFAULT CHARACTER SET = utf8 DEFAULT COLLATE utf8_general_ci;

GRANT SELECT,UPDATE,INSERT,DELETE ON unblu.* TO 'unblu'@'%' IDENTIFIED BY 'secret';
GRANT SELECT,UPDATE,INSERT,DELETE,CREATE,ALTER,DROP,INDEX,REFERENCES ON unblu.* TO 'unblu_admin'@'%' IDENTIFIED BY 'admin_secret';
Listing 31. Unblu MariaDB configuration
com.unblu.storage.database.platform=org.eclipse.persistence.platform.database.MySQLPlatform
com.unblu.storage.database.driver=org.mariadb.jdbc.Driver
com.unblu.storage.database.url=jdbc\:mysql\://<server>\:3306/unblu (1)
com.unblu.storage.database.jdbcProperties=connectTimeout\=60000,socketTimeout\=60000,useUnicode\=yes,characterEncoding\=UTF-8,useLegacyDatetimeCode\=true,serverTimezone\=UTC,useSSL\=false
com.unblu.storage.database.user=unblu
com.unblu.storage.database.password=<user-pwd> (2)
com.unblu.storage.database.schema=unblu
com.unblu.storage.database.liquibaseSchema=unblu
com.unblu.storage.database.adminUser=unblu_admin
com.unblu.storage.database.adminPassword=<admin-pwd> (3)
1 Replace <server> with your database hostname or IP address.
2 Replace <user-pwd> with the password of the unblu user.
3 Replace <admin-pwd> with the password of the unblu_admin user.
3.8.5.5. Microsoft SQL Server
Listing 32. Create the unblu database and users
CREATE DATABASE unblu;
USE unblu;

CREATE LOGIN unblu WITH PASSWORD = 'Unblu_Secret';
CREATE LOGIN unblu_admin WITH PASSWORD = 'Admin_Secret';

CREATE USER unblu_admin FOR LOGIN unblu_admin;
CREATE USER unblu FOR LOGIN unblu;

GRANT CREATE TABLE TO unblu_admin AS dbo;
GRANT ALTER, REFERENCES ON SCHEMA::dbo TO unblu_admin AS dbo;
GRANT SELECT, INSERT, UPDATE, DELETE ON SCHEMA::dbo TO unblu_admin;
GRANT SELECT, INSERT, UPDATE, DELETE ON SCHEMA::dbo TO unblu;
Listing 33. Unblu MSSQL configuration
com.unblu.storage.database.platform=org.eclipse.persistence.platform.database.SQLServerPlatform
com.unblu.storage.database.driver=com.microsoft.sqlserver.jdbc.SQLServerDriver
com.unblu.storage.database.url=jdbc\:sqlserver\://<server>\:1433;DatabaseName\=unblu (1)
com.unblu.storage.database.user=unblu
com.unblu.storage.database.password=<user-pwd> (2)
com.unblu.storage.database.schema=dbo
com.unblu.storage.database.liquibaseSchema=dbo
com.unblu.storage.database.adminUser=unblu_admin
com.unblu.storage.database.adminPassword=<admin-pwd> (3)
com.unblu.storage.database.jdbcProperties=sendStringParametersAsUnicode\=false (4)
1 Replace <server> with your database hostname or IP address.
2 Replace <user-pwd> with the password of the unblu user.
3 Replace <admin-pwd> with the password of the unblu_admin user.
4 Prevents implicit type conversions, can lead to performance problems if not set.
Analyze and optimize indexes at least every night to prevent fragmentation.
3.8.5.6. In-memory database

When no database configuration is present, Unblu will by default start using an embedded H2 database. This allows an administrator to log in and perform tests.

All data will be lost when you restart the server process. Do not use the in-memory database for any production use case.

3.8.6. Use a dedicated document storage

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

Listing 34. Unblu configuration to use min.io
com.unblu.server.storage.blob.persistentStoreType=S3
com.unblu.server.storage.blob.store.s3.bucketName=local-dev
com.unblu.server.storage.blob.store.s3.endpoint=http\://minio.example.com\:9001 (1)
com.unblu.server.storage.blob.store.s3.folder=blobs
com.unblu.management.aws.accessKey=<key> (2)
com.unblu.management.aws.secretKey=<secret> (3)
1 Remove this line to use AWS S3 instead of min.io.
2 Add your access key here.
3 Add your access secret here.

Alternatively, you can use Google Cloud Storage.

Listing 35. Unblu configuration to use min.io
com.unblu.server.storage.blob.persistentStoreType=GCS
com.unblu.server.storage.blob.store.gcs.bucketName=local-dev
com.unblu.server.storage.blob.store.gcs.folder=blobs
com.unblu.server.storage.blob.store.gcs.gcsServiceAccountKey[PROPERTIES, <key>] (1)
1 Add your service account key in JSON format here. If omitted, Application Default Credentials (ADC) will be used.

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.

Listing 36. Unblu database configuration reference
com.unblu.storage.database.platform=Auto
com.unblu.storage.database.driver=org.h2.Driver
com.unblu.storage.database.url=jdbc\:h2\:mem\:unblu
com.unblu.storage.database.jdbcProperties=
com.unblu.storage.database.user=unblu
com.unblu.storage.database.password=secret
com.unblu.storage.database.schema=unblu
com.unblu.storage.database.liquibaseSchema=
com.unblu.storage.database.adminJdbcProperties=
com.unblu.storage.database.adminUser=
com.unblu.storage.database.adminPassword=
com.unblu.storage.database.poolMax=20
com.unblu.storage.database.poolMinIdle=20
com.unblu.storage.database.adminUser=
com.unblu.storage.database.adminPassword=
3.8.7.1. Connection pool

The default JDBC connection pool is HikariCP.

It provides improvements in both speed and stability compared to the deprecated EclipseLink connection pool:

  • Connections are closed when not used for a longer period.

  • Connections are validated before using java.sql.Connection.isValid(int) provided by the JDBC Driver. (See Documentation)

  • New connections are proactively opened, not just on demand.

A Grafana dashboard called "Database (HikariCP)" visualizing all HikariCP metrics is automatically deployed with every Unblu cluster installation.

Listing 37. HikariCP default configuration
# Database Connection Pool
com.unblu.storage.database.datasourceFactory=HIKARI
com.unblu.storage.database.poolMax=20 (1)
com.unblu.storage.database.poolMinIdle=20 (2)
1 Maximum number of connections in the pool.
2 Minimum number of connections that should be idle, new connections are added to the pools when connections are busy up to the configured maximum number of connections.

The above configuration reflects the default settings beginning with Unblu 6. Please only add a connection pool configuration if you want to deviate from this default. For productions setups, the following values may be more appropriate:

com.unblu.storage.database.poolMax=60
com.unblu.storage.database.poolMinIdle=60
Instead of the approaches listed in this chapter, you can also use a data source provided by the application server. Please refer to this chapter for instructions.

3.8.8. Audit log database configuration

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:

Listing 38. Audit log database configuration properties
com.unblu.storage.database.audit.platform=
com.unblu.storage.database.audit.datasourceFactory=
com.unblu.storage.database.audit.datasourceName=
com.unblu.storage.database.audit.driver=
com.unblu.storage.database.audit.url=
com.unblu.storage.database.audit.jdbcProperties=
com.unblu.storage.database.audit.user=
com.unblu.storage.database.audit.password=
com.unblu.storage.database.audit.schema=
com.unblu.storage.database.audit.adminDatasourceFactory=
com.unblu.storage.database.audit.adminDatasourceName=
com.unblu.storage.database.audit.adminJdbcProperties=
com.unblu.storage.database.audit.adminUser=
com.unblu.storage.database.audit.adminPassword=
com.unblu.storage.database.audit.poolInitial=
com.unblu.storage.database.audit.poolMax=
com.unblu.storage.database.audit.poolMinIdle=

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.

3.9. Reverse proxy & WAF configuration hints

If your Unblu installation is behind a reverse proxy or web application firewall (WAF), you may have to make some changes to the latter’s configuration to ensure that Unblu is fully functional.

  • Requests from Unblu clients — the Unblu visitor UI and the Unblu mobile SDKs — must be forwarded to the Unblu server:

    • If you are running Unblu in a cross-origin installation, make sure that the domain or subdomain that Unblu is running on is accessible.

    • If your Unblu installation is a site-embedded deployment, create a URI mapping to the Unblu entry path for the PUBLIC entry path.

  • If a business (as opposed to a purely technical) exception occurs during an HTTP request, Unblu sends the error response code 400 or the error code specified in com.unblu.nio.error4xxcode and com.unblu.rest.error4xxcode. This code must be passed to clients so that they may handle it. You must therefore ensure that this error code is sent and not replaced by or redirected to an error page.

  • The request and response headers on the list of required HTTP headers must all be passed through unchanged.

  • The protocol used by clients to access Unblu can influence the server’s behavior. You should therefore add x-forwarded-proto and x-forwarded-host headers to the request headers forwarded to the Unblu Server.

  • Ensure that the x-unblu-device cookie is passed through and not stored in a cookie store (if your WAF has one).

  • If your installation uses CORS, allow the HTTP OPTIONS method. The method is required for CORS preflight requests.

    This is only necessary if your WAF is in front of Unblu (as opposed to the website being instrumented with Unblu).

  • If you want to use WebSockets, your WAF must support them.

3.10. Rendered co-browsing

3.10.1. Overview

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.

3.10.2. Rendering service

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.

3.10.3. WebRTC

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 is now built into most browsers, requiring no plugins to work.

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

  • Headless Browser (in the rendering service on the Unblu server)

  • Visitor Browser

  • Agent Browser

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.

3.10.4. Browser requirements

The browser requirements for WebRTC, and therefore for any feature that requires it (universal co-browsing, document co-browsing, video & voice calls). are the same as for Unblu as a whole (see browser requirements).

3.10.5. Network restrictions

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:

  • The headless browser in the rendering service, being part of the Unblu server, is behind a firewall both in on-premises installation and the Unblu Cloud.

  • The agent browser in an on-premises installation is often also behind the same firewall so in theory could contact the rendering service directly (though there may be other restrictions, depending on the internal details of the corporate network). In a cloud scenario, the agent browser accesses the Unblu Cloud over the internet and is therefore also outside the firewall.

  • The visitor browser is always outside the firewall and additionally, is often behind its own NAT.

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.

3.10.6. 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:

  • the target on the outside is itself not behind a firewall

  • the component on the inside initiates the connection

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.

This section discusses the TURN server used for Unblu’s rendered co-browsing functions (universal and document co-browsing) and for screen sharing. This should not be confused with the TURN server associated with the Vonage Video API service (formerly TokBox) that underlies Unblu’s voice and video call features. These two TURN servers are entirely separate: their roles cannot be shared across functions. The Vonage TURN server is bundled as part of the Vonage Video API service that Unblu employs. It cannot be used for any functions other than the voice and video service. Similarly, the Unblu TURN server (either in the cloud or on your infrastructure, if you choose that path) can only be used by Unblu’s rendering service.

3.10.7. TURN server deployment options

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

  • Unblu cloud service

  • Unblu on-premises with cloud TURN server

  • Unblu on-premises with on-premises TURN server

3.10.7.1. Unblu Cloud

The Unblu Cloud and Unblu cloud TURN server are separate products. The Unblu Cloud is the full Unblu system based in the cloud. If a feature requiring the TURN server (like universal co-browsing) is enabled, then the Unblu Cloud TURN server is included transparently in the system. There is no additional work required on the customer’s part to enable this.

3.10.7.2. Unblu cloud TURN server

The Unblu cloud TURN server is a cloud-based TURN server available by itself (without the full Unblu Cloud) for use by customers with Unblu on-premises. For Unblu on-premises customers, we recommend using the Unblu cloud TURN server for the vast majority of cases.

3.10.7.3. On-premises TURN server

If, for compliance or other reasons, using the Unblu cloud TURN server is not a feasible option, you can install your own TURN server on your own infrastructure. Advice on installation and configuration is provided below. However, general support for this option is not part of the standard Unblu license.

3.10.8. Firewall configuration

3.10.8.1. Unblu cloud TURN server

Outgoing connections from the rendering service in the Unblu server and the agent browsers to the Unblu cloud TURN server will require:

  • Open outgoing source ports in firewall for TCP and UDP.

  • Open outgoing destination ports 443 for TCP and 3478 for TCP and UDP.

Cloud TURN server
Figure 14. Unblu cloud TURN server

The above diagram depicts the WebRTC connections between the parties in a cloud turn server scenario. Notice that only outgoing connections through the firewall are required.

3.10.8.2. On-premises TURN server

Incoming connections from the visitor browser to the on-premises TURN server will require:

  • Open incoming destination ports 443 for TCP and 3478 for TCP and UDP.

On-premises TURN server
Figure 15. On-premises TURN server

In most cases organizations find it easier to accommodate the first option (opening the outgoing ports) than the second option (opening the incoming ports).

3.10.9. Data security

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.

Using document co-browsing with files of a type other than PDF relies on third-party services and involves uploading the files to the servers of those third parties. Please review the following configuration properties:

3.10.10. Comparison

Considering the two deployment issues above it should be clear that

  • In terms of firewall policy, the Unblu cloud TURN server is the simplest solution

  • In terms of data security in transit, there is no significant security advantage to the on-premises solution compared to the Unblu cloud solution

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

3.10.10.1. Unblu cloud TURN server configuration

To configure your on-premises Unblu server to connect to the Unblu cloud TURN server you need the following information:

  • The DNS address of the Unblu cloud TURN server (<TURN_ADDR>): turn.unblu.cloud

  • The authentication key (<AUTH_KEY>): available from the Unblu delivery team

The authentication key is given to you as part of the onboarding when you register for an Unblu cloud TURN Server account. Please consult with the Unblu delivery team for more details.

With this information you can set the following configurations properties on your Unblu server:

Listing 39. Unblu server configuration for the Unblu cloud TURN server
com.unblu.webrtc.iceServer=turn.unblu.cloud
com.unblu.webrtc.credentialSecretKey=<AUTH_KEY>

Additionally, for testing you can set the following:

Listing 40. Set Use Relay Only to true for testing
com.unblu.webrtc.useRelayOnly=true

But for production this should be changed to

Listing 41. Set Use Relay Only to false for production
com.unblu.webrtc.useRelayOnly=false
3.10.10.2. On-premises TURN server configuration

If you do choose to install your own TURN server on-premises then a common choice is the open-source Coturn Project To create a secure key, we recommend programmatically creating a pseudo-random string using code like the following:

Listing 42. Create an authentication key
#!/usr/bin/env python3

from base64 import b64encode
from random import SystemRandom
from string import ascii_letters

def generate_turn_auth_secret(length = 36):
    """Generate a Base64 encoded random string to be used as the turn server auth secret"""
    character_set = ascii_letters + '#$%&()*+,-./:;<=>[email protected][]^_`{|}~'
    random_string = ''.join(SystemRandom().choice(character_set) for _ in range(length))
    # print('secret is: ' + random_string)
    return b64encode(bytes(random_string, 'utf-8')).decode("utf-8")

print("Generated, random auth secret: " + generate_turn_auth_secret())

The resulting key should be used in place of <AUTH_KEY> in the configuration files below.

3.10.10.2.1. Note the TURN server address

Since you are installing the TURN server on your own infrastructure you control the address of the server. This value should be used in place of <TURN_ADDR> in the configuration files below.

3.10.10.2.2. Use the standard ports

The ports configured for TCP and UDP transport should be the standard ones, the same as with the Unblu cloud TURN server option:

  • <UDP_PORT>: 3478

  • <TCP_PORT>: 443

3.10.10.2.3. Determine listening IP address

The IP address on your internal network at which the TURN server should listen for connections is represented by the placeholder

<LISTENING_IP>

in the configuration file below.

3.10.10.2.4. Determine external IP address

The external IP addresses (i.e., as seen from the internet) at which the TURN server is listening for connections is represented by the placeholder

<EXTERNAL_IP>

in the configuration file below.

3.10.10.2.5. Unblu server configuration

The configuration on the Unblu server side will be very similar to that used with the Unblu cloud TURN server above, except that the <AUTH_KEY> will be the one you created and the <TURN_ADDR> will be the one you specified when you did the installation.

3.10.10.2.6. Coturn server configuration

Configuration of the coturn TURN server is done in the file turnserver.conf. You can adapt the following by substituting the appropriate values for the placeholders:

Listing 43. turnserver.conf
listening-device=eth0
listening-port=<UDP_PORT>
listening-ip=<LISTENING_IP>
external-ip=<EXTERNAL_IP>
min-port=20000
max-port=20200
verbose
use-auth-secret
static-auth-secret=<AUTH_KEY>
realm=unblu.com
cert=/etc/ssl/localcerts/tls.pem
pkey=/etc/ssl/private/tls.key
cipher-list=ECDH+AESGCM:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:ECDH+3DES:DH+3DES:RSA+AES:RSA+3DES:!ADH:!AECDH:!MD5:!RC4
dh2066=
log-file=/var/log/turn.log
simple-log=

Here is an example configuration, with placeholders filled in:

Listing 44. turnserver.conf
listening-device=eth0
listening-port=3478
listening-ip=172.16.2.54
external-ip=193.159.170.115/172.16.2.54
min-port=20000
max-port=20200
verbose=
use-auth-secret=
static-auth-secret=W3dEO1VoSURAJVtCeGdPVHoqYWtOJiMoaUhCYEFRemFsSW0q
realm=unblu.com
cert=/etc/ssl/localcerts/tls.pem
pkey=/etc/ssl/private/tls.key
cipher-list=ECDH+AESGCM:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:ECDH+3DES:DH+3DES:RSA+AES:RSA+3DES:!ADH:!AECDH:!MD5:!RC4
dh2066=
log-file=/var/log/turn.log
simple-log=
3.10.10.2.7. Check connection to TURN server

To check whether the TURN server is accessible from the internet, perform the following:

Listing 45. Checking the connection to an on-premises TURN server
openssl s_client -connect turn_server.com:443

4. Front-end and back-end integration

As we saw in the sections Front-end interfaces and integrations and Back-end integrations Unblu offers a number of connection points for integrating different kinds of interfaces and additional functionality. In the following section we will look at each of these integration points in more detail.

4.1. Overview

In terms of our earlier Basic System Components diagram, we will be looking at the highlighted components below:

Integration System Components
Figure 16. Integration system components

4.2. Floating Visitor UI web integration

To enable the floating visitor UI on your website, the Unblu installation must be integrated with your web infrastructure. This involves addressing three issues:

  • How is the client code for the floating visitor UI (often called the Unblu snippet) included in your website page? The options are dynamic injection or static inclusion.

  • Where is the Unblu Server positioned inside your infrastructure? The options are site-embedded or cross-origin.

  • Do you need support for protected resource upload to the agent?

These options only apply in an on-premises deployment. In an Unblu Cloud deployment, dynamic injection, site-embedded integration and protected resource upload are not supported. Consequently, all Unblu Cloud deployments use static inclusion and cross-origin integration and do not have protected resource upload.

4.2.1. Including the Unblu snippet

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.

4.2.1.1. Static inclusion

In this method you alter your website markup to include the Unblu snippet. The snippet in turn loads the Unblu client code. Every page on which you want to display the floating visitor UI launcher button must include the snippet. This method of inclusion is relatively simple but you do need access and permission to change the actual code of the website in question.

Listing 46. Unblu snippet example
<!DOCTYPE html>
<html>
<head>
    <script type="text/javascript" defer="defer"
        src="https://unblu.cloud/unblu/visitor.js?x-unblu-apikey=YOUR_API_KEY"></script> (1)
</head>
<body>
    <!-- Your HTML body -->
</body>
</html>
1 Replace YOUR_API_KEY with your API key.

The snippet with the correct key can also be copied from the API keys section in the Account Configuration.

For certain use cases you might not need the snippet on all pages. For example when you want Unblu’s Universal or Document Co-Browsing only on a specific section of your website, it is sufficient to instrument only those pages.
4.2.1.2. Dynamic injection

In this method you configure the Unblu snippet in a single central place and have it injected into the appropriate pages. There are two ways of doing this:

  • Dynamic injection with the SecureFlow Manager

  • Dynamic injection with a tag management system

4.2.1.2.1. Dynamic injection with the SecureFlow Manager

With this strategy you use a reverse proxy in front of your website server that includes the Unblu SecureFlow Manager. This method does not involve any changes to the website code itself, but it does involve installation of software on your corporate infrastructure. If you already have a suitable cache/reverse proxy installed you may be able to simply add the SecureFlow Manager to it.

The SecureFlow Manager will manage the injection of the required JavaScript into the pages to enable the floating visitor UI. It also provides the protected resource upload functionality (see below).

For details on installation see SecureFlow Manager.

4.2.1.2.2. Dynamic injection with tag management

An alternative method of including the Unblu snippet is to leverage an existing tag management system to inject the snippet into the desired pages of your website. Tag management systems are used primarily to centralize the management of injecting marketing-related code into pages across large websites, but in many cases they can be used to inject any JavaScript snippet, including the Unblu snippet.

4.2.1.3. Integration with single-page applications (SPAs)

Single-page applications (SPAs) pose special challenges to integrating Unblu. If your customer navigates to a part of your SPA that uses a different API key, for example, or changes the language of the application, Unblu will not be aware of the fact without a page reload.

You will have to take some additional measures to ensure that the Unblu UI works as your customers expect it to. If you are adding the floating visitor UI to an SPA, please review our article on integrating Unblu in an SPA.

4.2.2. Server positioning

4.2.2.1. Site-embedded

The following diagram depicts the site-embedded scenario:

Site Embedded Install
Figure 17. Site-embedded install

In this setup both the Unblu server and your company website server sit behind a proxy. Note that in this case the diagram also depicts the SecureFlow Manager as being installed on the proxy server. In most situations where a site-embedded integration is used, the SecureFow Manager will also be used (and thus dynamic injection and protected resource upload will both be enabled). However, strictly speaking the two factors are independent: SecureFlow Manager can be used without site-embedded integration and vice versa.

4.2.2.2. Cross-origin

The following diagram depicts the cross-origin scenario:

Cross Origin Install
Figure 18. Cross-origin install

In this setup the Unblu server and your company website server are exposed separately to the internet. Typically this arrangement is used with static inclusion, though as above, the factors are independent: cross-origin installation could theoretically be used in conjunction with dynamic injection provided by a SecureFlow Manager.

4.2.3. Protected resource upload

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.

4.2.4. Removing the Floating Visitor UI from a page

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.

4.3. JavaScript APIs

The JavaScript APIs are an optional add-on to the integrated visitor UIs.

  • Visitor JS API

  • Embedded JS API

They allow JavaScript to access and control certain functions related to the visitor UIs.

4.3.1. Concepts

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.

4.3.2. Reference and examples

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:

<unblu-server>/unblu/static/js-api/v2/doc/index.html

For the Embedded JavaScript API:

<unblu-server>/unblu/static/js-api/embedded-v1/doc/index.html

4.4. SecureFlow Manager

4.4.1. Overview

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:

Dynamic injection of the Unblu snippet

The SFM can dynamically inject the Unblu JavaScript snippet into specific pages of your website. This eliminates the need to modify the source code of the instrumented website itself.

Forwarding of protected resources

The SFM can intercept protected resources such as images and CSS as they transit the proxy from the website back-end to the visitor’s browser. It then forwards these resources to your agents' browsers during embedded co-browsing sessions.

4.4.2. Dynamic injection

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:

  • Static inclusion, where the snippet is added to the page’s source code.

  • Dynamic injection, where the back-end code is left unchanged and the snippet is injected by some other mechanism.

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.

4.4.3. Protected resource forwarding

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:

  • Your website’s back-end responds to the initial request by sending the HTML document representing that page.

  • The visitor’s browser parses the HTML and constructs a Document Object Model (DOM) within the browser.

  • The DOM does not directly contain all the elements needed to render the page. Resources such as CSS files and images are referenced within the DOM via URL and require an additional request to actually retrieve them.

  • Once the browser has retrieved all the referenced resources, the browser can finish rendering the page and display the final result.

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?

  • During an embedded co-browsing session, the Unblu code on the webpage in the visitor’s browser deconstructs the DOM and sends its state information to the Unblu server. Unblu reconstructs the page and serves it to the agent’s browser, giving the agent a view of what the visitor sees.

  • Because the agent’s browser receives the DOM information through this mechanism and not via a direct request for the webpage, it doesn’t need its own authorization to get the basic structure of the webpage.

  • Things are different for resources referenced in the DOM. The agent’s browser has to retrieve these resources directly. However, since the agent’s browser doesn’t have the same authorization as the visitor, it won’t be able to retrieve those resources if doings so requires authorization.

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.

SecureFlow Manager

4.4.4. Supported products

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

Customers interested in using the SecureFlow Manager with a product not listed above should contact Unblu. The SecureFlow Manager is defined by a publicly available specification that can be used as a guide to building a custom implementation. For more details, see the SecureFlow Manager specification.

4.4.5. Common configuration

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.

4.4.6. Installation

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

4.5. Mobile SDK

The Mobile SDKs for Android and iOS can be used to integrate Unblu into mobile applications for visitors or agents. When the SDK is integrated into an app, the app can use many of the same features as are available to visitors and agents through the web interfaces (chat, co-browsing, notifications, etc.).

4.5.1. Mobile SDK requirements

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

4.5.2. Features

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

  • Dynamically load and unload the API

  • Check if a connection to the Unblu server could be established

  • Start a chat conversation

  • Start a mobile co-browsing conversation

  • Start an audio/video call with up to six participants

  • Add or remove private views which shouldn’t be displayed to the agent/visitor (e.g. password fields)

  • Add or remove private areas which shouldn’t be displayed to the agent/visitor

  • Add or update custom cookies sent to the Unblu server with each request

  • In-app events for API state, session state, notifications (e.g., agent/visitor joint messages, chat messages), errors (More details can be found in the code documentation which is provided together with the SDK for each platform.)

  • Push notifications for unread messages and incoming calls

  • Whitelist of accessible URLs inside the WebView of the SDK

  • Whitelist of external links that can be opened from the chat

  • Certificate Pinning

  • Check if an agent is available

  • Join a conversation via a PIN from the agent

The following features are available in co-browsing sessions:

  • Co-browsing all of your app’s content

  • Interactions of the user with the device screen can be seen remotely

  • Orientation changes are displayed on the agent side

  • Lock the screen displayed in the agent desk if the visitor puts the app into the background

  • Areas of the app can be marked remotely

  • Chat between visitor and agent inclusive UI

  • Start an audio/video call

4.5.3. Architecture overview

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.

Mobile SDK architecture

4.5.4. Configuration on the Unblu server

The following configuration properties are important for the mobile SDKs:

messenger.mobileVisitorSdkEnabled

Specifies whether the mobile SDK’s visitor API is enabled. This must be enabled so that the SDK’s visitor API on a mobile device can initialize. If the property is set to false, the visitor API will not be usable.

messenger.mobileAgentSdkEnabled

Specifies whether the mobile SDK’s agent API is enabled. This must be enabled so that the SDK’s agent API on a mobile device can initialize If the property is set to false, the agent API will not be usable.

messenger.mobileCoBrowsingEnabled

Specifies whether mobile co-browsing with the SDKs is enabled. If it is not enabled, the SDKs can still be used for chat or call conversations.

conversation.feature.mobileCoBrowsingEnabled

The same as messenger.mobileCoBrowsingEnabled but on the conversation level. This property may be set individually for each conversation and conversation template.

cobrowsing.startWithMobileCobrowsingOptionEnabled

Enables starting a mobile co-browsing conversation. Such a conversation immediately launches mobile co-browsing when the conversation is accepted from the queue.

visitor.ui.showRequestMobileCobrowsingEngagementOption

If this property is true, the UI will give you the option to start a mobile co-browsing conversation when the Unblu UI is displayed in the app.

4.5.5. Integration

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:

4.5.6. Mobile push notifications

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:

mobile.push_notification.enablePushNotification

Enables push notifications in general. Currently there are email and mobile push notifications.

mobile.push_notification.enableFirebasePushNotification

Enables push notifications via Firebase Cloud Messaging.

mobile.push_notification.firebaseDatabaseName

The name of the firebase database where the app is configured for Firebase Cloud Messaging. Set the property to the Project ID of your Firebase project, as displayed on the General tab of your Firebase project’s settings.

mobile.push_notification.firebaseServiceAccountKey

The account key to allow the Unblu server to access Firebase Cloud Messaging. You can generate an account key by clicking on the Generate new private key button on the Service accounts tab in the settings of your Firebase project,

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.

4.5.7. UI concept

The Unblu UI is a view that behaves like any other view 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 when the view’s attached to the view hierarchy again. It preserves its state while it isn’t visible or attached to the view hierarchy.

4.5.8. Android mobile SDK integration

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.

4.5.8.1. Requirements

The Android mobile SDK requires Android version 7 or newer.

Before you start, make sure that you are using the D8 dex compiler and JDK 11 or newer to build your app.

The information here refers to version 4 of the Unblu Android mobile SDK. Please refer to the Unblu 6 documentation for information on version 3 of the SDK, and Unblu 5 documentation for information on version 2 of the SDK.
4.5.8.2. Android archive integration

For Android, Unblu provides android archive (AAR) files with additional sources JARs for public classes and Javadoc JARs for them. Those files are delivered within a .tar.gz file for the SDK. The TAR files have the internal structure of a maven repository.

Unblu is divided into modules, and depending on your implementation, you may use all, or only some of them.

To integrate the SDK, the TAR files have to be extracted into the project folder of the app. To add it to the project, the following lines need to be added to the app/build.gradle file:

repositories {
    ...
    mavenCentral() (1)
    maven {
        url "../unblu-mobile-sdk"
    }
}
...
dependencies {
    ...
    implementation 'com.unblu.mobile-sdk-android:coresdk:4.0.0'
    implementation 'com.unblu.mobile-sdk-android:firebasenotificationmodule:4.0.0'
    implementation 'com.unblu.mobile-sdk-android:callmodule:4.0.0'
    implementation 'com.unblu.mobile-sdk-android:cobrowsingmodule:4.0.0'
}
1 This line is required if you use the Unblu video & voice call feature in your app. The Unblu call module has a dependency on the OpenTok Android SDK provided by the Vonage Video API.

This way all dependencies of the SDK are automatically retrieved.

The *-public-sources.jar files only contain the sources for the public API part and cannot be used as a library as they don’t contain the internal classes.

The Unblu SDK’s firebasenotificationmodule uses Firebase Cloud Messaging for push notifications. For Firebase to work correctly, the google-services.json file from the Firebase project must be added to the app. Additionally, you need to add the following line at the end of your app’s gradle file.

apply plugin: 'com.google.gms.google-services'

Please follow the instructions here for detailed information.

It is not necessary to set up Firebase in your code. This is done automatically by the SDK when push notifications are enabled.
4.5.8.3. Permissions

Various features require that you include certain permissions in your application’s manifest.

android.permission.INTERNET

Required to use the internet connection

android.permission.SYSTEM_ALERT_WINDOW

Required to overlay the Unblu UI on top of the application. This permission is automatically granted by the app store.

android.permission.WRITE_EXTERNAL_STORAGE

Required to save files which should be downloaded

android.permission.RECORD_AUDIO

Required by OpenTok for audio and video sessions (also for plain audio sessions)

android.permission.CAMERA

Required by OpenTok for audio and video sessions

android.permission.MODIFY_AUDIO_SETTINGS

Required by OpenTok for audio and video sessions (also for plain audio sessions)

android.permission.BLUETOOTH

Required by OpenTok if bluetooth device is used inside calls

android.permission.BROADCAST_STICKY

Required by OpenTok (no details available)

android.permission.READ_PHONE_STATE

Required by OpenTok (no details available)

4.5.8.4. Code setup and initialization
4.5.8.4.1. UnbluApplication

To ensure the SDK works properly, you must set the attribute android:name in the application tag of the AndroidManifest.xml file to com.unblu.sdk.core.application.UnbluApplication (If you implemented your own custom application class that inherits from one of the above classes, set the attribute to that.) See the code snippet below for an example.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.unblu.testapp">

    <application
        android:name="com.unblu.sdk.core.application.UnbluApplication"> (1)
        </application>
</manifest>
1 There may also be some other attributes

If this isn’t possible in your application, you can use the UnbluApplicationHelper. They define a couple of static functions like onCreate which need to be called in the corresponding functions of the used Application class. The names of the functions in the helper class are the same as those in the Application class. The documentation also states whether the function must be called before or after the super call.

4.5.8.4.2. Unblu client instance

The most important instances of the SDK are UnbluVisitorClient and UnbluAgentClient. Choose the one that suits your implementation.

Instances of both clients can be obtained from the Unblu class:

After the success callback is triggered, the UnbluVisitorClient or UnbluAgentClient instance is provided, and you can obtain the Unblu View, add it to a view tree hierarchy, and display it, start new conversations, check agent availability etc.

You can only have one initialized client instance running throughout your application lifecycle. An instance can either be created directly or only on demand. For example when mobile co-browsing is needed.

Note that if the instance is created on demand, the SDK will take some time until it’s ready and a session can be started. You should also use the method that requires an Android.app.Activity to be passed. Check out the Android mobile SDK reference for an example.

Additionally if you use push notifications, you must initialize an instance at least once. Without it, the Unblu server can’t establish a relationship between a user and their device. We therefore recommend that, in general, you create a client instance as soon as possible, i.e. directly after login.

4.5.8.4.3. Unblu client configuration

When you create an instance of either UnbluVisitorClient/UnbluAgentClient, you must provide a configuration for it. Each instance creator accepts an instance of UnbluClientConfiguration. This class will be instantiated with the base URL of the Unblu server and the API key of the Unblu account.

For all possible configurations and their effects, take a look at the documentation of UnbluClientConfiguration.Builder.

Only a limited number of settings can be configured via the Unblu SDKs. All configurations which are independent of the client (the app) can be done via the Unblu agent desk.

To properly separate the configuration for the mobile visitor and agent SDK and also from configurations done for the webpage where Unblu is integrated, we recommend to use different API Keys for each environment. The Unblu client instance only stores a copy of the configuration. As a result, the client configuration can’t be changed via the reference. If you want to change the client’s configuration, you will have to destroy the current client instance and create a new one.

The configuration can only be used when creating new instances of UnbluVisitorClient and UnbluAgentClient.

4.5.8.4.4. Events

The Unblu Android Mobile SDK relies on the RxJava library to handle events and manage data. Before you initialize the API you should subscribe to events in order to be sure not to miss any.

This can be done by calling the Unblu class, which will provide a number of observables you can subscribe to.

Additionally, you can obtain events related to the UnbluClient instance and subscribe to them by calling the instance itself.

Detailed information on the observable events can be found in the documentation of the Unblu/UnbluClient and UnbluVisitorClient classes.

4.5.8.4.5. Deinitialization

UnbluVisitorClient and UnbluAgentClient instances can be deinitialized.

If the SDK is no longer needed and everything should get cleaned up, there is the deinitClient function.

The callback parameters can be used to get information about success and errors.

Additionally the Unblu.onError observable can be used as described in the events section above. We strongly recommend that you subscribe to this observable, as errors can occur independently of any explicit calls to the API.

4.5.8.5. Unblu View

All Unblu UI content is rendered into a View. This view is available via the UnbluClient.getMainView getter. The View it returns provides an Unblu UI that shows all existing conversations or the conversation currently open. These conversations can be used to chat and make calls.

For the view to be visible on the device, you need to add it to a view hierarchy somewhere in your app. It’s up to you to decide on the view’s size and position within the context of your application.

screenshot mobile sdk android

If there is an issue with the Unblu SDK, please be aware that the UI is rendered inside a WebView, so you can attach the local Chrome to check for error logs. It’s a limitation of Android WebViews that you can’t see the full content of logs in the normal debugger console.

Note that several functions, like opening a conversation and starting an audio/video call, require that the UI opens at least once so that the corresponding part gets loaded by JavaScript. You can find more details in the documentation.

4.5.8.6. Conversations

The UnbluConversation interface provides the neccessary APIs to interact with conversations in Unblu. This includes actions such as opening and closing the conversation, starting audio or video calls, and launching mobile co-browsing sessions.

The functions that start calls and mobile co-browsing sessions require the presence of the CallModule or MobileCoBrowsingModule, respectively. If the required module isn’t registered in the Unblu client instance, an error will be thrown at runtime.

The current open conversation is always available via the UnbluClient.getOpenConversationValue getter. If no conversation is currently open, the returned value is null.

If you wish to be notified when a conversation is opened or closed, subscribe to the UnbluClient.getOpenConversation observable in your app.

The main functions of note on the UnbluClient relating to conversations are:

Additionally, the UnbluVisitorClient provides:

You can intercept conversation-related activity by calling UnbluVisitorClient.setConversationInterceptor with an object that conforms to the ConversationInterceptor interface.

4.5.8.7. Private views

The SDKs provide a simple way to add specific views which shouldn’t be shown on the remote side. To do this, the MobileCoBrowsingModule provides the function addPrivateView which takes an ID as its argument. Each view has its own ID.

After a view ID is added, it is automatically overlaid by an image before the screen is transmitted to the remote side. You can make a view visible to the remote side again by calling the removePrivateView function.

4.5.8.8. Private areas

The SDKs provide a way to specify areas which shouldn’t appear on the remote side. To this end, the MobileCoBrowsingModule provides the function setPrivateArea which takes a custom ID, values for the x and y axes, and values for the width and height of the private area. Each private area has its own ID.

After an area is added, it is automatically overlaid by an image before the screen is transmitted to the remote side. To make an area visible to the remote side again, call the function removePrivateArea.

4.5.8.9. Custom cookies

It is possible to define custom cookies that should be sent to the Unblu server with each request. This can either be done (initially) by using the function UnbluClientConfiguration.Builder#setCustomCookies, or by setting the cookies dynamically with the setCustomCookies function. Before the API is initialized, always the last cookies configured are used. If the API is already initialized, cookies with the same name are overridden and new cookies are added. The previously-defined cookies will stay until the API is de-initialized. If the API is then initialized again, only the last defined cookies are used again.

4.5.8.10. Named areas

Similar to a web page, the named area feature is also available for the mobile SDKs.

You can set a named area by calling UnbluClientConfiguration.Builder#setNamedArea before you initialize the API. Alternatively, it can be set by calling UnbluVisitorClient#setNamedArea on the UnbluVisitorClient instance.

If a named area is set before initializing the API, its specific configuration is loaded upon initialization. If it is set later, it only changes the requests for new conversations in the agent desk queue in the way that the agent can filter by the named area. The named area has no effect for existing conversations.

As a result, it’s important to know if there will be specific configuration on the named area scope. If there is, the named area must be configured/set in the SDK before initializing the API, but then it should be always considered to change the configuration on API Key level. If a named area is only used for the queue, it can be set at any time before starting a new conversation.

4.5.8.11. Uploading files and camera pictures or videos

When the user of the app tries to upload a file in the Unblu chat UI, the file chooser appears. By default, the user may select either an existing file or create a new picture/video with their phone’s camera app.

You can restrict the file types that users may upload with the following configuration properties:

Unfortunately, the specific behavior of com.unblu.filemanager.fileTypeInputTagHint varies between device vendors. Android may filter out file types that you don’t want to exclude. You should take this into account when deciding whether to enable the configuration property for Android devices.

In Android, the camera app can’t write a picture directly to the app’s internal storage, so it stores a temporary file in the external storage of the Android system. This can be a security issue, so the SDK allows you to disable the upload of new pictures/videos from the camera app. Use UnbluClientConfiguration.Builder#setCameraUploadsEnabled(..) to change the configuration.

You can also disable only photo or video uploads individually using link:{android-sdk}com/unblu/sdk/core/configuration/UnbluClientConfiguration.Builder.html#setPhotoUploadsEnabled-boolean-[`UnbluClientConfiguration.Builder#setPhotoUploadsEnabled(..)`] or link:{android-sdk}com/unblu/sdk/core/configuration/UnbluClientConfiguration.Builder.html#setVideoUploadsEnabled-boolean-[`UnbluClientConfiguration.Builder#setVideoUploadsEnabled(..)`], respectively.
4.5.8.12. Push notifications

If the SDK is configured to use push notifications, there are currently three possible types of notifications visible for the user: Whenever there is a new message, if there is an incoming call, or if there was a missed call. For all types of notification, the system default sounds for notifications and calls should be used to ensure the best user experience. The SDK accomplishes this by using three different notification channels which use the default system sounds.

However, this is only possible — indeed, required — for Android 8.0 Oreo or newer. Before Android 8.0 Oreo, you had to define custom sounds. The name of the sound files must be configured on the Unblu server via the configuration properties com.unblu.mobile.push_notification.androidNewMessageSound and com.unblu.mobile.push_notification.androidIncomingCallSound. We recommend only changing the incoming call sound. The value has to be the name of the file without the file type ending. Within the app, the file must be located at res/raw/<file>.

By default, the icon of the push notifications matches the app icon. Only the parts of the image with an alpha value are displayed. This can lead to a completely gray icon if the app icon has no transparent area. To change the icon to a different image, you can specify a meta-data area inside the app manifest, as in this example:

<meta-data
    android:name="com.google.firebase.messaging.default_notification_icon"
    android:resource="@drawable/ic_notification" />

See the Firebase configuration documentation for further details.

If you wish to use Firebase Push Notifications, you must add the firebasenotificationmodule dependency to your project and get your UnbluNotificationApi from the UnbluFirebaseNotificationService class. See getNotificationApi for further details.

4.5.8.13. Logging

The Unblu SDK uses an internal Logger, which can be configured. Per default the logger does not print any additional and potentially security related information. To change this behavior for debugging purposes, set the flag Unblu#enableDebugOutput to true. Even though the default value of the log level is VERBOSE, in release builds, the verbose and debug logs are removed via proguard rules. You can change the log level by means of the function Unblu#setLogLevel.

It is also possible to enable the flag Unblu#enableCapturingPerformanceLogging to get logs about mobile co-browsing performance. For this the log level has to be DEBUG or less and also the enableDebugOutput flag has to be enabled.

If, for security reasons, you want to strip out the complete log statements from the compiled app, please review the section on log stripping first.

4.5.8.14. Security-relevant configuration

There are several security-related configuration possibilities when integrating the Android Mobile SDK. The following points should be taken into consideration to ensure the SDK is configured in the most secure way without limiting the features available.

4.5.8.14.1. Whitelist URLs

By default, only the configured Unblu base URL and its subroutes can be accessed by the SDK’s internal WebView. Sometimes you may need to grant the WebView access to other URLs. Examples of situations where this need may arise include:

  • Redirecting to a different domain

  • Accessing external resources such as fonts

If your application needs access to other URLs, you can provide a list of regular expressions matching those URLs via UnbluClientConfiguration.Builder#setInternalUrlPatternWhitelist. Otherwise there is no need to configure the internal pattern whitelist as it is secure by default.

The URLs in the internal pattern whitelist are those used internally by your Unblu-enabled application. If you want to specify which URL patterns may be accessed by having your application open another application, modify the external link pattern whitelist described in the following section.

If you want to use Google fonts in your mobile app, take into account that https://fonts.googleapis.com redirects to https://fonts.gstatics.com. You will have to include a pattern for the latter domain in the whitelist.
4.5.8.14.1.1. External link handler

The Unblu chat UI recognizes different types of links:

  • URLs such as https://<domain>

  • mailto:<email_address>

  • tel:<phone_number>

These links can be clicked by agents or visitors. Doing so opens another application, such as a browser or an email client.

To create an UnbluClientConfiguration, you need to provide an implementation of UnbluExternalLinkHandler. There is a default implementation availabe, which allows two constructors UnbluPatternMatchingExternalLinkHandler, that allows only a small set of link patterns, and UnbluPatternMatchingExternalLinkHandler(List<java.util.regex.Pattern> patternList), which allows you to pass in a customized list of patterns. For example, you may wish to restrict links to those within your organization’s domains.

4.5.8.14.2. Certificate pinning

From Android 7.0 Nougat (API 24) on, it is possible to use certificate pinning within your app’s network security configuration file. This may be done for the whole app including all WebViews, so there is no need for the SDK part to provide any configuration for it. Further information on certificate pinning in Android is available in the official documentation.

4.5.8.14.2.1. Download Handler

During a conversation, agents and visitors may exchange files. These files can be downloaded and have to be stored somewhere on the user’s device. By default, files are store in the device’s external storage. However, you may prefer to ensure that files are only accessible from within your app for security reasons, and that the app manage downloaded files itself.

To manage downloaded files within your app, you must provide the SDK with a custom implementation of the UnbluDownloadHandler interface via UnbluClientConfiguration.Builder#UnbluDownloadHandler. Any downloads initiated by the user will trigger the custom download handler, which must handle the download itself and store the file somewhere within your app.

4.5.8.14.3. Log stripping

The logging section above describes how to configure the log level and whether any values are logged within a log statement.

If you prefer, you can remove log statements from the binary entirely by adapting the app’s proguard-rules.pro file. The SDK already defines the following rules to strip out debug and verbose level debug logs:

-assumenosideeffects class com.unblu.sdk.core.internal.utils.Logger {
    public static *** d(...);
    public static *** v(...);
}

You can do the same for all other log levels, too:

  • INFO: public static * i(…​);

  • WARN: public static * w(…​);

  • ERROR: public static * e(…​);

4.5.8.14.4. Encrypting stored preferences

The SDK needs to store some internal values inside the app to properly identify the user device against the collaboration server even after restarting the app. By default, shared preferences in private mode are used to store those values.

In many cases this is secure enough because normally, only the app itself has access to this data. Sometimes, though, you may wish to encrypt the values before storing them. To do so, provide the SDK with a custom implementation of UnbluPreferencesStorage interface via UnbluClientConfiguration.Builder#setPreferencesStorage. The SDK will use this storage whenever it needs to write or read the value of a preference to persistent storage.

4.5.9. iOS mobile SDK integration

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.

The information here refers to version 4 of the Unblu iOS mobile SDK. Please refer to the Unblu 6 documentation for information on version 3 of the SDK, and Unblu 5 documentation for information on version 2 of the SDK.
4.5.9.1. Requirements

The required version of iOS depends on the version of both the Unblu server and the iOS mobile SDK you are using:

Table 1. Minimum required version of iOS

Unblu 6

Unblu 7

mobile SDK v3

iOS 12 or newer

iOS 14.5 or newer

mobile SDK v4

N/A

iOS 14.5 or newer

4.5.9.2. Framework composition

Unblu is divided into modules, and depending on your implementation, you may use all, or only some of them. Each module is distributed as an XCFramework, Apple’s binary framework format.

In total, there are four frameworks. The core framework must always be added:

  • UnbluCoreSDK.xcframework

Additionally, there are three optional modules:

  • UnbluMobileCoBrowsingModule.xcframework

  • UnbluCallModule.xcframework

  • UnbluFirebaseNotificationModule.xcframework

The binary type of each Unblu framework depends on whether it requires external dependencies. The table below illustrates the binary type for each Unblu framework:

Unblu Framework Name Binary type

UnbluCoreSDK

dynamic

UnbluMobileCoBrowsingModule

dynamic

UnbluCallModule

static

UnbluFirebaseNotificationModule

static

To add the files to an Xcode project, you need to add them to your app target. They can be dragged and dropped directly into this section.

The Unblu modules that have external dependencies are distributed as static frameworks, but you must provide the actual dependencies themselves. They aren’t included in the frameworks. Which dependencies you need will depend on the Unblu modules you use. The following table shows the dependencies you need to add to your app for different Unblu modules. We recommend adding the dependencies via CocoaPods, but the table includes links to instructions on how to integrate the libraries manually.

Unblu module name Dependency name Version CocoaPods podfile Manual integration link Purpose

UnbluCallModule

OpenTok

~> 2.18

pod ‘OpenTok’, ‘~> 2.18’

Using the SDK

Needed for audio/video calls

UnbluFirebaseNotificationModule

Firebase Core

~> 7.0

pod ‘Firebase/Core’, ‘~> 7.0’

Integrate without CocoaPods

Base for Firebase messaging

UnbluFirebaseNotificationModule

Firebase Messaging

Derived from Firebase Core

pod ‘Firebase/Messaging’

Integrate without CocoaPods

Needed for push notifications

For Firebase to work correctly, you must add the GoogleService-Info.plist file from the Firebase project to your app. To do so, please follow the instructions here.

It is not necessary to set up Firebase in your code. This is done automatically by the SDK when push notifications are enabled.

4.5.9.3. Swift compatibility
4.5.9.3.1. Objective-C

The frameworks provided by Unblu are written in Swift, not Objective-C, as Swift is the new standard from Apple. In principle Swift code can be used in Objective-C, but there are some limitations. For example, enums in Swift need to have a raw type of Int. It is therefore not simply possible to use the SDKs in an Objective-C environment. If your project is formally an Objective-C project, you will need to convert it to a Swift project that mainly uses Objective-C. The usage of an SDK must then be wrapped in a Swift helper which in turn can be used in Objective-C. Currently Unblu does not provide any Swift helper classes.

4.5.9.3.2. Swift versions

In 2014, Apple wrote:

  1. if your project uses frameworks to share code with an embedded extension, you will want to build the frameworks, app, and extensions together. It would be dangerous to rely upon binary frameworks that use Swift —- especially from third parties. As Swift changes, those frameworks will be incompatible with the rest of your app. When the binary interface stabilizes in a year or two, the Swift runtime will become part of the host OS and this limitation will no longer exist.

Swift is ABI stable as of version 5.0, so if your project is running Swift 5.0 or newer, it should be able to interface with the Unblu SDK. If you require a version of the Unblu SDK built with an older version of Swift, please contact the Unblu support team.

Unblu aims to provide the iOS SDKs for the newest Swift version.

4.5.9.4. Permissions

Various features require that you include certain permissions in your application’s Info.plist.

NSPhotoLibraryAddUsageDescription

Required to add downloaded images to the Photos app

NSPhotoLibraryUsageDescription

Required to upload images from the Photos app to a conversation

NSCameraUsageDescription

Required to upload images taken by the camera into a conversation. It is also required by OpenTok for audio and video sessions. OpenTok is a dependency of UnbluCallModule.

NSMicrophoneUsageDescription

Required by OpenTok for audio and video sessions. OpenTok is a dependency of UnbluCallModule.

You should also enable the following background modes:

Audio, Airplay, and Picture in Picture

Required to continue calls when your app is in the background

Remote notifications

Required to receive all push notifications

4.5.9.5. Code setup and initialization

Before using the Unblu SDK in your code, you need to add the statement import UnbluCoreSDK to any Swift file that requires it.

4.5.9.5.1. Unblu instance

The two most important Unblu instance types you can create using UnbluCoreSDK are:

Both types inherit from UnbluClient which provides shared functionality such as start and stop.

To create an instance of either UnbluVisitorClient or UnbluAgentClient, use the static functions Unblu.createVisitorClient and Unblu.createAgentClient respectively. The Unblu instance created this way is not a singleton. You must implement your own solution for managing the lifecycle of the Unblu instance.

It is highly recommended to create an instance of Unblu inside the AppDelegate.application function and then pass this around your application where it is required.

In theory, you can have more than one Unblu instance running at the same time. However, it is strongly discouraged because Unblu is not designed to work this way.

4.5.9.5.2. Unblu client configuration

When creating an instance of the UnbluVisitorClient or UnbluAgentClient, you need to provide a configuration. This is done by passing an instance of UnbluClientConfiguration to the Unblu.createVisitorClient and Unblu.createAgentClient functions, respectively. The UnbluClientConfiguration struct can be instantiated with the base URL of the Unblu server and the API key of the Unblu account.

For all possible configurations and their effects, take a look at the documentation of UnbluClientConfiguration. Only a limited number of settings can be configured via the Unblu SDKs. All configurations which are independent of the client (the app) can be done via the Unblu Account Configuration interface.

To properly separate the configuration for the mobile visitor API, the mobile agent API, and the webpage where Unblu is integrated, we recommend that you use different API keys for each environment.

The Unblu client instance only stores a copy of the configuration, so you can’t change the configuration via the reference alone. To reconfigure Unblu, you must create a new Unblu instance and pass in your new UnbluClientConfiguration.

4.5.9.5.3. Unblu client delegate

The Unblu client delivers events via delegation.

Both protocols inherit shared functionality from the UnbluClientDelegate protocol. The functions to adopt in these protocols are all optional and are there to inform you of specific events so you can take certain actions.

Make sure to assign your delegate before you call UnbluClient.start.

One of the more important delegate functions to be aware of is unblu(didRequestShowUi reason: UnbluUiRequestReason, requestedByUser: Bool). If you are using push notifications, we strongly recommend that you adopt this function in your implementation. Suppose there is a push notification when there is an incoming call. If the user opens the app by clicking the notification, Unblu will call this function and assume that the app will display the UnbluView as soon as possible.

4.5.9.5.4. Starting and stopping

The UnbluClient instance provides functions called UnbluClient.start and UnbluClient.stop to start and stop the connection, respectively. As these functions are defined on the UnbluClient protocol, they are available on both the UnbluVisitorClient and UnbluAgentClient.

Both functions accept a completion block that is called with a Result type containing success or an error, depending on the outcome.

If the Result represents a success, the UnbluView will start rendering Unblu content, you can start new conversations, check agent availability etc.

Note that how quickly Unblu is ready to be used after it is started depends on the user’s connection speed. If you are using push notifications, it is also important to have started Unblu at least once, so that a deviceToken (required for APNS connectivity) can be delivered to the Unblu server. Without the deviceToken, the Unblu server has no way to determine the link between a user and their device. Therefore, in general we recommend that you start Unblu as soon as possible, ideally directly after login.

If Unblu is no longer needed you should call the UnbluClient.stop function. This will terminate the connection and clean up resources.

4.5.9.6. Modules

Unblu provides three modules that extend the default functionality provided by the UnbluCoreSDK:

  • UnbluMobileCoBrowsingModule

  • UnbluCallModule

  • UnbluFirebaseNotificationModule

To use the UnbluMobileCoBrowsingModule and UnbluCallModule, you must register them with the UnbluClientConfiguration before you create your Unblu instance. You do this by creating an instance of the module and registering it via the UnbluClientConfiguration.register function.

4.5.9.6.1. UnbluMobileCoBrowsingModule

The UnbluMobileCoBrowsingModule provides co-browsing functionality which enables real time interaction and collaboration between an agent and a visitor. To create an instance of the UnbluMobileCoBrowsingModule you need to call the UnbluMobileCoBrowsingModuleProvider.create static function, passing in a configuration object of type UnbluMobileCoBrowsingModuleConfiguration. You then register this module via the UnbluClientConfiguration.register function.

4.5.9.6.2. UnbluCallModule

The UnbluCallModule provides the neccessary functionality to make audio and video calls. To create an instance of the UnbluCallModule you need to call the UnbluCallModuleProvider.create static function. You then register this module via the UnbluClientConfiguration.register function.

4.5.9.6.3. UnbluFirebaseNotificationModule

If you use Firebase to receive push notifications from Unblu, you’ll need to import the UnbluFirebaseNotificationModule.

You don’t need to register the UnbluFirebaseNotificationModule.

4.5.9.6.3.1. Using UnbluFirebaseUIApplicationDelegate

As part of the Firebase module, Unblu provides some helper classes to make integration with Firebase easier. One of the classes, UnbluFirebaseUIApplicationDelegate, can be used as the base class for your AppDelegate:

import UnbluFirebaseNotificationModule

class AppDelegate: UnbluFirebaseUIApplicationDelegate {

}

If you choose to subclass UnbluFirebaseUIApplicationDelegate, Unblu will be able to configure Firebase push notifications for you automatically.

To receive push notification data in your AppDelegate, you can override a number of functions:

override func on_application(
    _ application: UIApplication,
    didReceiveRemoteNotification userInfo: [AnyHashable: Any])
{

}

override func on_application(
    _ application: UIApplication,
    didReceiveRemoteNotification userInfo: [AnyHashable: Any],
    fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void)
{

}

To receive the device push token provided by Firebase, you can override the following function:

override func on_messaging(
    didReceiveRegistrationToken fcmToken: String?)
{

}
4.5.9.6.3.2. Manual integration

If you choose not to use UnbluFirebaseUIApplicationDelegate, you’ll need to manually integrate with Firebase and pass relevant push notification data to Unblu, such as device tokens, and remote notification data, when it is received. This is not covered by this documentation. Please ask the Unblu support team for more details.

4.5.9.7. UnbluView

All Unblu UI content is rendered into a UIView subclass called UnbluView. This is available via the UnbluClient.view property.

The UnbluView provides an Unblu UI that shows all existing conversations. These conversations can be used to chat and make calls.

You need to add the UnbluView to a view hierarchy somewhere in your app for it to be visible on the device. It is up to you to decide the view’s size and position within the context of your application.

You don’t have to add the UnbluView into your app view hierarchy before calling UnbluClient.start, but we recommend that you do so. Unblu will maintain the UnbluView in a hidden view hierarchy until you add it to your own view hierarchy. Likewise, if you remove the UnbluView from your view hierarchy at runtime, Unblu will keep it alive until you call UnbluClient.stop.

screenshot mobile sdk ios

Sometimes, Unblu will request that you show the UnbluView via the delegate (see section above), e.g. because there is an incoming call or mobile co-browsing just started. It is up to you to respond to these requests and take the user to wherever you have the UnbluView rendered in your application.

For the hide request, you have to enable the configuration property com.unblu.conversation.ui.autoCollapseIndividualUiOnLayerActivation.

It is also possible to add a "back" button to the Unblu UI that enables the user to explicitly hide the Unblu UI. In this situation, a hide request is sent which you must respond to. The config property that enables this behavior is com.unblu.visitor.ui.showOverviewActionBarCollapseAction on the visitor side, and com.unblu.agent.mobile.ui.showInboxActionBarCollapseAction on the agent side.

If there is an issue with the Unblu UI, please be aware that the UI is rendered inside a WKWebView. You can therefore attach the local Safari to check for error logs. It is a limitation of the iOS WebViews that it is not possible to see the logs inside the normal debugger console.

4.5.9.8. Conversations

The UnbluConversation protocol provides the neccessary APIs to interact with conversations in Unblu. This includes actions such as opening and closing the conversation, starting audio or video calls, and launching mobile co-browsing sessions.

The functions that start calls and mobile co-browsing sessions require the presence of the UnbluCallModule or UnbluMobileCoBrowsingModule, respectively. If the required module is not registered to the Unblu instance, an error will be thrown at runtime.

The current open conversation is always available via the UnbluClient.openConversation property. If no conversation is currently open, the value of the property is nil.

If you wish to be notified when a conversation is opened or closed, adopt the unblu(didChangeOpenConversation openConversation: UnbluConversation?) function in your delegate implementation.

The main functions of note on the UnbluClient relating to conversations are:

Additionally, the UnbluVisitorClient provides:

It is also possible to intercept conversation-related activity by setting the UnbluVisitorClient.conversationInterceptor to an object conforming to the UnbluConversationInterceptor protocol.

4.5.9.9. Private views

As part of the UnbluMobileCoBrowsingModule, Unblu provides a simple way to add specific views which should not be shown on the remote side. After a view’s tag is added, the view is then automatically overlaid by an image before the screen is transmitted to the remote side. To do so, the UnbluMobileCoBrowsingModuleApi provides the function addPrivateView which takes a tag as its input parameter. You can define a different tag for each view.

You can make a view visible to the remote side again by calling the removePrivateView function, which is also exposed on the UnbluMobileCoBrowsingModuleApi.

4.5.9.10. Custom cookies

It is possible to define custom cookies, which should be sent with each request to the Unblu server. This can either be done (initially) by using the UnbluClientConfiguration or by setting the cookies dynamically on your Unblu client instance via the UnbluClient.customCookies property.

When the Unblu client is started, the last cookies configured are always used. If the client is already started, cookies with the same name are overridden, and any new cookies are added. Cookies set here will survive on the Unblu instance even when the client is stopped. They will be applied again to the WebView when the instance is started again. As such, if the client is started again, the last defined cookies are used.

4.5.9.11. Named areas

Similar to a web page, the named area feature is also available for the mobile SDKs.

A named area can be set either via the UnbluClientConfiguration before starting the client, or via the UnbluClient.namedArea property.

If a named area is set before starting the client, also the specific configuration for the named area is loaded on initialization. If it is set later, it only changes the requests for new conversations in the agent desk queue in the way that the agent can filter by the named area. The named area has no effect for existing conversations.

As a consequence, it’s important to know if there will be specific configuration on the named area scope. In this case the named area has to be configured or set in the SDK before you start the client. You should, however, consider changing the configuration at the API key level rather than on the named area. If a named area is only used for the queue, it can be set at any time before starting a new conversation.

4.5.9.12. File uploads

You can restrict the file types that users may upload with the following configuration properties:

These options affect the Unblu mobile SDK, too. However, the restrictions in place aren’t reflected in the iOS UI. Use com.unblu.filemanager.fileTypeInputTagHint to provide the iOS with a hint as to which file types a user may upload.

Consult the article on configuring file uploads for further information.

4.5.9.13. Push notifications

If the SDK is configured to use push notifications, there are currently two possible types of notifications visible to the user. Whenever there is a new message and if there is an incoming call. Basically for both types the system default sounds for notifications and calls should be used to provide the best user experience. As for the incoming calls notification, you can’t use the default sound on iOS. We therefore recommend that you define a custom sound for the incoming call push notification. This can be done on the collaboration server via the config property com.unblu.mobile.push_notification.iOSIncomingCallSound or also for the new message notifications com.unblu.mobile.push_notification.iOSNewMessageSound. The value has to be the name of the file including the file type ending. The file itself has to be available inside the app. Make sure it is added to the Build Phases step Copy Bundle Resources.

4.5.9.14. Logging

The Unblu SDK uses an internal Logger, which can be configured. By default, the logger doesn’t print any additional, potentially security related information. To change this behavior for debugging purposes, set the flag UnbluClient.enableDebugOutput to true. You can change the log level using the field UnbluClient.logLevel.

It is also possible to enable performance logging for mobile co-browsing. This is done via the UnbluMobileCoBrowsingModuleConfiguration object used to configure the UnbluMobileCoBrowsingModule. For performance logging, the log level has to be .debug or lower, and the UnbluClient.enableDebugOutput flag must be enabled.

4.5.9.15. Security-relevant configuration

There are several security-related configuration possibilities when integrating the Unblu iOS SDKs. The following points should be taken into consideration to ensure the SDK is configured in the most secure way without limiting the features available.

4.5.9.15.1. Whitelist URLs

By default, only the configured Unblu base URL and its subroutes may be accessed by the SDK’s internal WebView. On the other hand, you must be able to specify that a URL is also accessible if, say, the initial URL is redirected to another domain. To this end, you can provide a list of regular expressions by way of the UnbluClientConfiguration.internalUrlPatternWhitelist variable. If you do not have this requirement, there is no need to configure the internal pattern whitelist as it is secure per default.

The patterns in the internal pattern whitelist are those used by the Unblu-enabled application itself. If you want to specify URL patterns which may be accessed by having your application launch another application, modify the external link pattern whitelist described in the section below. This applies even if the patterns describe URLs within your organization’s domain.

If you want to use Google fonts in your mobile app, take into account that https://fonts.googleapis.com redirects to https://fonts.gstatics.com. You will have to include a pattern for the latter domain in the whitelist.

Whitelisting external links is handled by the externalLinkHandler property and the UnbluExternalLinkHandler protocol.

When you initialize UnbluClientConfiguration, you must provide an object that conforms to the UnbluExternalLinkHandler protocol. Unblu provides a default implementation of this protocol called UnbluDefaultExternalLinkHandler.

When a link is tapped in a conversation, Unblu calls the function decidePolicy(for: URL) → UnbluExternalLinkHandlingPolicy on the UnbluExternalLinkHandler. How Unblu proceeds depends on whether the function returns .open, .block, or .ignore.

UnbluClientConfiguration exposes the link handler via the new externalLinkHandler property.

For more information, please review the Unblu iOS mobile SDK reference entries of the following types:

4.5.9.15.3. Certificate pinning

The SDK uses a WKWebView for most of it’s communication, and URLSession for file downloads. For certificate pinning the WKNavigationDelegate method is called to handle URLAthenticationChallanges and file download challenges triggered via URLSessionDelegate method.

To define a handler for these challenges, you need to provide an object that conforms to the AuthenticationChallengeDelegate protocol and pass it to UnbluClientConfiguration.authenticationChallengeDelegate.

4.5.9.15.3.1. UnbluAuthenticationChallengeHandler

If you do not want to write the code to handle certificate pinning yourself, Unblu provides a class that does the heavy lifting for you, and all you have to do is pass the certificate data, or public keys. This class is called UnbluAuthenticationChallengeHandler. Please refer to the documentation for this class for more information on how to use it.

4.5.9.15.4. File downloads

The SDK needs to know how to download files.

In most cases, the default handling provided by UnbluDefaultFileDownloadHandler is sufficient, so passing an instance of this class to the initializer of UnbluClientConfiguration is all you’ll need to do. However, if you want to implement your own solution, you must pass your own object conforming to the UnbluFileDownloadHandler protocol to the initializer of UnbluClientConfiguration.

4.5.9.15.5. Log stripping

In iOS, there’s no need to explicitly strip out log statements as they can’t be accessed from the binary of the app by simple means anymore, although they are visible within the binary files delivered by Unblu.

4.5.9.15.6. Encrypting stored preferences

The SDK needs to store some internal values inside the app to properly identify the user device against the collaboration server even after restarting the app. By default, UserDefaults.standard is used to store these values. this is achieved by passing an instance of UserDefaultsPreferencesStorage to UnbluClientConfiguration when it is initialized.

In many cases this is enough because normally, only the app itself has access to this data. You may, however, wish to encypt the values before storing them. To do so, you have two options:

  • Provide the SDK with a custom implementation of UnbluPreferencesStorage when you initialize UnbluClientConfiguration. The SDK will then use this storage whenever it needs to write or read the value of a preference to persistent storage.

  • Use UnbluKeychainPreferencesStorage to store preferences in the iOS keychain. Please refer to the documentation for this class for more information on how to use it.

4.5.9.16. Known issues
  • UIDocumentInteractionController isn’t compatible with the Unblu mobile co-browsing engine. If you are using UIDocumentInteractionController to display a PDF and you want this PDF to be captured by Unblu during mobile co browsing, please either display your PDF using WKWebView, or Apple’s PDFKit framework.

4.6. External messenger integration

External messengers are supported with Unblu version 6.

4.6.1. Overview

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.

Custom External Messenger Integration Architecture

4.6.2. Integration

4.6.2.1. Integration custom channel
Custom External Messenger Integration Flow

A custom channel works via the Unblu server Web API and Webhooks. Typically a custom channel is connected with some Custom Middleware which creates conversations in the Unblu server when needed and it translates the messages from the Unblu server into the format of the external messenger and vice versa.

4.6.2.1.1. Channel creation

To integrate an external messenger via a custom channel, a custom channel first needs to be created via the WebAPI (see step 1 in image below) or the UI. The custom channel defines the webhook endpoint, to which messages are send to and how the external messenger is displayed in the UI. The Unblu server ensures, that only those messages which were initially not send by the external messenger channel, are send out to the webhook. Otherwise there would be a feedback loop.

4.6.2.1.2. Create Linked conversation

After a channel was created, new conversations which should be connected via this channel can be created.

The reason why and especially when a conversation should be created, depends on the integration scenario. A conversation could be created when the custom middleware receives a message from the external messenger (step 2a) and no corresponding conversation on the Unblu server exists. In this case typically a conversation with initial engagement type CHAT_REQUEST would be created with only the visitor person to directly send it to the queue.

Alternatively if there is already a mapping between the contacts inside the external messenger and agents inside the Unblu server, these conversations can be created at the very beginning.

A conversation is connected to the custom external messenger channel by giving the ID of the channel in the creation call (step 2b).

Optionally a source ID in the conversation can be defined to link the conversation back to the external source. Using the service Conversations#findBySourceIdAndChannelId, it is then possible to find an Unblu conversation for the corresponding conversation inside the external messenger.

As a conversation can have some participants connected via Unblu and other participants connected via an external messenger, it is necessary to distinguish between them. To achieve this, the participants need to have the flag connectedViaExternalMessenger set accordingly. This means an agent which should use the Agent Desk, but is marked as connectedViaExternalMessenger will not be able to write messages from the Agent Desk.

4.6.2.1.3. Sending and receiving messages

Whenever the custom middleware receives a new message from the external messenger (step 3a), the message needs to be transformed into an Unblu message via the middleware. This message can then be send into Unblu by using the ExternalMessengers#sendMessage API (step 3b). Afterwards those message will be visible in the Unblu UI of a chat.

Whenever the Unblu server receives a message that should be propagated to the external messenger, a new webhook event of type external_messenger.new_message is emitted to the custom middleware (step 4a). When the custom middleware receives this event, it needs to be transformed into a message of the external messenger and send it into that system (step 4b).

Step 3 and Step 4 are independent of each other. There can be multiple message from the external messenger as well as from the Unblu server, and they not need be linked technically or contextually to each other.

4.6.2.1.4. Managing read and delivered states

Please refer to the appropriate section of the Message states article for information on how to handle message state with external messengers.

4.6.2.1.5. Distinguishing between agents when using a central business account

In many external messengers, the custom middleware is represented as one central business account. This means that all messages sent from the Unblu server are shown as originating from this business account, regardless of which agent they are from. To distinguish between the different senders, the middleware may need to add a prefix such as <senderName>: to each message.

4.7. Bot integration

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

Bot Integration Architecture

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.

4.7.1. Bot types

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.

4.7.2. Bot persons

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.

4.7.3. Conversation-observing bots

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.

4.7.4. Dialog bots

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:

  • Unblu makes sure only one person is in the dialog with the bot to allow seamless integration with existing bot frameworks.

  • Dialogs can be

    • handed off to the next bot or an agent,

    • solved so no further involvement from other bots or agents is required, or

    • canceled to stop the boarding process.

  • Dialog bots can use all Unblu Web API services during the dialog to alter conversations and persons.

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.

4.7.4.1. Setting up a dialog bot

The initial step of integrating a dialog bot is to set it up.

  1. If no bot person has been created beforehand a bot person has to be created.

  2. Next, a dialog bot has to be created. This involves defining things such as the webhook endpoint, which persons should be on- and offboarded etc.

    Reboarding can only be enabled or disabled as it only involves the visitor. For more details see the create DialogBot API.

Once this is done, your bot is ready to participate in the onboarding/reboarding/offboarding of the configured persons.

Bots must be enabled for a conversation type to be offered the interaction. This can be changed in the settings for the conversation type. Look for the setting called com.unblu.conversation.bot.externalBotsEnabled.
Bot Dialog 1 - Setup
4.7.4.2. Receiving and responding to a dialog offer

Once the dialog bot is set up, the Unblu server will send a dialog offer webhook (more specifically, an onboarding, reboarding or offboarding offer) each time a person matching the configured filter joins or leaves the conversation, respectively. We will only consider the onboarding case here, but the reboarding and offboarding case follows the same lines.

When we speak of the visitor below, we actually mean the dialog counterpart person. We have chosen to refer to them as the visitor since this is the most common case. However, it is also possible to onboard or offboard agents using a bot. (Reboarding, on the other hand, is only possible for the main visitor of a conversation.)

The onboarding offer webhook serves two purposes:

  1. It allows the bot to decide whether they want to be part of the onboarding, with the full context of the onboarding person and the conversation they are entering.

  2. It ensures that the bot is available. This keeps visitor waiting time to a minimum if the bot were to malfunction.

When a bot receives an BotOnboardingOfferEvent webhook, it must respond to that offer as fast as possible. Otherwise the server will deem the bot dysfunctional and automatically exclude it from the further onboarding after a short timeout. Using the Web API, a bot can either accept or decline the onboarding offer.

If the offer is declined, the bot’s participation in this onboarding ends here. No further webhooks will be sent for this onboarding.

If the bot accepts the offer, the Web API call returns the dialog token that will be used later on for all webhooks of this dialog. The bot will be placed in the onboarding queue with all other bots that have accepted the offer. When it is its turn to complete the onboarding for the visitor, it will receive a BotDialogOpenEvent webhook. This is the signal that the dialog between the bot and the visitor is now open and the bot can start sending messages.

All state that is connected to this dialog should be linked to the dialog token. The dialog token is sent in every webhook related to this dialog and will be needed for every dialog-related Web API call. If a new context or conversation must be created for the underlying bot framework, this is the time to do it. The new context or conversation should be linked to the dialog token which may be used to reference it later on.

The dialog remains open, and the bot is the only party interacting with the visitor, until the BotDialogClosedEvent webhook is received. More details about this can be found in closing a dialog

Even though a bot may have accepted a dialog offer there is no guarantee that it will receive the DialogOpen event for this dialog. Reasons for this can be that the conversation is ended or deleted before it is the bot’s turn, or another bot solves or aborts the dialog. Therefore make sure that your bot implementation does not keep any state during the dialog offer and the dialog open events to avoid memory leaks.
Bot Dialog 2 - Offer
4.7.4.2.1. Disable file upload during onboarding and offboarding

By default, the Visitor UIs provide the same functionality during onboarding and offboarding as they do in other phases of a conversation. In particular, if the configuration property com.unblu.conversation.file.allowFileCobrowsing is true, visitors can upload files to a conversation during onboarding and offboarding.

If you wish to prevent this, set the following two configuration properties to false:

This will ensure that visitors cannot upload files to a conversation unless it is either in the queue or has been answered by an agent.

4.7.4.3. The active phase of a dialog

During the active phase of a dialog, the bot can use the Web API to send different types of chat messages to the visitor. The bot integration code may also use other Web API services, e.g. the Conversations or Persons services to influence the routing of the conversation or the visitor’s details. Additionally, the bot receives a BotDialogMessageEvent webhook for every message either the bot or the visitor sends.

If an anonymous user logs in during this phase, this triggers a user change. Please refer to the section handling user changes below for further information

Bot Dialog 3 - Active
4.7.4.4. Closing a dialog

When the bot has solved the visitor’s issue, doesn’t know what to do, or has finished its onboarding tasks, it is time to close the dialog.

There are several ways how this can be accomplished, but the usual way is by making the appropriate Web API call. When finishing a dialog via Web API, the reason for ending the dialog may be either HAND_OFF, SOLVED or ABORTED.

4.7.4.4.1. HAND_OFF

HAND_OFF means proceeding to the next step of the boarding process. If more than one bot responded to the boarding offer, and the current bot is not the last one in the queue, this is accomplished by handing the process over to the next bot in the queue.

If there is no further bot in the queue, what happens depends on the type of dialog.

  • For onboarding dialogs, hand-off will either

    • activate the onboarding participation and put the conversation in the incoming queue if the conversation is a chat request, or

    • activate the person being onboarded and allow them to interact with others for other conversation types or if the person was invited to join an ongoing conversation.

  • For reboarding dialogs, this will put the conversation back into the incoming queue if there is no further bot.

  • For offboarding dialogs, this will do one of the following either

    • end the conversation if the offboarding was triggered by ending a conversation, or

    • end the participation of the offboarding person if the offboarding was triggered by that person leaving.

4.7.4.4.2. SOLVED

SOLVED means that no further bot or human agent is required. The boarding process is stopped with a success indication. Any further bots that responded to the boarding offer will be ignored.

For onboarding and reboarding dialogs, this will also

For offboarding dialogs, it will also

  • End the conversation if the offboarding was triggered by ending a conversation.

  • End the participation of the offboarding person if the offboarding was triggered by the leaving of that person.

4.7.4.4.3. ABORTED

ABORTED means that no further bots should be called. The boarding process is stopped with a failure indication. Any further bots that responded to the boarding offer will be ignored.

  • For onboarding dialogs, the participant is directly moved to the offboarding phase and won’t be allowed to enter the conversation.

  • For reboarding dialogs, the conversation is put into the UNASSIGNED state.

  • For offboarding dialogs, the participation of the person being offboarded is ended.

This reason can be used when, for example, the visitor doesn’t accept mandatory terms and conditions.

4.7.4.4.4. The BotDialogClosedEvent webhook

When a dialog is closed, a BotDialogClosedEvent webhook will be sent. This may occur as a result of the finishDialog API call. However, it may also be sent for other reasons: a timeout, the visitor leaves or ends the conversation manually etc.

Make sure your code integrating the bot can always handle this event and is able to clean up everything related to that dialog, even if the event isn’t expected at that point.
Bot Dialog 4 - Close
4.7.4.5. Handling user changes

If a visitor logs in during an active bot dialog phase, this may trigger a user change within Unblu. The user change will occur if

As a result of the user change, the bot’s counterpart in the dialog will change their identity from an anonymous to an authenticated person.

To inform the bot of this change, Unblu sends an additional BotDialogCounterpartChanged webhook event. The event contains both the old and the new person identifying the bot’s counterpart in the dialog. Once this event has been received, any further messages sent by the visitor will reference the new person and the new person’s PersonPresence. Unblu will make sure that any messages sent by the bot will be received and displayed to the person’s new identity.

You must ensure that all bot logic referring to the identity of the counterpart person (like their name, email address, authentication etc.) references the new, authenticated person after a BotDialogCounterpartChanged webhook event.
4.7.4.6. Managing read and delivered states

Please refer to the appropriate section of the message states article for information on how to handle message state with dialog bots.

4.8. Web API and webhooks

The Unblu Web API provides an HTTP-based interface that allows other systems to perform actions on the Unblu server. It supports many of the same actions accessible through the conventional user interfaces. This enables the integration of Unblu with third-party applications. For example, the Web API could be used to implement the following functions:

  • A customer relationship management application that pre-initializes a conversation between each relationship manager and each of their customers, based on the relationships already recorded in a CRM system.

  • A call center application that dispatches incoming conversation requests to the appropriate agents connecting through Unblu.

  • An identity management system that automatically updates the status of agents and composition of teams based on changes to its database.

Unblu Webhooks enable integration in the reverse direction. They allow you to configure the Unblu server to react to internal events by triggering an HTTP request to an external system. This functionality can be used to implement features such as:

  • An identity management system that’s updated whenever some agent user data is updated on Unblu.

  • A third-party dashboard system that’s updated whenever a conversation is started or ended.

  • An archive of conversations that’s updated every time a conversation ends.

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

4.8.1. Web API

4.8.1.1. Introduction

The Unblu Web API exposes all the major entities that make up the internal data model of the Unblu server and offers methods to create, read, update and delete these entities via HTTP GET and POST requests. The entities are represented as a JSON objects in the bodies of HTTP requests and responses.

Examples of entity types include user, team, conversation and account. Definitions of all the entity types can be found in the Web API Reference, under Schemas.

The API methods (the actions that can be performed through the API) are organized into services. Most services are associated with a specific entity type. For example, the services associated with the above entity types are, respectively, users, teams, conversations and accounts. The services are documented in the Web API Reference, under Operations.

Under each service, several methods are typically available, for example, read, getAll, create, update and so forth. The API is designed to be as consistent as possible (the same methods are offered for the different entities), but for some entities more methods are available than for others.

4.8.1.2. Structure of a request

Calls to the Web API are made by sending HTTP GET, POST, or DELETE requests to the Unblu server.

The following grammar shows the structure of the request URL:

<url> ::= <serverinfo>/<pathprefix>/rest/<version>/<entity>/<action>[<params>]
<serverinfo> ::= https://[<username>:<password>@]<hostname>[:<port>]
<pathprefix> ::= app | unblu  // By default
<version> ::= v2 | v3  // Depends on server version
<service> ::= // See reference documentation
<action> ::= // See reference documentation
<params> ::= // Depends on action

The significant parts of the grammar are described below:

4.8.1.2.1. <username>:<password>@

Optional. If using basic authentication, the sender can embed the username and password in the URL itself. See Basic authentication, below.

4.8.1.2.2. <hostname>

The name of the server to which you are directing your request. For on-premises installations this will, of course, depend on the location of your own installation. For the Unblu Cloud, this is always unblu.cloud.

4.8.1.2.3. <port>

Optional. An on-premises installation may require a port to be specified, depending on your set up. For the Unblu Cloud, there is no port number.

4.8.1.2.4. <pathprefix>

The path prefix indicating the entry path of the request. In most cases this is unblu or app, but see Entry path below.

4.8.1.2.5. rest

The keyword rest is used to route the request to the Web API handler.

4.8.1.2.6. <version>

This specifies the version of the API that you wish to use. Possible values with Unblu 7 are v2 or v3. See API versioning, below.

4.8.1.2.7. <service>

Web API actions are organized into services. Each service corresponds to the type of internal entity being addressed, for example accounts, users, teams, etc.

4.8.1.2.8. <action>

The action to be performed on the entity indicated by the service, for example, create, delete, getAll, etc.

4.8.1.2.9. <params>

Optional. Parameters that modify or fully specify the action. These may be either URL query parameters (the ones after the ?) or additional elements in the path. See Parameters for details.

4.8.1.3. Authentication

In order to make most API calls, the client must be authenticated by the server to determine whether it has sufficient permissions to perform the operation. The permission level in Unblu is defined by the client’s role: ANONYMOUS_USER, WEB_USER, REGISTERED_USER, SUPERVISOR, ADMIN or SUPER_ADMIN (see User roles). For each call, the required minimum role is noted as "required-role" in the Web API reference section.

There are two mechanisms available for authentication with the Unblu Web API: Basic Authentication and the Authenticator Service.

4.8.1.3.1. Basic authentication

Basic Authentication is the standard authentication mechanism supported natively by all browsers and built-in to HTTP. To authenticate using this method the client can either:

  • Add the header Authorization: Basic <credentials> to the request, where <credentials> is the base64 encoding of the user ID and password joined by a single colon, :.

  • Prepend <userid>:<password> to the URL, as mentioned above.

4.8.1.3.2. Authenticator service

The Authenticator Service of the Web API provides an alternative mechanism for authentication. Under this method the client uses their user name and password to request an authentication token (which can then be used to login), or to login directly. In either case, a successful login will result in a response that includes a Set-Cookie header. The client can then cache the provided cookie and include it with any subsequent requests.

See Authenticator Service reference section.

4.8.1.4. Data and types

All data sent and received via the API is in JSON format. It is recommended to set the Content-Type and Accept headers accordingly on each request:

Content-Type: application/json
Accept: application/json

The types of JSON objects sent and received are all documented in Web API Schemas.

4.8.1.5. Entry path

The <pathprefix> segment of the Web API URL is used to indicate the entry path of the request.

Unblu has two entry paths that are relevant in the context of the Web API, the INTERNAL and the PUBLIC entry path. The default INTERNAL path prefix is app, and the default PUBLIC path prefix is unblu. You can change the path prefixes with the configuration properties com.unblu.identifier.internalPathPrefix and com.unblu.identifier.publicPathPrefix, respectively.

Just as every Web API call has a minimum required role, so it has a minimum required entry path:

  • An API call with an INTERNAL entry path can perform both INTERNAL and PUBLIC operations. INTERNAL API calls must use the INTERNAL path prefix.

  • An API call with a PUBLIC entry path can only perform PUBLIC operations. PUBLIC API calls may use either the INTERNAL or PUBLIC path prefix.

Each call’s required entry path is documented in the Unblu Web API reference.

4.8.1.5.1. Example

Suppose Unblu is running on example.com and the default path prefixes have not been changed. A call to perform the INTERNAL operation accounts/getAll on API v3 would look like this:

GET https://example.com/app/rest/v3/accounts/getAll

A call to perform the PUBLIC operation authenticator/login could look like this:

POST https://example.com/unblu/rest/v3/authenticator/login

{
    "username" : "...",
    "password" : "..."
}

Alternatively, it could look like this:

POST https://example.com/app/rest/v3/authenticator/login

{
    "username" : "...",
    "password" : "..."
}

In the Unblu Cloud, the entry path prefix configuration is fixed to the default values.

4.8.1.6. API versioning

The Unblu Web API is versioned. As shown above in the request URL structure, the version indicator can be specified as part of the path. Current possible values are v2 and v3.

A new API version is introduced as soon as a breaking change is introduced into the API. When a new API version is introduced, the old version is kept for the duration of one major version life cycle of the product to ensure compatibility with existing consumers of the old API.

Adding properties to the entities transferred by the Web API is not considered a breaking change. It is your responsibility to ensure that the application consuming the Unblu Web API can deal with unknown properties. For example, if the application that consumes the Web API was written using Jackson, you should set DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES to false.
4.8.1.6.1. Changes between server versions

The API version and the Unblu product version are related as follows:

  • Unblu 5 supported API v1 and v2

  • Unblu 6 supported API v1, v2 and v3

  • Unblu 7 supports API v2 and v3. v1 has been removed.

4.8.1.7. Parameters

Depending on the action, various parameters may be required. In some cases these are to be specified as query parameters, as in

GET <prefix>/rest/v3/accounts/isAccountNameAvailable?name=<name>&accountId=<accountId>

or as additional path segments, as in

POST <prefix>/rest/v3/conversations/<conversationId>/setRecipient

{
    ...
}

The parameters for each call (if any) are documented in the reference section for that call.

4.8.1.7.1. The expand parameter

Many API JSON objects contain related objects within their properties. When such a sub-object is shown inside a top-level object it is usually represented by an ID.

The expand query parameter allows you to specify that one or more properties in an object are to be represented in fully expanded form, not just as IDs. Multiple properties can be specified by using a comma-delimited list. The general form of the expand query parameter is:

expand=<prop1>[,<prop2>,...,<propN>]

Only some properties in some objects are expandable. When a property is expandable, this is noted in the Web API reference.

Starting with Unblu 7.1.0, if you include a property in the expand parameter that can’t be expanded, Unblu considers the request invalid and returns a 4xx response. Previously, Unblu simply ignored the invalid property.

The expand parameter can be used in three ways:

  • On read

  • On write

  • For the special properties configuration, metadata, and text

4.8.1.7.1.1. Expand on read

On read, the expand parameter specifies which properties in the returned object are to be in expanded form. For example, the request

GET <prefix>/rest/v3/users/getByUsername?username=johndoe

would return something like

{
    "$_type": "User",
    "id": "VPu6G3Y0QU6Y1nRn2nPzog",
    "creationTimestamp": 1572276276000,
    "modificationTimestamp": 1572517581000,
    "version": 9,
    "accountId": "wZvcAnbBSpOps9oteH-Oxw",
    "avatar": "VJPN47X8Q4iVxIqQtT8DAQ",
    "username": "johndoe",
    "email": "[email protected]",
    "phone": null,
    "teamId": "3iy_Jpd7QwilXGC_7w3KRg",
    "authorizationRole": "REGISTERED_USER",
    "displayName": "John Doe",
    "firstName": "John",
    "lastName": "Doe",
    "configuration": null,
    "metadata": null
}

whereas the request

GET <prefix>/rest/v3/users/getByUsername?username=johndoe&expand=avatar

would return something like

{
    "$_type": "User",
    "id": "VPu6G3Y0QU6Y1nRn2nPzog",
    "creationTimestamp": 1572276276000,
    "modificationTimestamp": 1572517581000,
    "version": 9,
    "accountId": "wZvcAnbBSpOps9oteH-Oxw",
    "avatar": {
        "$_type": "Avatar",
        "id": "VJPN47X8Q4iVxIqQtT8DAQ",
        "creationTimestamp": 1572517579000,
        "modificationTimestamp": 1572517579000,
        "accountId": "wZvcAnbBSpOps9oteH-Oxw",
        "imageZoomFactor": null,
        "imageXPositionRatio": 0.5,
        "imageYPositionRatio": 0.5,
        "imageRotationAngle": 0,
        "imageData": "data:image/png;base64,..."
    },
    "username": "johndoe",
    "email": "[email protected]",
    "phone": null,
    "teamId": "3iy_Jpd7QwilXGC_7w3KRg",
    "authorizationRole": "REGISTERED_USER",
    "displayName": "John Doe",
    "firstName": "John",
    "lastName": "Doe",
    "configuration": null,
    "metadata": null
}

Note that in the first object, the avatar property is an ID whereas in the second example, avatar is expanded to be an object.

4.8.1.7.1.2. Expand on write

The expand parameter can also be used on write. Write requests typically include the data to be written as a JSON object in the request body. In this context, the expand parameter can be used to specify that one or more properties of that object will be submitted in fully expanded form.

For example, the request below will update the avatar of the user johndoe. Without the expand=avatar query parameter, the avatar sub-object would be ignored.

POST <prefix>/rest/v3/users/update?expand=avatar

{
    "$_type": "User",
    "id": "VPu6G3Y0QU6Y1nRn2nPzog",
    "creationTimestamp": 1572276276000,
    "modificationTimestamp": 1572517581000,
    "version": 9,
    "accountId": "wZvcAnbBSpOps9oteH-Oxw",
    "avatar": {
        "$_type": "Avatar",
        "id": "VJPN47X8Q4iVxIqQtT8DAQ",
        "creationTimestamp": 1572517579000,
        "modificationTimestamp": 1572517579000,
        "accountId": "wZvcAnbBSpOps9oteH-Oxw",
        "imageZoomFactor": null,
        "imageXPositionRatio": 0.5,
        "imageYPositionRatio": 0.5,
        "imageRotationAngle": 0,
        "imageData": "data:image/png;base64,..."
    },
    "username": "johndoe",
    "email": "[email protected]",
    "phone": null,
    "teamId": "3iy_Jpd7QwilXGC_7w3KRg",
    "authorizationRole": "REGISTERED_USER",
    "displayName": "John Doe",
    "firstName": "John",
    "lastName": "Doe",
    "configuration": null,
    "metadata": null
}
4.8.1.7.1.3. Expand for special properties

The object types

  • accounts

  • users

  • teams

  • apikeys

  • namedareas

have one or more the following special properties:

  • configuration

  • metadata

  • text

When these properties are returned in an object, they normally have a value of null. This is the case for the configuration and metadata properties in the user object shown above.

However, if one of these properties is specified in the expand parameter then it is returned in full.

4.8.1.7.1.4. Using expand with SECRET and MULTILINE_SECRET configuration properties

If you make a read request with the expand=configuration query parameter, and the entity you requested includes a configuration property of the type SECRET or MULTILINE_SECRET, the value of the configuration property will be masked. This is the case for configuration properties used to store keys, secrets, and passwords, such as com.unblu.storage.database.auth.password.

If you update an entity and you send the expand=configuration query parameter, you must include any masked configuration properties with the mask as their values. If you omit them, the configuration properties and their values will be deleted.

4.8.1.8. CRUD examples

In general the API supports full CRUD (Create, Read, Update, Delete) operations on all the entities that it exposes, subject to the permissions of the API client, of course.

The examples below use the users service as an example. Similar patterns apply to the other services.

4.8.1.8.1. Create

To create a new user, the client sends a POST with a request body holding the JSON object representing the new user entity:

POST <prefix>/rest/v3/accounts/create

{
    "$_type": null,                         // ignored
    "id": null,                             // has to be 'null' for create operation
    "creationTimestamp": null,              // ignored
    "modificationTimestamp": null,          // ignored
    "version": null,                        // ignored
    "accountId": "wZvcAnbBSpOps9oteH-Oxw",  // optional
    "avatar": null,                         // optional
    "username": "johndoe",                  // required
    "email": "[email protected]",         // required
    "phone": null,                          // optional
    "teamId": null,                         // optional
    "authorizationRole": "REGISTERED_USER", // required
    "displayName": "John Doe",              // optional
    "firstName": "John",                    // required
    "lastName": "Doe",                      // required
    "configuration": null,                  // only when 'expand' is used
    "metadata": null                        // only when 'expand' is used
    }

The above object depicts the full set of properties of the user entity. In this example, comments are included for explanation. In practice comments are not permitted. See User Type.

Notice that you do not have to specify every property. Some are ignored and some are optional. That leaves the required properties username, email, authorizationRole, lastName and firstName.

On a successful creation, the server responds with the JSON object of the newly created user. The returned object will have filled in the internally generated properties $_type, id, creationTimestamp, modificationTimestamp and version.

Note also that if you want to include one of the expandable properties (avatar, configuration or metadata) inline in the submitted object then you must specify that property in the expand query parameter.

Similar details involving ignored, optional, required and expandable properties apply to the other entity types. This information is documented in the reference sections for those types.

4.8.1.8.2. Read

Reading is straightforward: A GET request is made and a JSON object is returned that represents the requested entity. See below for an example.

4.8.1.8.3. Update

Writing is done by issuing a POST request with the request body containing the data to be written. Keep in mind that the API does not support patch syntax. In other words, you cannot specify only the properties that you want to change on a write. You must send the entire object even if you are making a change to only one property in the object.

The best way to perform a change to an entity, therefore, is:

  • Request the entity.

  • Take the returned JSON and alter the property or properties that you wish to change.

  • Send back the newly updated JSON using the appropriate update call for that entity type.

For example, let’s say you want to update the phone number of a registered user, you might perform the following series of calls:

4.8.1.8.3.1. Get the object
GET <prefix>/rest/v3/users/getByUsername?username=johndoe

returning

{
    "$_type": "User",
    "id": "VPu6G3Y0QU6Y1nRn2nPzog",
    "creationTimestamp": 1572276276000,
    "modificationTimestamp": 1572517581000,
    "version": 9,
    "accountId": "wZvcAnbBSpOps9oteH-Oxw",
    "avatar": "VJPN47X8Q4iVxIqQtT8DAQ",
    "username": "johndoe",
    "email": "[email protected]",
    "phone": "+1 416 555 0105",
    "teamId": "3iy_Jpd7QwilXGC_7w3KRg",
    "authorizationRole": "REGISTERED_USER",
    "displayName": "John Doe",
    "firstName": "John",
    "lastName": "Doe",
    "configuration": null,
    "metadata": null
}
4.8.1.8.3.2. Update the object

You change the phone property from +1 416 555 0105 to +1 416 555 0162, leaving everything else the same.

4.8.1.8.3.3. Send the updated object back

And now you send back the newly updated object as the body of the POST request:

POST <prefix>/rest/v3/users/update

{
    "$_type": "User",
    "id": "VPu6G3Y0QU6Y1nRn2nPzog",
    "creationTimestamp": 1572276276000,
    "modificationTimestamp": 1572517581000,
    "version": 9,
    "accountId": "wZvcAnbBSpOps9oteH-Oxw",
    "avatar": "VJPN47X8Q4iVxIqQtT8DAQ",
    "username": "johndoe",
    "email": "[email protected]",
    "phone": "+1 416 555 0162",
    "teamId": "3iy_Jpd7QwilXGC_7w3KRg",
    "authorizationRole": "REGISTERED_USER",
    "displayName": "John Doe",
    "firstName": "John",
    "lastName": "Doe",
    "configuration": null,
    "metadata": null
}
4.8.1.8.3.4. Receive confirmation of update

Assuming you have sufficient permissions to make the change, the server should respond with the updated object:

{
    "$_type": "User",
    "id": "VPu6G3Y0QU6Y1nRn2nPzog",
    "creationTimestamp": 1572276276000,
    "modificationTimestamp": 1572517581010,
    "version": 10,
    "accountId": "wZvcAnbBSpOps9oteH-Oxw",
    "avatar": "VJPN47X8Q4iVxIqQtT8DAQ",
    "username": "johndoe",
    "email": "[email protected]",
    "phone": "+1 416 555 0162",
    "teamId": "3iy_Jpd7QwilXGC_7w3KRg",
    "authorizationRole": "REGISTERED_USER",
    "displayName": "John Doe",
    "firstName": "John",
    "lastName": "Doe",
    "configuration": null,
    "metadata": null
}
4.8.1.8.3.5. What has changed

Notice that the phone number has changed. It now reflects the value you submitted in the update call. However, you will also see that some other properties are do not reflect the values that you submitted:

  • The modificationTimestamp is different. This makes sense since the entity has indeed been updated and therefore so has the timestamp.

  • The version has been incremented. This is a mechanism used to avoid concurrent update conflicts. On update the server checks if the version number on its copy of the entity is the same. If it is, that means no change took place in the meantime. The change is only applied if no conflict is detected. If you receive an "out of date" error, you have to re-request the original object and attempt the update again.

4.8.1.8.4. Delete

To delete an entity, send a DELETE request to the delete action of the corresponding service with a query parameter holding the ID of the entity. For example, to delete as user you would do the following:

DELETE <prefix>/rest/v3/users/delete?id=VPu6G3Y0QU6Y1nRn2nPzog
4.8.1.9. Searching

The Web API provides a search endpoint for many of the entities it exposes. The endpoint expects a POST HTTP request with the search criteria specified in the request body.

The body of a search request consists of

  • An array of one or more search filters

  • An optional ordering of the search results

  • An optional offset

  • An optional limit

The offset and limit can be used to paginate search results.

The examples below give you an idea of how to use the search endpoints.

Please refer to the Web API reference for details about the schema for the body of each search request.

4.8.1.9.1. Search filter operators

Below is a complete list of the operators you can use in the body of a search request.

CONTAINS

Checks if the value contains the string provided in the operator

EQUALS

Checks if the value is equal to the one provided in the operator

NOT_EQUALS

Checks if the value is not equal to the one provided in the operator

GREATER_THAN

Checks if the value is greater than the one provided in the operator

LOWER_THAN

Checks if the value is lower than the one provided in the operator

IN

Checks if the value is one of the ones provided in the operator

NOT_IN

Checks if the value is not one of the ones provided in the operator

IS_NULL

Checks if the value is null

IS_NOT_NULL

Checks if the value is not null

IN_RANGE

Checks if the value is in the range of the provided values. Results equal to the provided values are included.

NOT_IN_RANGE

Checks if the value is outside the range of the provided values. Results equal to the provided values are not included.

Which operators are available depends on the value of the field object they refer to. For example, it would make little sense to search for a string with the IN_RANGE operator. In fact, three operators are only available with the PARTICIPANT_PERSON_ID field of the body sent to the endpoint <serverUrl>/rest/v3/conversation/search:

ALL_OF

Checks if all of the values are present in the value list provided by the operator

ANY_OF

Checks if any of the values is equal to any of the values in the list provided by the operator

ALL_EQUAL

Check if the lists are of the same length and contain the same values

Again, please refer to the Web API reference for details about the operators available for each search request.

4.8.1.9.2. Example 1: webhook log error entries

Say you want to retrieve all entries in the webhook log that logged errors. To do so, you would call the webhookcalllogs/search endpoint:

Listing 47. Call to the webhookcalllogs/search endpoint to retrieve webhook log entries
POST <serverUrl>/rest/v3/webhookcalllogs/search

The body of the call would look like this:

Listing 48. HTTP request body to retrieve error entries in the webhook log
{
  "searchFilters": [
    {
      "field": "HTTP_RESPONSE_CODE",
      "operator": {
        "type": "NOT_IN_RANGE",
        "minimum": "200",
        "maximum": "299"
      }
    }
  ],
  "orderBy": [
    {
      "field": "ID",
      "order": "ASCENDING"
    }
  ],
  "offset": 0, (1)
  "limit": 10 (2)
}
1 With the offset set to 0, the call will return the first results found.
2 With the limit set to 10, the search will return at most 10 results. The response will tell you whether there are more results that match your search criteria.

The response to your request will look something like this:

Listing 49. Response to call to webhookcalllogs/search with more than 10 matches
{
  "$_type": "WebhookCallLogResult",
  "hasMoreItems": true, (1)
  "nextOffset": 10, (2)
  "items": [
    {
      "$_type": "WebhookCallLog",
      "id": "wxKdh3-DSJKvMrKz8PcXaw",
      "creationTimestamp": 1610725688976,
      "modificationTimestamp": 161072568898,
      // ...
    },
    // ...
  ]
}
1 "hasMoreItems": true tells you that there are more than 10 results matching your search criteria.
2 "nextOffset": 10 can be used to retrieve the next n results with a new request to the same endpoint.

If there are 10 or fewer log entries matching you search criteria, the beginning of the response will look like this:

Listing 50. Response to call to webhookcalllogs/search with 10 matches or fewer
{
  "$_type": "WebhookCallLogResult",
  "hasMoreItems": false,
  "nextOffset": null,
  "items": [
    {
      "$_type": "WebhookCallLog"
      // ...
    }
  ]
}

If there are no results matching your criteria, "items" will be an empty array:

Listing 51. Response to call to webhookcalllogs/search with no matches
{
  "$_type": "WebhookCallLogResult",
  "hasMoreItems": false,
  "nextOffset": null,
  "items": []
}
4.8.1.9.3. Example 2: All webhook log entries of a given day

Including the following body in your HTTP request to the endpoint <serverUrl>/rest/v3/webhookcalllogs/search will return all webhook log entries for 1 April 2021:

Listing 52. HTTP request body to retrieve entries in the webhook log created on 1 April 2021
{
  "searchFilters": [
    {
      "field": "CREATION_TIMESTAMP",
      "operator": {
        "type": "IN_RANGE",
        "minimum": "1617228000000", (1)
        "maximum": "1617314399999" (2)
      }
    }
  ],
  "orderBy": [
    {
      "field": "CREATION_TIMESTAMP",
      "order": "ASCENDING" (3)
    }
  ]
}
1 2021-04-01 00:00:00.000
2 2021-04-01 23:59:59.999
3 The oldest log entry will be the first result.
4.8.1.9.4. Example 3: Group of users

The following body returns all users in the team "Support" or "Advisory" created in March 2021 whose email address is blank.

Listing 53. HTTP request
{
  "searchFilters":  [
      {
        "field": "EMAIL"
        "operator": {
          "type": "IS_NULL"
        }
      },
      {
        "field": "TEAM_ID"
        "operator": {
          "type": "IN",
          "values": [
            "v01giHTYRvmoWClaPu3brw", (1)
            "xN7MxXZVT4ComUoHSOuijA" (2)
          ]
        }
      },
      {
        "field": "CREATION_TIMESTAMP",
        "operator": {
          "type": "IN_RANGE",
          "minimum": "1614553200000",
          "maximum": "1617227999999"
        }
      }
  ],
  "orderBy": [
    {
      "field": "TEAM_ID",
      "order": "ASCENDING" (3)
    },
    {
      "field": "CREATION_TIMESTAMP",
      "order": "DESCENDING" (4)
    }
  ]
}
1 The team ID for the "Support" team
2 The team ID for the "Advisory" team
3 The results will be grouped by team ID first
4 Within each team, the most recently created users will be shown first

The HTTP request must be sent to the endpoint <serverUrl>/rest/v3/users/search.

4.8.1.9.5. Example 4: Conversation participation

If you send the HTTP request body below to the endpoint <serverUrl>/rest/v3/conversations/search, you can retrieve all of the conversations in March 2021 that two particular people participated in:

{
  "searchFilters": [
    {
      "field": "PARTICIPANT_PERSON_ID",
      "operator": {
        "type" : "ALL_OF",
        "values" : ["-kQOBaTdTZ20QRqrlwOvqQ", "sPNlrHvzRQSrUm3GxCOGVg"] (1)
      }
    },
    {
      "field": "CREATION_TIMESTAMP",
      "operator": {
        "type": "IN_RANGE",
        "minimum": "1614553200000", (2)
        "maximum": "1617227999999" (3)
      }
    }
  ]
}
1 The participant person IDs of the participants you are interested in.
2 2021-03-01 00:00:00.000
3 2021-03-31 23:59:59:999

4.8.2. Webhooks

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:

Agent invitation and forwarding events

Events related to the creation, revocation and redemption of invitations sent to agents, or of forwarding of a conversation to an agent.

Conversation events

Events related to when conversations are created, updated, and ended, and to new messages sent to a conversation.

CRUD events

Events triggered when an entity is edited. The entities that can trigger such events are:

  • account

  • API key

  • domain

  • named area

  • person

  • team

  • user

PIN events

Events related to the creation, renewal, revocation, and redemption of PIN invitations.

Push notifications

Events triggered by new messages, messages being read, incoming calls, and calls being revoked.

Queue events

Events that are triggered by creating, revoking or redeeming assignment requests in the queue.

Visitor invitation events

Events related to creating, renewing, revoking, or redeeming invitations sent to visitors.

4.8.3. Reference material

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

  • <unblu-server>/rest/v2/openapi

  • <unblu-server>/rest/v3/openapi

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

5. Configuration

Unblu is highly configurable in order to be able to serve a wide range of use cases.

5.1. Overview

Configuration in Unblu is governed by a single namespace of configuration properties which can be adjusted both in configuration property files and through the web-based configuration UI.

A configuration property is a string of the form:

com.unblu.<x>.<y>.<z>=<value>

An example would be:

com.unblu.storage.database.driver=oracle.jdbc.driver.OracleDriver

5.2. Global configuration page

An Unblu installation can serve multiple customers. This multi-tenancy capability is implemented using the account entity. All configuration entities (users, teams, API-keys, canned responses) and business-data (conversation content) are coupled with one specific account. When an account is deleted, all associated data is also deleted from the system.

5.2.1. Superadministrator

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.

config global

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:

  • Search user allows you to search for a user across multiple accounts.

  • Session tracking allows you to see the sessions currently running on the Unblu server.

  • Migration provides tools to migrate configuration property files between Unblu versions.

5.3. Account configuration

Any user having the admin role can open the "Account configuration" page from the top right menu. There, all account-level configuration settings can be set and modified.

config account

5.3.1. Account

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

5.3.2. User management

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.

5.3.3. Site integration

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.

5.3.4. Product setup

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

5.3.4.1. Conversation template

A conversation template holds a set of configuration settings and text properties for conversations. When a new conversation is created, all the values of a template are copied to configure the new conversation. This allow to have different behavior for the conversation (different permissions, restriction of the collaboration features, activation of audio and/or video channel, specific concierge flows…​).

For each conversation engagement type there is at least one template (the default one), and additional templates can be created. Per configuration at account, API-key or named area level, it is possible to define which conversation template will be used for each engagement type. If nothing is defined, the default template for this engagement type will be used.

If a conversation template is modified (for example a configuration is changed), it will only affect the next conversations created based on this template. All existing conversation created with the template will stay configured the way they are.

5.3.4.2. Canned responses

Canned responses allow agents to use shortcuts for common messages instead of having to type the whole message. They can be specific to one agent, or shared between all the agents in a team or even an entire account.

Selecting a canned response in a chat conversation

Canned responses can be managed from different locations of the Account Configuration interface:

  • The Canned responses menu item is used for canned responses associated with the account

  • Each team and user has a Canned responses tab to manage the canned responses exclusive to them

  • The Manage profile menu item, accessed by clicking on the user’s avatar, provides access to the user’s personal Canned responses tab

There are two predefined placeholders, $(visitor_name) and $(agent_name), that can be included in the text of a canned response. You can also specify your own custom placeholders when you create a canned response.

When a canned response is used, predefined placeholders are automatically replaced by the correct value for the conversation. You will have to replace your custom placeholders with the appropriate values for the conversation.

5.3.5. Supervisor

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

  • They can edit their teams and sub-teams.

  • They can reorganize them but cannot create a new teams.

  • They can see all members of their own team and sub-teams.

  • They can edit the team assignment of the users belonging to their teams or sub-teams, but cannot create new users.

  • Finally, supervisors can manage canned responses for their teams and sub-teams, and for the members of their teams and sub-teams.

5.4. Configuration interface

The Unblu configuration interface is used to configure the system settings. Unblu is a highly configurable product where almost every significant feature can be adjusted. Consequently the configuration interface is quite extensive.

5.4.1. Configuration levels

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:

account config

The Global Server Configuration main page looks like this:

global server config

6. Security

6.1. Overview

Unblu is designed with the stringent security standards of the financial industry in mind. In the following section we describe how these standards are implemented in practice in an Unblu on-premises installation and in the Unblu Cloud.

6.2. User roles

Everyone who connects to Unblu, whether a visitor on your public website or someone within your organization, requires a user identity on the system. Unblu classifies user identities by role. The possible roles are:

6.2.1. ANONYMOUS USER

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.

6.2.2. WEBUSER

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.

6.2.3. REGISTERED_USER

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.

6.2.4. SUPERVISOR

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.

6.2.5. ADMIN

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.

6.2.6. TECHNICAL_ADMIN

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:

  • Users with the TECHNICAL_ADMIN role have no access to the Agent Desk.

  • In the Account Configuration interface, they can only access account-related functions.

  • Users with this role cannot configure webhooks, bots or external messengers. If they could, they would have an indirect way to access the contents of conversations.

  • The TECHNICAL_ADMIN user role has limited user management capabilities. Specifically, users with the role:

    • Can modify the settings of users and teams

    • Can create, modify, or delete canned responses of a user or team

    • Cannot create, modify, or delete users, including themselves

    • Cannot create, modify, or delete teams

6.2.7. SUPER_ADMIN

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:

  • create, modify, or delete any type of user and team

  • create, modify, or delete canned responses for users or teams

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:

  • Can only create TECHNICAL_ADMIN users in the account

  • Cannot create, modify, or delete teams in the account

The default value of the configuration property is false.

6.2.8. Role-based feature access

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.

Example of a role-based feature setting in the global configuration interface
Figure 19. Role-based feature setting that grants admins, but not superadmins, permission to delete conversations

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.

Superadministrators can change the settings that define role-based feature access. In principle, they can therefore grant themselves access to any feature.

6.3. Entry paths

The key security issue in any on-premises Unblu installation is the fact that the system spans both the public internet and your organization’s private network:

  • The public part of the Unblu installation is the visitor interface that appears on your company’s website. Because the interface forms part of the website, it is transmitted to the visitor’s browser and transmits information from the visitor’s browser back to the Unblu server.

  • Within your organization’s network perimeter, on the other hand, you have the actual Unblu server itself, as well as the agents that interact with the visitors. Because the agents are trusted employees of your firm, they have access to your internal network, through which they access the agent interface with their browsers.

To maintain the separation between these realms, Unblu is designed to leverage your existing secure infrastructure as much as possible. It does so by associating different entry paths with different levels of trust.

6.3.1. Levels of trust

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:

  • PUBLIC

  • INTERNAL

  • SYSTEM

6.3.2. Entry paths

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.

6.3.3. Combining levels of trust and entry paths

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.

  • A PUBLIC resource can be accessed by a request using the PUBLIC, INTERNAL or SYSTEM path prefix.

  • An INTERNAL resource can only be accessed by a request using the INTERNAL or SYSTEM path prefix but not the PUBLIC path prefix.

  • A SYSTEM resource can only be accessed by a request using the SYSTEM path prefix but not the PUBLIC or INTERNAL path prefix.

6.3.3.1. Example

Contrast the following two scenarios:

  • When you integrate the Unblu visitor UI into your public website, a <script> element similar to the one below will be embedded in your website’s code:

    <script src="https://unblu.example.com/unblu/visitor.js"></script>

    This HTML element loads the bootstrap code that, in turn, loads the Unblu visitor UI. Since this resource is intended for use in the public internet, the level of trust required to access it is PUBLIC, so the request for it can use the PUBLIC entry path with the path prefix /unblu/.

  • When an agent at your organization wants to navigate to their Unblu Agent Desk inbox, they point their browser to a URL such as

    https://unblu.example.com/app/desk/#/inbox

    Access to the Agent Desk requires the INTERNAL level of trust. The URL of the request therefore uses the INTERNAL entry path with the path prefix /app.

This pattern of determining the trust level required to fulfil a request based on the path prefix encoded in the request URL is used for all requests sent to the Unblu server.

6.3.4. Using entry paths to restrict access

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:

  • Requests that originate outside your company network will only be passed to the Unblu server if they have the PUBLIC path prefix /unblu.

  • Requests from within your company network will only be passed to the Unblu server if they have the INTERNAL path prefix /app.

  • If a request is made by other components closely connected to the Unblu server, it will only be passed to the Unblu server if it has the SYSTEM path prefix /system.

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:

Entry path
Figure 20. Entry path

6.3.5. The SYSTEM entry path

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

6.4. CSP headers

Unblu comes with three predefined sets of directives for the Content Security Policy (CSP) HTTP response header of its various interfaces.

6.4.1. Activating Unblu CSP directives

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:

  1. A set of directives for the Agent Desk, Visitor Desk, and Single Conversation Desk:

    Listing 54. Contents of the CSP response header for the Agent Desk, Visitor Desk, and Single Conversation Desk
    Content-Security-Policy: style-src 'unsafe-inline' 'self'; default-src 'none'; connect-src wss: 'self' *.opentok.com *.tokbox.com wss://*.tokbox.com ws:; img-src 'self' data:; media-src 'self'; font-src 'self' data:; script-src 'unsafe-inline' 'self' *.opentok.com *.tokbox.com wss://*.tokbox.com 'unsafe-eval'; frame-src 'self' blob:
  2. A set of directives for the Account Configuration interface, Global Server Configuration interface and SDK:

    Listing 55. Contents of the CSP response header for the configuration interfaces and mobile SDKs
    Content-Security-Policy: style-src 'unsafe-inline' 'self'; default-src 'none'; connect-src 'self'; img-src 'self' data:; media-src 'self'; font-src 'self' data:; script-src 'unsafe-inline' 'self' 'unsafe-eval'; frame-src 'none'
  3. A set of directives for the content of a visitor’s browser displayed to an agent in the Agent Desk during an embedded co-browsing session:

    Listing 56. Contents of the CSP response header for embedded content
    Content-Security-Policy: style-src 'unsafe-inline' 'self' *; default-src 'none'; img-src 'self' * data:; media-src 'self' *; font-src 'self' * data:; script-src 'unsafe-inline'; frame-src 'self' blob:

6.4.2. Modifying CSP header directives

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:

  • Add *.company.com to com.unblu.contentsecuritypolicy.allowedDomainsForUiResources.

  • Add both imgs.static.company.com and resources.company.com to com.unblu.contentsecuritypolicy.allowedDomainsForUiResources.

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

6.4.3. Limitations

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

6.4.4. Further information

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

6.5. The superadmin user

If the value of the configuration property com.unblu.storage.createSuperAdmin is true, then a superadmin user will be created as part of the initial installation of the Unblu collaboration server. The username can be specified in the configration property com.unblu.storage.superAdminUsername. If no username is provided, a username will be generated from a WebUUID.

6.5.1. Initial superadmin password

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

  • If the property is not empty, the superadmin password will be set to whatever value the property has.

  • If the property is empty, a random password will be generated and stored in a file called credentials.txt. The file is located either within the directory specified in com.unblu.logging.outputDirectory (if present) or in the system’s default temporary folder.

    The file credentials.txt is also created when the configuration property com.unblu.storage.createSuperAdmin is true and the property com.unblu.storage.superAdminUsername is empty.

Store this password securely! It is required to access the server’s agent desk and to administer the installation.
The password file must be deleted after the initial server startup, otherwise the server will not allow ordinary, non-superadmin users to log in.

6.5.2. Restoring the superadmin password

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.

7. Visitor experience

An end customer or visitor has different ways to interact with a company using Unblu as its central collaboration platform.

7.1. Site Integration

Usually the Unblu collaboration suite is integrated into the website of the customer, such as the online banking website, the insurance customer center, and so on.

7.1.1. Floating Visitor UI

The floating visitor UI consists of 4 major elements:

The Unblu launcher button

This button is typically positioned in the bottom right corner and is the first interaction point of the visitor with Unblu. It allows to maximize and collapse the Conversation Panel and also gives information about the current state:

  • If the visitor has unread messages a small badge with a notification count is displayed.

  • When a visitor enters a conversation the icon in the button changes to indicate that closing the conversation panel doesn’t end the conversation.

  • If the visitor pops out the conversation panel into its own window (usually used during calls) the launcher button changes its icon to allow "popping in" the window again.

The conversation panel

The conversation panel is the main interaction window with Unblu. When initially opening it, it shows the overview with past conversations and ways to start new conversations. On the overview, the visitor also directly sees if there is an agent available or not. Based on the availability of agents the visitor sees different possibilities to start a conversation. From here the visitor can navigate in and out of conversations.

The collaboration space

The collaboration space is like an overlay over the whole website. As long as only chat is active, it’s not visible for the visitor. When embedded co-browsing is started in a conversation, a green frame and banner are displayed around the website, indicating that the content of the page is currently being shared. If any other collaboration layer (such as document or universal co-browsing) is activated, its contents are displayed inside the collaboration space, hiding the actual page behind it.

The collaboration layer control panel

The content displayed and the interactions that can be done within the collaboration space are controlled by the collaboration layer control panel. By default the panel is only displayed when a collaboration layer is activated. It floats over the collaboration space and allows the visitor to see which layer is active, to stop sharing that layer and depending on the configuration to control the active layer and switch to another one.

7.1.2. Embedded Visitor UI

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.

7.1.3. Visitor Desk

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.

7.1.4. Customization

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.

7.2. State management

The Unblu Site Integration UI has different states with different life cycles that shall be explained here.

Unblu manages visitors in devices. Each browser is identified as a device by setting a long-term cookie. This means, that the Unblu server will treat all tabs from one browser as belonging to the same device.

7.2.1. Visitor identity

7.2.1.1. Non-authenticated

When a non-authenticated visitor opens a website that has Unblu enabled, the visitors identity will be linked to the device cookie. As long as the visitor doesn’t delete their cookies and uses the same browser, they will be treated as the same person when coming back to the page and all past conversations will be visible to him.

7.2.1.2. Authenticated

When a visitor authenticates himself (and this authentication is propagated from the customers website e.g. E-Banking to the Unblu server) Unblu will always treat the visitor the same person and make all previous conversations available to the visitor independent of the system, browser or device they are using.

7.2.2. Open conversation

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.

7.2.3. UI state

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.

7.3. Visitor engagement use cases

There may be different use cases where the visitor will use the Unblu UI to engage with an agent. These use cases may be generally divided into two categories.

7.3.1. Engagement requests

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

  • Chat Request

  • Video Call

  • Voice Call

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.

7.3.2. PIN support conversations

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.

  • Embedded PIN

  • Mobile PIN

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.

7.3.3. Show conversations

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.

7.4. Conversation panel

7.4.1. Conversation overview

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.

  • Active conversations have a notification badge next to them if they contain unread messages. They can be entered and all collaborative features may be used in them.

  • Ended conversations are grayed out. They can be entered to view their content e.g. messages and files but no further collaboration can be done in these conversations.

7.4.2. PIN entry page

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.

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

7.4.3.1. Conversation action bar

The action bar within a conversation will feature info and actions specific to that conversation. The left side displays an avatar for every participants in the conversation except for the own avatar. Also keep in mind, that hidden participants will also not be displayed. Clicking on an avatar will reveal additional information as well as actions for that person.

Depending on the configuration one or several actions may be started from the action bar:

  • Start voice & video calls

  • Start sharing the own screen or website

  • Downloading a conversation log in csv format

  • Leaving the conversation

  • Ending the conversation

  • Navigating to the "All shared files" view

7.4.3.2. Messaging view

When a visitor opens or joins a conversation they will initially see the messaging view. This is the main conversation view which allows the visitor to read and write chat messages and share files using the clip icon. Shared documents can be downloaded or co-browsed if the file type is supported by the document co-browsing layer. Approvals to start collaborations can be accepted or declined here.

7.4.3.3. Files view

The files view shows all files that have been shared in this conversation. Files may be downloaded, deleted or co-browsed from here.

7.4.3.4. Call view

When a visitor starts a voice or video call or there is an incoming call inside a conversation the call view is displayed. The call view takes up the whole Conversation Panel to give a maximum focus to the call. Once the call is active the visitor may use several features on the call view:

  • Go back to the Messaging UI.

  • Enable or disable the microphone & camera.

  • Take a snapshot of the ongoing call (only if the agent has video enabled).

  • Maximize the conversation panel to take the whole window size.

  • Pop the conversation panel out into its own window..

If a call is active, the file and messaging views will display a banner on the top indicating this. Clicking on the banner will open the full call view again. Also if the other person in the call is sharing video, a small preview of that video will be displayed in a movable overlay on these views.

8. Supervisor and administrator

Supervisors and admins are special agent roles in Unblu. Besides being agents, they can manage several additional aspects of a team or an account. Admins have more permissions than supervisors.

8.1. Supervisor

Supervisors manage their team, sub-teams, and all the users in those teams. To manage the teams and users, they can open the Account configuration. Managing a team or user means that supervisors can change the properties of an entity, but they can’t create or delete them. For more information, see User Management.

One key capability of supervisors is that they can check the conversation history of not only their conversations but also all the conversations of the agents in their teams.

Additionally, supervisors can use the Agent Monitor to see if their teams perform well or if there are any bottlenecks.

8.2. Administrator

An admin has all the capabilities to manage the whole Unblu account.

In the Agent Desk they can basically do the same as a supervisor. Inside the conversation history, they can see all the conversations of the account. Furthermore, in the Agent Monitor, admins can monitor teams and agents, and check if they’re short on capacity or if everything is working as expected.

When an admin opens a conversation (in normal, preview, or ghost mode), they can change the configuration of the conversation.

On the Account configuration page an admin can manage all kinds of account entities and their settings/texts. This includes the account details themselves, teams, users, API keys, domains, named areas, conversation templates, canned responses, webhooks, bots and external messengers. Unlike supervisors, an admin can also create and delete those entities. Only the accounts themselves can’t be created or deleted by admins (that requires superadmin access).

8.3. Technical administrator

The technical administrator role is intended for IT specialists whose tasks involve configuring or troubleshooting Unblu.

Technical administrators have similar permissions to administrators as far as managing account configurations are concerned. However, they can’t access the Agent Desk or any conversations that take place in Unblu.

8.4. Agent monitor

Agent monitor

The agent monitor can be used by supervisors and admins. It provides information about the available capacity of agents, named areas, used filters and active sessions.

The UI is split into 4 sections:

  • Service status

  • Agent availability

  • Active sessions

  • Filtered chat queues

If one or more entries in one of the four sections are selected, all unrelated entries in the other sections are grayed out.

8.4.1. Service status

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.

8.4.2. Agent availability

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.

8.4.3. Active sessions

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.

8.4.4. Filtered chat queues

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.

8.5. Agent Desk

The agent desk is where your agents and advisors converse with visitors and clients. It provides for:

  • Handling the Queue of incoming conversation requests.

  • Managing an Inbox of current conversations.

  • Managing the Conversation History, keeping a record of all interactions.

  • For agents designated as Supervisors: managing teams of agents.

Here is the Agent Desk Inbox, showing the current, ongoing conversations:

agent desk elements 4

8.6. Team

Agents in Unblu can be organized into teams. A team is defined as a grouping that contains:

  • A supervisor (An agent with special permissions to manage the team, see below)

  • Zero or more agents (The members of the team)

  • Zero or more sub-teams (Teams can contain other teams, defining a hierarchy. Circular references are not permitted)

Teams are created and deleted by admins. Each team is managed by its supervisor.

8.7. Supervisor

The role of the supervisor is to manage their team. To do this, the supervisor role has all the permissions of a normal agent plus specific ones to do with team management. Specifically, supervisors can:

  • Manage their team and sub-teams through the Agent Monitor in the Agent Desk.

  • Edit the team assignments within the team and its sub-teams.

  • Manage the canned responses for their team in sub-teams.

However, supervisors can’t:

  • Create new agent accounts.

  • Change the user-level canned responses.

In general, only a subset of the user or team configuration items are available to the supervisor.

8.8. Admin

This is the highest business role in a single account. The Admin user can see, configure, and manipulate everything within a given account (see Accounts).

Admins can:

  • Create users and teams.

  • Define team hierarchy and assign agents to their respective teams.

  • Change configuration settings to integrate Unblu into the visitor website. This includes adapting the interface to reflect corporate standards and branding.

  • Manage the conversation templates used when new conversations are created.

  • Manage canned responses for the account, each team or each individual user.

  • Set up webhooks for integration with third party applications.

8.9. Superadmin

The superadmin is the highest role in the system. The difference between an admin and a superadmin is that the superadmin can see the "Global Server Configuration" item in the menu, where they will be able to manage global server-level settings. Specifically, superadmins can:

  • Create and remove accounts.

  • Act as admin for any particular account.

  • Manage the global configuration. For example, the superadmin can configure Settings and Texts at a global level, meaning that these settings will then be applied for all accounts, unless they are overridden at the account level.

9. Conversations

9.1. The elements of a conversation

The concept of a conversation is central to Unblu. To understand how Unblu works, it’s essential to have a solid grasp of the various elements that make up a conversation.

We don’t describe the configuration properties that affect a conversation or its components here. For more information on conversation configuration, see the configuration properties reference.

9.1.1. Overview

All communication in Unblu takes place within the context of a conversation. A conversation begins before there are any participants in the conversation, and a number of factors determine how Unblu creates a conversation.

First, Unblu ascertains the type of conversation to be created. This is referred to as the engagement type, and it’s used to determine which conversation template to base the new conversation on.

Next, Unblu identifies who may participate in the conversation. A conversation has two main participants: a visitor, and an agent. The main visitor is referred to as the Context person; the main agent is the Assigned agent. (There may also be other participants, as explained below in the section Conversation participants.)

The person or people who don’t initiate the conversation receive an invitation to join the conversation. If the conversation is initiated by a visitor, they are the primary participant on the visitor’s side. In such a case, the invitation is sent to the conversation’s Recipients, that is, those agents who have the authorization and/or skills required to join the conversation. The agent who accepts the invitation first and joins the conversation becomes the conversation’s Assigned agent.

Depending on the configuration, participants may leave a conversation and return to it later. Once one of the conversation’s participants is present in the conversation, a conversation session is opened. The session is maintained until no participants are present in the conversation.

9.1.2. Engagement types

When creating a conversation, Unblu uses the following factors to determine the conversation’s engagement type:

  • The person type of the person who initiates the conversation: either agent or visitor

  • The person type of the person that the conversation is centered around: again, either agent or visitor

  • The type of media initially used in the conversation

  • Whether the conversation is initiated in a standard Unblu UI or via the API

The engagement type determines the conversation template for the conversation. It’s only taken into account when first establishing a conversation. At that point, the configuration of the conversation template is copied to the conversation. From then on, the configuration of the conversation is independent of the conversation template. When an existing conversation is re-opened, the engagement type is no longer relevant.

9.1.2.1. Chat request

A visitor requests to chat.

  • Creator person type: visitor

  • Central person type: visitor

  • Media type: chat

  • Available in standard UIs: yes

9.1.2.2. Offline chat request

A visitor requests to chat while no agent is available.

  • Creator person type: visitor

  • Central person type: visitor

  • Media type: chat

  • Available in standard UIs: yes

9.1.2.3. Video request

A visitor requests to start a video call.

  • Creator person type: visitor

  • Central person type: visitor

  • Media type: video

  • Available in standard UIs: yes

9.1.2.4. Audio request

A visitor requests to start an audio call.

  • Creator person type: visitor

  • Central person type: visitor

  • Media type: audio

  • Available in standard UIs: yes

9.1.2.5. Universal co-browsing request

A visitor requests to start universal co-browsing.

  • Creator person type: visitor

  • Central person type: visitor

  • Media type: universal co-browsing

  • Available in standard UIs: yes

9.1.2.6. Screen sharing request

A visitor requests to start context migration co-browsing.

  • Creator person type: visitor

  • Central person type: visitor

  • Media type: screen sharing

  • Available in standard UIs: yes

9.1.2.7. Embedded co-browsing request

A visitor requests to start embedded co-browsing.

  • Creator person type: visitor

  • Central person type: visitor

  • Media type: embedded co-browsing

  • Available in standard UIs: yes

9.1.2.8. Mobile co-browsing request

A visitor requests to start mobile co-browsing.

  • Creator person type: visitor

  • Central person type: visitor

  • Media type: mobile co-browsing

  • Available in standard UIs: yes

9.1.2.9. Universal co-browsing PIN

An agent invites a visitor to join universal co-browsing via a PIN.

  • Creator person type: agent

  • Central person type: visitor

  • Media type: universal co-browsing

  • Available in standard UIs: yes

9.1.2.10. Screen sharing PIN

An agent invites a visitor to join screen sharing via a PIN.

  • Creator person type: agent

  • Central person type: visitor

  • Media type: screen sharing

  • Available in standard UIs: yes

9.1.2.11. Embedded co-browsing PIN

An agent invites a visitor to join embedded co-browsing via a PIN.

  • Creator person type: agent

  • Central person type: visitor

  • Media type: embedded co-browsing

  • Available in standard UIs: yes

9.1.2.12. Mobile co-browsing PIN

An agent invites a visitor to join mobile co-browsing via a PIN.

  • Creator person type: agent

  • Central person type: visitor

  • Media type: mobile co-browsing

  • Available in standard UIs: yes

9.1.2.13. Chat PIN

An agent invites a visitor to chat with them via a PIN.

9.1.2.14. Chat invite

This engagement type doesn’t reflect a standard use case. It can only be used for conversations that are created using the Unblu Web API. While it’s possible in principle to create conversations of any engagement type via the Web API, in practice, chat invite is the most commonly used engagement type under these circumstances.

9.1.2.15. Universal co-browsing invite

An agent sends a visitor an invitation to join universal co-browsing.

  • Creator person type: agent

  • Central person type: agent

  • Media type: universal co-browsing

  • Available in standard UIs: yes

9.1.2.16. Screen sharing invite

An agent sends a visitor an invitation to join screen sharing.

  • Creator person type: agent

  • Central person type: agent

  • Media type: screen sharing

  • Available in standard UIs: yes

9.1.2.17. Scheduled conversation

An agent creates a conversation with a topic and schedules it for some point in time.

  • Creator person: agent

  • Central person: agent

  • Media type: chat

  • Available in standard UIs: yes

9.1.3. Invitations

When a person creates a conversation, Unblu sends an invitation to other potential participants. To join a conversation, an invitee must redeem the invitation. An invitation can only be redeemed once. Thus, even if more than one person receives an invitation, at most one of these people can join the conversation using this invitation.

Besides being redeemed, an invitation can also be revoked, either by an agent or by Unblu, provided it hasn’t yet been redeemed. Once an invitation has been revoked, it can no longer be used to join a conversation.

9.1.3.1. Recipients

If a visitor initiates a conversation, the agent or group of agents to receive an invitation to join a conversation are referred to as the conversation’s recipients. They’re potential participants in the conversation.

Once a recipient has redeemed the invitation, it isn’t possible for other recipients to join the conversation with the same invitation. However, the conversation’s recipient stays the same when the invitation has been redeemed.

If a conversation is forwarded to another agent, team, or named area, they become the conversation’s new recipient.

Recipients are displayed in the conversation list of the floating visitor UI until a recipient redeems the invitation.

9.1.3.2. Invitation types

There are a number of different types of invitation, depending on who initiated the conversation and on the purpose of inviting the other person.

9.1.3.2.1. Conversation request

This is the most common type of invitation. It’s sent to conversation Recipients when a visitor initiates a conversation.

9.1.3.2.2. Agent forwarding

When an agent forwards a conversation to another agent (or to a team), the new agent receives this kind of invitation. Once the latter joins the conversation, they become the conversation Assigned agent, and the original assigned agent leaves the conversation.

9.1.3.2.3. Agent invitation

This kind of invitation is used to invite an agent to join a conversation as a secondary agent. The status of other agents in the conversation isn’t affected when the invited agent joins.

9.1.3.2.4. Visitor invitation

This is the kind of invitation created when an agent adds a visitor to an existing conversation using the Invite a customer option in the agent desk. Any user with the invitation ticket of an visitor invitation can join the conversation as a visitor. Once the invitation has been redeemed it can’t be used by another visitor.

9.1.3.2.5. PIN conversation

This invitation type is used for universal, mobile, and embedded PIN sessions. Any user with the invitation ticket can join the conversation as a visitor. The invitee redeems the invitation by entering a PIN code. Once the invitation has been redeemed it can’t be used by another visitor.

The invitation types discussed above can all only be redeemed once. An agent setting up a conversation with multiple participants has to create a separate invitation for each invitee. Furthermore, if a participant redeems an invitation but fails to join the conversation for some reason or other, the agent has to send them a new invitation.

Agents can opt to provide participants with a public link instead. All participants can use the same link. This way, agents can send all participants a single email with the same link, for example.

If you don’t want your agents to create public links, disable the option with the configuration property com.unblu.conversation.invitation.allowPublicLinkAccess in the CONVERSATION_TEMPLATE scope.

When a visitor opens a public link, the Visitor Desk opens on the Request admission page:

*Request admission* page in the Visitor Desk

When the visitor has filled in their details and clicked on the Join button, they must wait for an agent in the conversation to review their admission request. If no agent has the conversation open in the Agent Desk, the page ask them to wait for an agent to join:

*Request admission* page after entering details if no agent is present

If an agent is viewing the conversation, the visitor is asked to wait for the agent to admit them to the conversation:

Request admission page after entering details if an agent is present

Since anyone can use a public link to join a conversation, Unblu lets agents perform a basic check of who is trying to join the conversation using a public link. This option is controlled by the configuration property com.unblu.conversation.invitation.requireAgentApprovalBeforeJoin. Set to true, Unblu displays a modal dialog like the one below.

Dialog of visitor requesting admission to a scheduled conversation via a public link

The assigned agent can grant or deny access to the conversation on a person-by-person basis. If you don’t want your agents to vet participation requests via public links, set the configuration property to false.

Once an agent admits the visitor to the conversation, Unblu treats the visitor as if they had used a personal invitation.

9.1.4. Conversation participants

A participant in a conversation is a person who has joined that conversation. Unblu distinguishes between different participants depending on their person type (visitor or agent) and on whether they’re primary or secondary participants in the conversation. What participants are able to do in a conversation is configurable. You may wish to prevent visitors from inviting other people to join the conversation as Secondary participants, for example.

9.1.4.1. Context person

The context person is the primary visitor in a conversation.

The primary visitor is the first visitor to join the conversation. This person defines certain aspects of the conversation such as the default language used, the size of certain UI elements in the collaboration space and when collaboration layers can be opened (see Conversations). For this reason, the primary visitor is also referred to as the context person.

9.1.4.2. Assigned agent

The assigned agent is the primary agent in a conversation.

The assigned agent is the agent who is initially assigned to the conversation. This typically occurs when the agent selects the incoming conversation from their queue.

9.1.4.3. Secondary participants

Secondary participants are participants invited to join a conversation by a current participant of the same conversation. For example, Unblu allows the assigned agent of a conversation to invite other agents and visitors to join them. Who is able to invite whom to join a conversation is configurable.

9.1.4.3.1. Secondary visitors

For visitors, we distinguish between the primary visitor (or context person) and secondary visitors.

Secondary visitors are any visitors other than the context person participating in a conversation. For example, a relationship manager may wish to chat with two clients in different locations. In this case, the relationship manager could start a conversation with one of their clients and then invite the other client to join them in the conversation. Here, the first client would be the context person and the second client would be a secondary visitor.

There can be more than one secondary visitor in a conversation.
9.1.4.3.2. Secondary agents

For agents, we also distinguish between the assigned agent and secondary agents.

Any agents participating in a conversation who aren’t the assigned agent of that conversation are referred to as secondary agents.

For example, a relationship manager may wish to invite a tax specialist from the bank to take part in a conversation with their client. In that case, the tax specialist would join the conversation as a secondary agent.

There can be more than one secondary agent in a conversation. In the previous example, the relationship manager could also invite their assistant and one of the bank’s lawyers. All three invitees would be secondary agents.

Another context where secondary agents are important is in long-running conversations between advisors and their clients. By inviting a secondary agent to the conversation, relationship managers can ensure that their clients' enquiries are dealt with in a timely fashion even if they themselves are unavailable.

For more information, see Hidden secondary agents.

9.1.4.3.3. Hidden participants and ghost participants

Hidden participants are secondary participants in a conversation who aren’t visible to the other participants.

Two kinds of participants can be hidden: bots and secondary agents. For information on hidden bots, see Conversation-observing bots.

Hidden secondary agents participate in a conversation just like normal secondary agents: they can see the conversations where they’re secondary agents in their inbox under Secondary Conversations. There, they can open a conversation and observe it as it happens. However, if they begin to participate actively in the conversation—​by sending a message to the chat, for example--, they become visible to the other participants.

Unlike hidden participants, ghost participants aren’t actual participants in a conversation. They may view a conversation, usually by using the Preview button in the inbox or the conversation history of the Agent Desk.

Depending on the configuration of the conversation, ghost participants have the right to execute actions such as forwarding the conversation to another agent or inviting another agent. For more information, see the configuration properties reference.

9.1.5. Conversation session

When at least one participant is present in a conversation, a session is created in the context of that conversation. Conversation participants who are online are said to be present in the conversation session.

9.2. Collaboration layers

Unblu’s collaboration layers allow conversation participants to view the content of a website, a mobile app or an application together. They make communication more effective and provide a richer experience for your visitors.

Unblu offers five different collaboration layers, each serving a different purpose and often using different technology:

  • Embedded co-browsing

  • Universal co-browsing

  • Document co-browsing

  • Screen sharing

  • Mobile co-browsing

This article describes the collaboration layers. It presents each collaboration layer and explains the differences between the layers.

For information on how to work with collaboration layers, see the Floating Visitor UI guide and the Agent Desk guide.

The article Configuring and manipulating collaboration layers provides information on the various ways you can customize the configuration of each collaboration layer.

9.2.1. Embedded co-browsing

The embedded co-browsing collaboration layer allows collaboration on web pages instrumented with the Unblu JavaScript snippet. It does so using a technique called DOM capturing, which runs in the visitor’s browser. The visual state of the visitor’s browser is cloned and transferred to the agent. Additional resources like images or CSS files that the agent’s browser needs to replicate the visitor’s view of the page are retrieved separately, not from the visitor’s browser.

As mentioned above, each page you want to enable embedded co-browsing on must contain the Unblu JavaScript snippet. Without it, the state of visitor’s view of a page cannot be forwarded to the agent. You can add the JavaScript snippet to the <head> section of the pages you want to instrument. Alternatively, you can have the snippet injected dynamically by the SecureFlow Manager or a tag management system.

Embedded co-browsing allows access to the full set of collaboration tools: mark mode, remote control, and scroll lock.

Since you have control over the pages that are instrumented for embedded co-browsing, you can also take advantage of other features, such as the ability to hide page elements from agents. Please review the article on Configuring and manipulating collaboration layers for further details.

Embedded co-browsing allows in-context sessions. This means that the visitor’s current browser information is kept intact. For example, suppose a visitor has logged in to your website and requests a co-browsing session. All of the visitor’s context information, such as their login information and browsing history, carry over into the embedded co-browsing session. Agents thus have access not just to the web page the visitor was on but to the whole context of what they were doing, such as completed form fields.

Although a very powerful tool, embedded co-browsing does have some technical limitations. Please review the article on the Limitations of embedded co-browsing for an in-depth discussion.

9.2.2. Universal co-browsing

Universal co-browsing requires the Unblu rendering service. Please refer to our guide on Configuring the rendering service for information on how to configure the rendering service.

In a universal co-browsing session, participants in the conversation can view websites together that haven’t been instrumented for use with Unblu. For example, if a relationship manager recommends that a client invest in a particular company, they may wish to view that company’s website together.

Universal co-browsing makes this possible by using the Unblu rendering service. * Each universal co-browsing session launches a new rendering service in a Docker container. The rendering service is an application based on a Chromium browser running in headless mode. * All of the participants in the session interact with this browser instance, and the same graphical output is streamed to all of the participants. * The view of the browser is transmitted to all participants via the WebRTC API. Check our browser requirements page to see which browser versions support WebRTC. * Interaction with the browser — mouse clicks, marking, editing and the like — takes place via the collaboration server, which forwards the interaction to the rendering service via gRPC.

The participants in a universal co-browsing session cannot see anything that is on another participant’s computer. This is a significant difference from embedded co-browsing and screen sharing sessions, where all participants view the contents of a particular participant’s browser. It also means that, unlike with embedded co-browsing, it is not possible to hide part of a page from some participants and show to others.

Like embedded co-browsing, universal co-browsing comes with collaboration tools that are not available in screen sharing sessions: mark mode, remote control, and scroll lock.

9.2.3. Document co-browsing

Document co-browsing requires the Unblu rendering service. Please refer to our guide on Configuring the rendering service for information on how to configure the rendering service.

Document co-browsing allows the participants of a conversation to view a single copy of a document together. With the appropriate settings enabled, participants can also highlight sections of the document or edit it.

To co-browse a document, a conversation participant must upload it to the conversation. Any participant with the required permissions can then initiate a co-browsing session of the document. As with universal co-browsing, the interaction between participants and the software displaying the document takes place over the WebRTC API.

When a document is edited in the course of a co-browsing session, the modified document must be uploaded to the conversation to save the changes. If the document is not uploaded to the conversation, the changes made to the document will be lost. The rendering service does not store a copy of the document.

You can also integrate third-party electronic signature solutions such as DocuSign. This allows you to complete the entire contract negotiation process online, from the advisory stage to the final signature.

9.2.3.1. Supported file types

Unblu allows you to co-browse PDF files, plain text (.txt) files, and images. (PDFs that require special plugins are not supported.)

It is possible to enable co-browsing of other file types, too. To do so, you will need access to software such as ONLYOFFICE or Microsoft Office Online Server that allows you to view and possibly edit these file types.

If you don’t have an on-premise solution such as Microsoft Office Online Server, using document co-browsing with files of a type other than PDF requires third-party services and involves uploading the files to the servers of those third parties.

9.2.4. Screen sharing

In a screen sharing collaboration session, the participants in a conversation all have access to the screen, or part of the screen, of one of the participants.

This is useful if, for example, a relationship manager wishes to share a view of a spreadsheet in Microsoft Excel to show a client some calculations they made without giving the client access to the Excel file itself. In the Agent Desk, that would look like this:

Screen sharing session, view in the Agent Desk

The client in the conversation would see this:

Screen sharing session, view in the floating visitor UI

When initiating a screen sharing session, the participant sharing their screen is usually asked which content they wish to share.

This is not a feature of Unblu but a security measure built into modern browsers.

Most browsers offer the following choices:

  • The entire screen

  • An application window

  • A browser tab

This flexibility can be very useful, since it allows people to share a view of their own computer without the need to share files or programs with the other participants in a conversation. If a customer is experiencing technical difficulties printing a contract, they could allow your support agents to view their printer settings.

However, screen sharing also has disadvantages compared to universal or embedded co-browsing:

  • There are no collaboration tools available in screen sharing sessions. Screen sharing is not a remote desktop solution.

  • It is easier to share content inadvertently that you did not want other participants to see.

  • The view being shared is captured by the browser of the participant sharing their screen. As a result, screen sharing may exhibit inconsistent behavior across different browsers.

  • Screen sharing uses the Screen Capture API to access the video and audio stream of a participant’s screen. This API is only available in relatively modern browsers.

  • Screen sharing relies on the page that the screen sharing session was launched from to remain available. If the visitor navigates to a different page instrumented with Unblu, the screen sharing session stops and must be re-initiated.

The specific browser versions that permit screen sharing are listed on the browser requirements page.

9.2.5. Mobile co-browsing

Mobile co-browsing refers to the possibility for your agents to join users of your mobile apps as they use them. This requires that Unblu is integrated into your mobile apps using the Unblu Mobile SDKs for iOS and Android.

The following features are available in mobile co-browsing sessions:

  • Co-browsing all of your app’s content

  • Interactions of the user with the device screen can be seen remotely

  • Orientation changes are displayed on the agent side

  • Lock the screen displayed in the agent desk if the visitor puts the app into the background

  • Areas of the app can be marked remotely

9.2.6. Collaboration tools

Unblu includes various tools to make working with collaboration layers more effective:

Mark mode

Allows conversation participants to mark an area of the view being shared in the conversation.

Remote control

Allows a conversation participant to take control of the pointer

Scroll lock

Locks the section of the page displayed in place. Even if another participant scrolls the page, what is displayed on the screen of whoever activated scroll lock will remain the same.

The controls for these three tools are grouped together. In the Agent Desk, they are in the collaboration layer’s action bar. For visitors, they are located in the collaboration layer controls at the top of the collaboration space.

9.2.6.1. Enabling collaboration tools

Not all tools are available in all collaboration layers. If a tool is available in a particular collaboration layer, there will be a configuration property to enable it.

The configuration properties that enable collaboration tools are defined on conversations or conversation templates. This provides for fine-grained configuration possibilities. You might, for example, decide that relationship managers should be granted full control of the collaboration layer in conversations with their clients. In conversations between support agents and visitors, on the other hand, agents should only be allowed to mark sections of the layer.

As a rule, you can specify which categories of participant may enable a tool.

In addition to enabling collaboration tools, you can define whether using the tools requires the explicit approval of the visitor or agent (depending on the tool).

For more information on configuring collaboration tools, and indeed other aspects of collaboration layers, please read our article Configuring and manipulating collaboration layers.

9.3. Conversation and participation life cycles

Each conversation goes through a number of different states which determine what can or must occur within the conversation for it to proceed. The state of a user’s participation in a conversation goes through a similar (but not identical) series of changes. These series of transitions from one state to the next are referred to as the conversation life cycle and participation life cycle, respectively.

9.3.1. The conversation life cycle

The conversation life cycle is a simple series of transitions from one state to the next. It is influenced by the participation states of the users taking part in the conversation as well as the engagement type of the conversation. The latter determines which conversation template is used when creating the conversation. This in turn determines which transitions are possible and/or necessary in the conversation’s life cycle. The following diagram shows all of the possible conversation states and the order of transition.

conversation life cycle
Figure 21. The conversation life cycle

A conversation need not necessarily go through all of the states in the diagram above. If a visitor declines the Terms and Conditions, for example, the conversation state will change from ONBOARDING to ENDED. Other states, such as UNASSIGNED, are only used in certain configurations.

9.3.1.1. Conversation states

The conversation states specify the overall state of a conversation.

Created

This is the initial state of a conversation, regardless of whether it was a visitor or an agent who started the conversation. Whoever started the conversation automatically joins the conversation as the context person (visitor) or assigned agent, respectively.

Onboarding

While the central person of the conversation is completing the onboarding process, the conversation is in the ONBOARDING state.

During the onboarding process, the participant can only see dialog messages exchanged with the bot or bots involved in the onboarding process. Once they have completed the process, they will see any messages sent to the conversation in the meantime.

The central person of a conversation need not be the person who initiated the conversation; see Engagement types for more details.

In many cases, the onboarding process needs visitor input to be completed. If, however, the onboarding process you put in place doesn’t require any action by the visitor, Unblu will complete the onboarding process without waiting for the visitor to open the conversation. This will be the case if, for example, you aren’t using the concierge or any other dialog bots at all, or if the concierge merely displays a message.

If you use an external dialog bot, Unblu doesn’t know whether the visitor will have to answer any questions, so it always waits for the visitor to open the conversation.

Unblu completing the onboarding process without waiting for the visitor to open the conversation is referred to as fast onboarding. Fast onboarding is not a way of speeding up the onboarding process.

Queued

If the conversation was initiated by a visitor, the conversation’s state will change from ONBOARDING to QUEUED once the central person has completed the onboarding process. A conversation may also be assigned this state by calling the web API endpoint /invitations/requeueConversation on it to move it to the queue.

The conversation remains in this state until an agent joins the conversation.

Active

A conversation is ACTIVE once two primary participants have joined the conversation (if the conversation was initiated by a visitor) or once the central person has completed onboarding (if the conversation was initiated by an agent).

Unassigned

When the assigned agent leaves an ACTIVE conversation, the state of the conversation changes to UNASSIGNED. If the visitor remaining in the conversation as a participant wishes to resume the conversation, they can simply send a message to start the reboarding process.

Whether it is possible for a visitor to stay in a conversation after the assigned agent has left depends on how the conversation or its template is configured. Only conversations originally initiated by visitors can be UNASSIGNED. All other conversations are ended when the assigned agent leaves.

See the list of engagement types for further information.

Reboarding

When a message is sent to a conversation whose state is UNASSIGNED, the conversation’s state is set to REBOARDING until the central person has completed the reboarding process.

During the reboarding process, the participant can see

  • Messages that were sent to the conversation before the reboarding process started,

  • Dialog messages exchanged with the bot or bots involved in the reboarding process, and

  • Dialog messages from earlier onboarding or reboarding processes.

Once the reboarding process is completed, the conversation will be placed in the queue again for an agent to accept. The participant will also see any messages sent to the conversation during their reboarding. If the process is canceled, the conversation state reverts to UNASSIGNED.

Offboarding

When an active conversation is ended, its state changes to OFFBOARDING and remains in this state while the participants complete their respective conversation offboarding processes.

During the offboarding process, the participant can see

  • Messages that were sent to the conversation before the offboarding process started,

  • Dialog messages exchanged with the bot or bots involved in the offboarding process, and

  • Dialog messages from earlier onboarding or reboarding processes.

Ended

When the offboarding process has been completed for each participant, either by the participants themselves or due to timing out, the conversation’s state changes to ENDED. The participants that didn’t leave the conversation remain active participants of the conversation. This enables them to view the details of the ended conversation at a later point in time.

9.3.1.2. Starting a conversation

When a visitor wants to start a conversation, they generally either click on a button in the visitor UI or trigger the execution of code you wrote that uses one of the Unblu JS APIs. Both of these actions attempt to start a conversation with a certain engagement type. For example, you may have added a link to your organization’s e-banking that allows users to request an embedded co-browsing session with a support agent. When a user clicks on the link, you call UnbluAPI.startConversation() with the type DOMCAP_BROWSER_REQUEST.

The configuration property com.unblu.messenger.startWithOfflineChatOptionEnabled gives you the possibility to let visitors start a conversation even though there are no agents available to deal with their request. This engagement type is called an offline chat request. All other engagement types are online requests.

The evaluation procedures for online and offline requests differ.

In the case of offline chat requests, the visitor’s client sends the offline chat request to the Unblu server. The server then carries out the following checks:

  1. Is there an agent available to deal with the request?

If you’re using version 3 of the Unblu Mobile SDK with Unblu 7, and you want visitors to be able to start conversations even though no agents are available, set the configuration property com.unblu.messenger.ignoreAgentAvailabilityForOnlineRequest to true.

For online requests, the evaluation procedure looks like this:

  1. The visitor’s client checks whether an agent is available to handle the request.

    • If an agent is available, the client sends the chat request to the Unblu server.

    • If no agent is available, the client throws an error and displays a message explaining the situation.

  2. Upon receiving a chat request, the Unblu server also checks whether an agent is available.

    • If there is an agent available, the server adds the request to the queue.

    • If no agent is available, it raises an exception and returns it to the visitor’s client.

If you use the Unblu visitor JS API to create conversation requests from the visitor side, you should therefore always check that an agent is available before you transmit your conversation request. If no agent is available, only send requests with the conversation type OFFLINE_CHAT_REQUEST.

9.3.1.3. Leaving vs ending a conversation

When a participant leaves a conversation, they no longer have access to the conversation: they cannot view it in their conversation history, nor can they rejoin it. If they wish to rejoin the conversation, they will need a new invitation. The conversation has not necessarily ended, though.

When a conversation has ended, on the other hand, participants who didn’t leave the conversation remain active participants in the conversation and continue to have access to it in their conversation history. Although an ended conversation has active participants, it is not possible to send new messages to an ended conversation or to invite people to join it. A conversation that has ended is in a state that can no longer change.

You can specify that a conversation be ended when participants leave a conversation with the configuration property com.unblu.conversation.lifecycle.autoEndOnLeave. It is also possible to configure Unblu so that participants automatically leave or end a conversation when they disconnect. The relevant configuration properties are

9.3.1.3.1. Closing a conversation

When we say a user has closed a conversation, we mean that they have navigated away from a conversation, e.g. by closing the browser tab the conversation was taking place in. Closing a conversation doesn’t affect the conversation state. However, it is possible to configure Unblu so that participants automatically leave or end a conversation when they disconnect.

If you want the UI to close automatically when a conversation has ended, you can set it to do so for different participants with the following configuration properties:

The setting will not have an effect if a visitor’s participation in a conversation is ended by the system, e.g. because they declined the terms and conditions during onboarding. In such cases, you cannot close the UI automatically.

9.3.2. The participation life cycle

The participation life cycle describes how the state of a user in relation to a conversation changes in the course of that conversation.

9.3.2.1. Participation states
Created

The participant has been created.

Onboarding

The participant is completing the onboarding process for the conversation. During the onboarding process, the participant can only see messages that are part of the onboarding process.

Active

The participant has joined the conversation and is an active member. If the participant doesn’t leave the conversation, their participation in the conversation will remain active even after the conversation has ended. See Leaving vs ending a conversation for more information.

Offboarding

The participant is completing the offboarding process to leave the conversation.

A participant’s state only changes to OFFBOARDING if they leave the conversation. If they remain in a conversation until it ends, they will be required to complete the conversation offboarding process, but their participation state will remain ACTIVE.
Ended

The participant is no longer present in the conversation and no longer has access to it.

9.4. Concierge

9.4.1. Overview

The Unblu concierge is a bot that can be configured to automate three common interactions that occur during a typical conversation: onboarding, reboarding and offboarding.

For example, it can ask visitors to answers preliminary questions such as

  • "What is your name?"

  • "What is your email address?"

  • "Do you accept the terms and conditions?"

This is all done before an agent actually joins the conversation.

This helps the agents by automating the asking of repetitive questions and can provide valuable information for sorting the incoming chat requests. At the end of the conversation the concierge can ask about the experience and relay additional information to the visitor.

The flow of messages written and question asked by the concierge can be configured by choosing among a large set of possible predefined actions and by defining conditions as to when specific actions are performed. For example, depending on the situation (start of a conversation, ejection of visitor from conversation, reboard visitor after agent left, conversation is ended, visitor did not successfully finished the onboarding, etc.) the type and order of the messages sent can be defined. This can be different depending on the type of engagement (chat request, pin based conversation, …​) and depending on the page where the visitor is (named area).

The possibilities during onboarding are:

  • Greet & several other customizable text messages

  • Ask for name

  • Ask for terms and conditions

  • Determine the for recipient of the conversation by asking between a multiple answers question

  • Ask for email to send notifications

The possibilities during reboarding are:

  • Ask the visitor if they want to chat with an agent again. The visitor then has the option to

    • Accept: the conversation will be put into the queue again and an agent can pick it up

    • Decline: the conversation will stay unassigned

The possibilities during offboarding are:

  • Give reason for offboarding (info message)

  • Several customizable text messages

  • Rate conversation

  • Ask to send log via email

10. Glossary

Account

A collection of users, teams, named areas, conversation templates, configuration properties and the like. The account is the main entity to separate several tenants—​your organization’s various country subsidiaries, for example—​on the same Unblu installation.

It’s important to bear in mind that, in Unblu, the term "account" doesn’t refer to a user. Rather, a user belongs to an account.

Account ingress

The method by which Unblu routes HTTP requests to different accounts before it has authenticated the requests, based on using distinct host names and/or subdomains.

Admin

A role that grants users access to the account configuration interface and allows them to configure settings at the account level.

Administrator

See Admin.

Agent

A registered user of the Unblu Agent Desk, usually a representative of the organization that offers collaboration services on their website.

Anyone in your organization who uses Unblu to engage with your customers—​call center employees, client advisors, relationship managers, support desk agents and so on—​is referred to as an "agent" in Unblu.

Agent Desk

The web-based interface for users to conduct and manage conversations, calls, and collaboration sessions.

API key

A code passed by websites instrumented with the Unblu snippet to identify themselves. The API key acts as a unique identifier and has a set of access rights and configuration properties associated with it.

API keys are commonly used to provide different configurations for Unblu in mobile and desktop web applications, or on different websites that belong to the same organization.

Avatar

A graphical representation of an entity such as a user, person, team, account, or named area.

Canned response

A canned response is a predefined text snippet that agents can use in chat messages. They help reduce the amount of typing agents have to do for frequently used messages and ensure recurring texts are error-free. Canned responses can also be used to improve the consistency of your organization’s communication with its customers.

See the section on canned responses in the Agent Desk guide for an in-depth introduction.

Collaboration layer

The means by which conversation participants can view the contents of a website, a mobile app, or a document together.

For more information, see the knowledge base article Collaboration layers.

Configuration cascade

The mechanism by which entities inherit the values of configuration properties from other entities. The configuration cascade is defined by Unblu and can’t be changed.

Configuration property

A property or setting defined on an entity which specifies a facet of the entity’s behavior.

Conversation

A channel to enable communication between two or more persons.

Conversations are highly flexible. The mode of communication isn’t fixed for a conversation, nor is its duration. The persons participating in a conversation can also change.

Conversation presence

A person’s active connection to a conversation. A person may have multiple concurrent presences in a conversation, for example if they’re participating in a conversation with both their mobile phone and a web browser.

Conversation template

A collection of configuration and text properties applied to a conversation when it’s created. Which conversation template is applied to a new conversation depends on a number of factors:

  • For conversations started by agents or via the Unblu web API, you can specify which conversation template to use.

  • The conversation template used for conversations initiated by visitors is determined based on the engagement type and the account, API key, or named area that the visitor’s request originated from.

Cross-origin setup

An Unblu installation exposing the Unblu server and your company website to the Internet separately. For example, your website may be accessible via https://www.mycompany.com, but your visitors access Unblu via https://unblu.mycompany.com/.

This type of setup is common in Unblu Cloud deployments but can also be used in on-premises installations.

Deputy

A deputy is an agent or a team that’s notified when another agent receives a personal conversation request and doesn’t respond to it.

For more information, see Deputy delegation.

Document co-browsing

A collaboration layer that allows conversation participants to view PDF files and other kinds of files together. Participants all see the same copy of the document, so when completing a PDF form, for example, all participants can see what’s entered in the form as it happens.

DOM capturing

A technique used in embedded co-browsing to transfer the state of a visitor’s view of a website to an agent.

Domain

A distinct subset of the internet with addresses sharing a common suffix or under the control of a particular organization or individual.

Embedded co-browsing

A collaboration layer that uses DOM capturing to allow visitors to share their view of an Unblu-enabled website with other conversation participants.

Embedded visitor UI

The version of the visitor UI that you can embed in a website or single page application (SPA) using the custom HTML element <unblu-embedded-app>. The embedded visitor UI is particularly suited to contexts where the focus is on messaging.

Engagement type

The set of criteria used to determine which type of conversation to launch. The criteria are:

  • The person type of the person who initiates the conversation: "agent" or "visitor".

  • The person type of the person that the conversation is centered around: again, either agent or visitor.

  • The type of media initially used in the conversation.

  • Whether the conversation is initiated in a standard Unblu UI or via the API.

Entry path

The part of the URL that an HTTP request is sent to which determines the level of trust required to access the resource at the endpoint accessed via the URL.

Review the article on entry paths for further details.

Floating visitor UI

The version of the visitor UI that can be integrated in a website without a custom HTML element.

The floating visitor UI takes up less of the screen than the embedded visitor UI and is therefore better suited to providing in-context assistance.

Ghost

A ghost or ghost participant is a user viewing a conversation without actually participating in it. The other participants in the conversation can’t tell that a ghost is accessing a conversation unless the ghost executes an action that the other participants are informed of.

ID propagation

The replication of a user’s identity from a system outside Unblu. Authentication, where required, is also handled by the external system.

For more information, read the relevant section of the article on authentication.

Inheritance

The method by which configuration properties are transferred to entities further down the configuration cascade.

Launcher button

The button displayed on an Unblu-enabled website to open the floating or embedded visitor UI.

Named area

A means of grouping parts of your website. You can then specify that Unblu should behave differently for different groupings.

A named area may be defined using either domains and subdomains registered in Unblu, or with an ID that you then add, in a meta tag, to the pages you wish to include in the named area.

Offboarding

The process a person must complete to leave a conversation. The steps in the process are configurable and may differ for agents and visitors.

Onboarding

The process a person must complete to join a conversation. The steps in the process are configurable and may differ for agents and visitors.

Participant

A user who has or had a participation in a conversation.

Participation

The time that a person is actively taking part in a conversation.

Person

The representation of a user in conversations. The user’s details, such as their name, are copied to the person. Changes made to the user’s details are reflected in the person that represents it.

Users who joined a conversation at some point in the past are represented by persons in the conversation. This is the case even if they aren’t currently present in a conversation, for example because they closed the browser tab with the conversation. When they open the conversation again, they’re represented by the same person.

Decoupling the representation of users in conversations from the users themselves allows for persistent conversations to be displayed with information about their participants even after a user has been deleted from Unblu.

PIN

A temporary identifier, typically consisting of several digits. The agent usually provides the visitor with the PIN over the phone. The visitor then enters the PIN to join the conversation.

Queue

An ordered list of conversations that an agent may join.

The conversations in an agent’s queue depend on the filters the agent has defined for their queue. Suppose an agent is able to join conversations from two different named areas, but their queue is filtered to display only conversations from one of these named areas. In that case, the queue will only include conversations from one named area, and the agent will only be able to join these conversations.

Reboarding

The process a visitor must complete to resume an unassigned conversation.

Review the documentation on the conversation and participation life cycle for information on the cases where reboarding is possible.

Rendering service

An application based on a Chromium browser running in headless mode.

The rendering service runs in a Docker container as part of an Unblu installation. It’s required for document co-browsing and universal co-browsing.

Resource history

Contents of the web page displayed in a visitor’s browser during an embedded co-browsing session that are transferred to the Unblu server so that agents have the same view of the page. The contents transferred to the resource history typically include resources such as images and CSS files.

See the article on the technical details of the resource history for further information.

Role

A means of classifying users. The purpose of a role is to define which users may access which features of Unblu.

See the dedicated article on user roles for more details.

Scope

The scope of a configuration property describes the set of entities the property may affect, depending on the level within the configuration cascade that the value of the configuration property is specified.

Read the article entitled Configuration property scope and the configuration cascade for further information.

SecureFlow Manager

The component of an Unblu installation that makes protected resources available for embedded co-browsing sessions via the resource history. The SecureFlow Manager can also be used to inject the Unblu JavaScript snippet when it’s required.

For more information, see SecureFlow Manager.

Session

The connection between the conversation presences of the participants in a conversation and the conversation in question. A session is started automatically once a person has established a presence in a conversation. When no participant has a presence in the conversation anymore, the session ends automatically.

Settings

Single Conversation Desk

A variety of the Agent Desk without the navigation sidebar.

The Single Conversation Desk is commonly used to give agents access to a single conversation from another system, such as a call center solution or a CRM application.

Site-embedded setup

An on-premises installation that exposes the Unblu server and you organization’s website via a proxy. For example, your company website may be accessible via https://www.mycompany.com, and your Unblu installation is accessible via https://www.mycompany.com/unblu.

See also Cross-origin setup.

Subteam

See Team.

Superadmin

A role that grants users the authorization to configure settings at the account and server (or "global") level.

Superadministrator

See Superadmin.

Supervisor

A role that grants users the authorization to manage some aspects of an account, such as certain teams and their members.

If a supervisor manages a team with subteams, they can manage those subteams and their members, too.

Team

Teams are groups of users and subteams. A subteam is simply a team within another team.

Teams allow you to change settings and apply the changes to multiple users. Configuration settings applied to a team are inherited by the team’s users and its subteams.

Teams don’t intersect: a user can only be a member of a single team. If a user is a member of a subteam, they aren’t members of the parent team as well.

Text property

A setting containing text used in one of the Unblu UIs. Many text properties can be adapted to your organization’s needs and localized.

Unblu Cloud

The Unblu Cloud is Unblu’s cloud service.

Universal co-browsing

A collaboration layer that allows persons to view a website together that hasn’t been instrumented with Unblu. Universal co-browsing requires the rendering service.

For more information, see Universal co-browsing and Rendering service.

User

The entity used to store information about someone who can use Unblu, such as their name and email address, in the Unblu server.

Agents, supervisors, admins, and superadministrators are all represented as users in Unblu.

What a user can do in Unblu is determined by their role.

Users may be created in Unblu or propagated from an external source such as an identity management system. For more information, see User modes.

In conversations, users are represented by person entities.

Virtual user

A user identity propagated to Unblu by another system. Unblu doesn’t have any local information about that user in its built-in user directory. Rather, it trusts the system that propagated the user’s identity.

Visitor

A person using Unblu to get assistance, support, or advice. Usually a customer of the company that offers collaboration services on their web site.

Visitor Desk

The visitor-side equivalent to the Single Conversation Desk.

The Visitor Desk gives visitors access to a single conversation without the navigational possibilities of the embedded and floating visitor UIs.

Web user

A visitor using Unblu after being authenticated by a protected web application such as an e-banking portal.