Labels and visibility rules

Creating and managing labels

You can create and manage labels in the Account Configuration interface or through the web API. Refer to the Labels section of the Account Configuration interface guide and the PersonLabels section of the web API reference for more information.

Every label has the following properties:

The label’s name
An optional description
The color of the label
Who the label can be assigned to. This is determined by the role of the person in question: Agent, authenticated visitor, anonymous visitor, or bot.

The final three properties of a label are related to accessing labels. These properties are also determined by the role of the person in question. In this case, however, the roles are supervisor, agent, authenticated visitor, or anonymous visitor.

Who can read the label through the web API (readableByRoles).
Who can set the label on a person (settableByRoles). This property depends on the ability to read the label through the web API. Whoever can set the label is automatically allowed to read it as well.
Who can see the label in the Unblu UIs (displayedToRoles). This property also depends on the ability to read the label through the web API. If someone can’t read the label through the web API, it isn’t displayed to them in the Unblu UIs either.

At present, there’s no way to display labels to visitors in the Unblu UIs.

If you don’t check any options for a property, only users with the ADMIN`or `SUPER_ADMIN role are granted the ability in question.

Scoped labels

Sometimes you want to ensure that a person is only assigned one of a group of labels. For example, you might have labels that indicate which customer segment a client belongs to, such as "retail banking", "private banking", and "HNWI". Usually, customer segments don’t overlap, so you only ever want to assign a visitor one such label.

Scoped labels allow you to create sets of mutually exclusive labels. The name of a scoped label has two parts:

The scope name. This part of the name is shared between mutually exclusive labels.
The scope value for a particular label.

In the Account Configuration interface, activating the Scoped label switch at the top of the page replaces the Name field with the Scope name and Scope value fields. When you click Save, the label is created as a scoped label.

If you’re using the web API to create or edit labels, you create a scoped label by providing a value that has the format <scope_name>::<scope_value> in the name field of the PersonLabel entity. Note that the scope name and scope value are separated by two colons.

You can’t convert labels to scoped labels or vice versa.

Setting and removing labels

Users can set labels in different ways:

In the Unblu UIs
Through the web API
Through the JS APIs and the mobile SDKs

All the methods outlined in the sections below are subject to the labels' properties granting the person in question the necessary permissions.

Setting and removing labels in the Unblu UIs

For users to be able to set or remove a label in the Unblu UIs, their role must be included in the label’s settableByRoles and displayedToRoles properties.

Account Configuration interface

Admins and supervisors with access to the Account Configuration interface can manage labels in the Labels section. They can also assign labels to existing users in the Users section.

It isn’t possible to assign labels when you’re creating a new user. You must save new users before you can assign them labels.

Agent Desk

In the Agent Desk, users can review and change the labels assigned to themselves in their profile.

In conversations, users can view and edit the labels of conversation participants. To do so, they can click the participant’s avatar, then click More information to open the participant fly-in page with the participant’s details. Alternatively, they can open the Participants fly-in page, then click the participant whose labels they wish to view or edit.

Visitor UIs

There are no visitor UIs where it’s possible to set or remove labels.

Setting and removing labels through the web API, the JS APIs, and the mobile SDKs

The Unblu web API provides the endpoints /persons/{personId}/setLabels, /persons/{personId}/addLabels, and /persons/{personId}/removeLabels to assign and remove labels from persons.
The UnbluApi class of the Floating JS API provides the methods addPersonLabel and removePersonLabel. The Embedded JS API provides analogous methods.
The iOS and Android mobile SDKs provide methods to add and remove labels. For more information, refer to the Android and iOS reference documentation.

Visibility rules

Visibility rules build on the labels you assign to persons. They use labels to define which agents may interact with which visitors.

Visibility rules affect who an agent can initiate outbound conversations with and which conversations that they aren’t participating in they have access to. They also determine which built-in actions an agent may trigger on a visitor, for example, whether they can change the visitor’s nickname.

How visibility rules work

Visibility rules use the labels set on agents and visitors to determine whether an agent can interact with a visitor. A visibility rule specifies which set of labels an agent must have to see a visitor who, in turn, has a specific set of labels. Both sets of labels, that of the agent and that of the visitor, can be one of the following:

No labels: The agent or visitor has zero labels.
Any label: The agent or visitor has zero or more labels.
A set of specific labels: The agent or visitor has all of the labels in the set. Note that this doesn’t mean they may have only the labels in the set.

All visibility rules that apply to an agent are applied cumulatively. This allows you to create multiple rules that are relatively restrictive individually, but grant access to a wide range of visitors when combined.

When an agent tries to launch an outbound conversation, only visitors that are visible to them are available as potential counterparts in the conversation.

Visibility rules don’t just apply in the Unblu UIs. They’re also applied in the Unblu web API, for example, in the endpoints to search for persons.

Visibility rule examples

The background information from the previous section is important, but how visibility rules work in practice is easiest to understand if you look at some examples.

Consider the following agents and visitors and the labels they’ve been assigned:

Table 1. Agents and visitors with their labels
		Labels
		`L1`	`L2`	`L3`	`L4`
Agents	Alice	X			X
Agents	Bob
Visitors	Carol	X
	Dave		X	X
	Susan

Below are several visibility rules along with explanations of who Alice and Bob can see. The explanations assume that the visibility rule they refer to are the only rule that’s enabled.

Rule 1: If agents have no labels, they can see visitors with any label.

With this rule, Bob can see Carol, Dave, and Susan. He can see Susan because any label means zero or more labels.

Alice can’t see any visitors.
Rule 2: If agents have any label, they can see visitors with no labels.

With this rule, Alice can see Susan but neither Carol nor David. Bob can see Susan, too, because any label means zero or more labels.
Rule 3: If agents have all of a set of specific labels (in this case, L1), they can see visitors with all of a set of specific labels (in this case, L3)

With this rule, Alice can see Dave, but neither Carol nor Susan. The fact that Dave has the label L2 is irrelevant for this rule.

The rule doesn’t apply to Bob, because he doesn’t have the label L1.
Rule 4: If agents have any label, they can see visitors with all of a set of specific labels (in this case, L1).

With this rule, Alice and Bob can both see Carol, but neither Dave nor Susan.

Individually, visibility rules can be quite restrictive. Rules 2, 3, and 4 above, for example, each only give Alice access to one visitor. However, if you enabled all three of the rules, Alice would be able to see all three visitors, because visibility rules are applied to agents cumulatively.

Visibility rules and conversation visibility

By default, conversations are private, that is, they’re only visible to participants and the assigned agent's supervisor.

Visibility rules don’t apply to private conversations. They only apply to conversations with rule-based visibility.

Rule-based conversations are visible to participants and to non-participating agents who can see the conversation’s context person based on their visibility rules.

Whether a conversation’s visibility is private or rule-based depends on the conversation template it was created from (or the value the template’s visibility was overridden with). The conversation visibility is a defining characteristic of each conversation template. You specify it when you create the template. For more information, refer to the description of creating a new conversation template in the Account Configuration interface guide and the /conversationtemplates/create endpoint in the web API reference.

You can also specify a conversation’s visibility directly when you create it through the `/conversations/create endpoint.

For more information on conversation visibility, refer to Configuring conversation visibility.

Conversation visibility example

The examples below should give you a better idea of how conversation visibility works in practice. They use the same agents, visitors, and rules as the examples above. In each example, the conversation visibility is rule-based.

Alice is the assigned agent, Dave is the context person, and Carol is a secondary visitor. Only Rule 4 is enabled.

In this case, Bob can’t see the conversation because Rule 4 doesn’t allow him to see Dave. It doesn’t matter that Rule 4 allows him to see Carol, who’s also a participant, because she isn’t the context person in the conversation.
Bob is the assigned agent, Dave is the context person, Susan is a secondary visitor. Rules 3 and 4 are enabled.

Alice can see the conversation (in her conversation history, for example), because Rule 3 allows her to see Dave. The fact that Rule 4 doesn’t allow her to see him is irrelevant because visibility rules are applied cumulatively.
Alice is the assigned agent, Carol is the context person. Only Rule 1 is enabled.

You might be surprised that Alice is conducting a conversation with Carol, whom she can’t see according to the visibility rule. This isn’t a contradiction. Visibility rules don’t apply everywhere. They don’t affect the conversations that agents see in their queue, for example.

Bob can see the conversation because Rule 1 allows him to see Carol.

Creating and managing visibility rules

You can create and manage visibility rules in the Account Configuration interface. For more information, refer to the Labels and Visibility rules sections of the Account Configuration interface guide.

You can also use the Unblu web API endpoints of the PersonVisibilityRules service to create and manage visibility rules. For more information, refer to the web API reference.