Contact usRequest a demo

UI customization guide

This article discusses various ways you can customize the behavior of the Agent Desk and the Floating Visitor UI to suit the needs of your organization. It explains how the configuration of various options affect the way the user interface appears to users.

For information on customizing the appearance of the UIs, refer to UI theming cheat sheet.

Numerous aspects of the user interfaces change depending on how you configure Unblu. In the Agent Desk, this includes:

  • The sidebar menu

  • The user menu

  • The plus icon menu Plus icon in the top bar

  • The layer action bar displayed in collaboration layers

  • Various elements in the agent conversation bar below the top bar:

    • The Forward button

    • The Invite button

    • The conversation configuration button

    • The Collaborate menu

Some elements of the user interfaces that change are present in both the Agent Desk and the Floating Visitor UI:

  • The engagement UI

  • The collaboration layer controls

  • The message view or chat panel, which includes

    • The action bar

    • The list of messages

    • The message input field

The common elements will only be discussed in the section on the Floating Visitor UI and collaboration space.

Customizing the Agent Desk

The image below shows the various parts of the Agent Desk you can customize:

The Agent Desk with various parts numbered
Figure 1. The Agent Desk with various parts numbered

The numbered parts of the Agent Desk are:

How your configuration affects each of these parts will be discussed in turn.

By default, the left navigation sidebar is collapsed:

The Agent Desk sidebar
Figure 2. The Agent Desk sidebar

To expand the sidebar, click the Toggle navigation bar button Toggle navigation bar button:

The expanded Agent Desk sidebar
Figure 3. The expanded Agent Desk sidebar

The menu in the sidebar consists of at most five entries, each providing access to a different view:

Queue

The Queue entry in the sidebar menu is displayed if com.unblu.desk.ui.showQueue is true. When selected, it opens the queue view.

The requests in the queue are displayed in the order they were added to the queue, with the oldest request at the top. You can highlight that requests have been waiting more than a certain period by setting a warning and a danger threshold with the configuration properties com.unblu.queue.ui.warningTimeThresholdSeconds and com.unblu.queue.ui.dangerTimeThresholdSeconds, respectively.

Configuring the queue is discussed in depth in a separate article, Queue and request dispatching configuration. The article also points out how your configuration affects the queue in the Agent Desk.

Inbox

The Inbox menu entry is displayed if com.unblu.desk.ui.showInbox is true. When selected, it opens the inbox with the user’s ongoing conversations.

Depending on how Unblu is configured, the conversations may be grouped in three tabs, My Conversations, Secondary Conversations, and Forwarded. This makes it easier for agents to distinguish between conversations where they’re the assigned agent, ones where they’re only secondary agents, and conversations that they have forwarded to another agent.

Inbox with separate tabs for secondary conversations and forwarded conversations
Figure 4. Inbox with separate tabs for secondary conversations and forwarded conversations

You can configure Unblu to display all conversations in a single list by setting the configuration property com.unblu.agent.inbox.ui.displayOwnAndSecondaryConversationsInTabs to false. The inbox then looks like this:

Inbox with all conversations shown in a single list
Figure 5. Inbox with all conversations shown in a single list

Conversations in the inbox are listed in order of the time of the last message sent to the conversation. You can choose to list conversations in ascending or descending order with the configuration property com.unblu.core.client.agent.inbox.InboxUiConfig. By default, they’re listed in descending order.

Forwarded tab

Forwarded conversations are listed in the Forwarded tab. This tab is displayed by default and depends on the property com.unblu.agent.inbox.ui.displayForwardedConversationsInTabs.

You can open the tab using a keyboard shortcut defined in com.unblu.agent.inbox.shortcuts.openInboxForwardedShortcut. The default shortcut is Alt+Shift+f.

You can configure the text displayed in the tab using the following text properties:

  • com.unblu.agent.inbox.ui.tabTitleForwardedConversations: Forwarded tab label.

  • com.unblu.core.client.agent.inbox.AgentConversationListItemView.forwardedRecipient: The text displayed for the recipient in case of forwarding.

  • com.unblu.agent.inbox.shortcuts.openInboxForwardedTitle: Label for the shortcut.

  • com.unblu.agent.inbox.ui.emptyForwardedInboxLabel: Text displayed when there are no forwarded conversations.

When another agent answers the forwarded request, the original assigned agent’s participation in the conversation ends automatically and the conversation is no longer listed in their Forwarded tab.

When you open a forwarded conversation, a banner indicating that it’s forwarded is displayed at the top of the conversation. You can revoke a forwarding from the banner. You can also directly forward the conversation again. This has the effect of revoking the original forwarding and forwarding the conversation again.

You can configure the text in the banner using the following text properties:

  • com.unblu.conversation.forward.banner.bannerTitle: Title of the forwarding banner.

  • com.unblu.conversation.forward.banner.bannerText: Text displayed in the banner to describe the forwarding.

  • com.unblu.conversation.forward.banner.revokeButton: Button to revoke the pending forwarding.

Group avatar

On each conversation in the various lists of conversations in the inbox, Unblu displays the context person's avatar. This can be confusing if there are several participants in a conversation.

If you’d rather display a neutral group avatar when there are more than two participants in a conversation, enable the configuration property com.unblu.conversation.ui.enableGroupConversationAvatar. When you do, Unblu displays an avatar with the user group icon User group icon. The same avatar is used in conversation tab in the Agent Desk top bar and the conversation list in the Visitor UIs.

When the agent hovers over the avatar, Unblu displays a tooltip telling them how many other participants are in the conversation. To customize the tooltip, edit the text property com.unblu.conversation.ui.groupConversationAvatarTooltip.

Conversation history

The Conversation history menu entry is displayed if com.unblu.desk.ui.showConversationHistory is true.

The only configurable option in the conversation history is the number of conversations that it should show. Set com.unblu.conversationhistory.limit to the maximum number of conversations to display in the conversation history.

There is no pagination in the conversation history. If more conversations match the criteria specified in the filter, Unblu will simply display a message to this effect. You can then adapt your search criteria to further limit the number of search results.

Agent monitor

The Agent monitor entry in the sidebar menu is displayed if config: com.unblu.desk.ui.showAgentAvailabilityMonitor[] is true and the user who is logged in has at least the user role SUPERVISOR.

The top bar

The top bar holds the plus menu Plus menu icon and the tabs of open conversations.

The Agent Desk top bar
Figure 6. The Agent Desk top bar

There are two configurable elements in the top bar: the plus menu and the avatar displayed on conversation tabs. How you can configure the avatar is explained in the Group avatar section above. The plus menu provides a way for agents to launch conversations with various engagement types.

The plus icon menu
Figure 7. The plus icon menu

The content of the menu depends on the types of conversation that are enabled for the Unblu account in question.

You can only enable collaboration layers for which you have a valid license.

To add a template for a particular engagement type to the plus menu, you must add it to the configuration property com.unblu.conversation.template.newConversationTemplateIds. It’s possible to add multiple templates for the same engagement type to the plus menu.

If the configuration property is empty, or if none of Unblu’s collaboration layers are enabled, the plus menu isn’t visible in the Agent Desk.

Initial plus menu entries

When you first create an Unblu account, the plus menu lists all the conversation templates for the various conversation types. The exception is templates for the engagement type Chat invite, which are only included if com.unblu.agent.conversationtemplate.allowStartChatInviteConversations is set or the template in question has com.unblu.conversation.outbound.enableOutboundConversation set to true.

If you change the value of com.unblu.conversation.template.newConversationTemplateIds, however, and then uncheck all the options, Unblu doesn’t revert to default conversations templates. Instead the plus menu is empty, so it isn’t displayed.

The user menu

The user menu is available if com.unblu.ui.usermenu.userMenuEnabled is true.

The Agent Desk user menu
Figure 8. The Agent Desk user menu

The following configuration properties are available to customize the menu’s appearance:

The agent conversation bar

The agent conversation bar is located beneath the top bar and is displayed when a conversation tab is open. Its contents depend on the type of conversation currently open, and it is configured via the conversation template for the type of conversation in question.

The agent conversation bar
Figure 9. The agent conversation bar

The UI elements the agent conversation bar may contain are:

The Forward button

The Forward button can be used by authorized users to forward the current conversation to a different agent, a team, or a named area. Which participants may forward conversations to whom is determined by three configuration properties:

The participation role of the person logged in to the Agent Desk determines the content of the forward button menu.

  • If the user is authorized to forward the conversation to two or more types of entity, clicking the icon will open a menu, and the user can choose which type of entity the conversation they want to forward the conversation to.

  • If the user is only authorized to forward the conversation to one type of entity, clicking the icon will open the fly-in page where they can select the recipient of the conversation.

  • The Forward button is not displayed if the user is not authorized to forward the conversation.

The Invite button

The Invite button works similarly to the Forward button. It allows authorized users to invite agents, teams, or visitors to join the current conversation.

Which participants may invite which types of participant to join a conversation is again specified in the following configuration properties:

The number of permissions the Agent Desk user has affects the behavior of the button in the same way as the Forward button.

  • If the user is authorized to invite two or more types of entity, clicking the button open a menu, and the user can choose which type of entity the conversation they want to invite.

  • If the user is only authorized to invite to one type of entity, clicking the button directly opens the fly-in page where they can send the invitation to the entity.

  • If the user isn’t authorized to invite anyone to join the conversation, the Invite button isn’t visible.

If public links are enabled for the conversation in question, the public link to the conversation is also displayed in the fly-in page.

The conversation configuration button

The conversation configuration button Configure conversation icon is present in the conversation action bar if the user logged in to the Agent Desk is an admin or superadmin. When clicked, it opens the settings of the conversation in question and allows the user to make changes to the settings of a single conversation, just as they would to those of a conversation template.

The Collaborate menu

The Collaborate menu is used to launch a new collaboration layer.

Agent Desk collaborate menu

Its content depends on the types of collaboration layer that can be launched within the context of the running conversation.

Only participant types listed in com.unblu.conversation.collaboration.showLayerControls will see the layer controls. Additionally, com.unblu.conversation.collaboration.action.displayInactiveLayers determines which types of participant see inactive collaboration layers in the menu.

Each conversation template can be configured individually to allow various types of collaboration:

You can only enable features for a conversation that have been enabled for the relevant Unblu account. If one of the configuration properties mentioned above isn’t available in the settings of the conversation template, check the corresponding account-level property:

Leave conversation and End conversation buttons

Setting com.unblu.conversation.ui.showLeaveInAgentControlBar to true adds a button to the conversation action bar that allows the participant to leave the conversation.

The Leave conversation button is only displayed if the Agent Desk user has a participation role in the conversation that’s allowed to leave a conversation. This is determined by com.unblu.conversation.lifecycle.allowLeave, which you can set in the conversation template. You can change the label of the button in the text property com.unblu.agent.conversation.ui.dialogButtonLeaveConversationLeave.

Without the button, authorized users can only leave conversations if you have set com.unblu.conversation.actionbar.ui.leaveConversationActionDisplayMode such that there is a possibility to leave the conversation displayed somewhere in the action bar.

If you’ve enabled the awaited person type, you can configure the dialog that’s displayed when a participant leaves the conversation. For more information, refer to Configuring the awaited person type.

The End conversation button is displayed for all a conversation’s participants allowed to end the conversation. Who may do so is specified in conversation template’s configuration property com.unblu.conversation.lifecycle.allowEnd. The label of the button is defined in com.unblu.agent.conversation.ui.btnEndConversation.

To show a confirmation dialog when a participant ends the conversation, include their participant type in com.unblu.conversation.ui.showEndConversationConfirmationDialog.

The action bar

The message view action bar in the Agent Desk offers numerous customization options. You can specify which features to display, and whether to display the features as an icon in the action bar or as an entry in the overflow menu represented by the kebab icon Action bar kebab menu.

The action bar in the Agent Desk message view
Figure 10. The action bar in the Agent Desk message view

The settings described below can be set in various scopes:

  • Globally, that is, for an entire Unblu Collaboraton Server deployment

  • For an Unblu account

  • For a named area

  • For a team

  • For individual users

  • For an API key

This offers you great flexibility.

Collaboration layers

You can specify the collaboration layers that conversation participants can switch to with the following configuration properties:

The collaboration layers users can launch are grouped in the Share action. The action is displayed if users are allowed to share at least one layer.

How the Share action appears in the UIs is determined by the following configuration properties:

Two configuration properties determine which layers users may start:

The display mode for conversation or custom actions is defined on the custom action, not through configuration properties.

There are similar configuration properties for all other predefined actions that can appear in the action bar.

The values the configuration properties listed above can take are:

always_in_overflow

The collaboration layer will only ever be listed in the overflow menu, not in the action bar.

always_show

The icon to switch to the collaboration layer will always appear in the action bar.

The action provides enough room for four icons on normal screens, and three icons on small screens and mobile devices. If you add more icons to the action bar, this may have an adverse effect on the UI.

hidden

Users won’t see the collaboration layer in the action bar or the overflow menu.

show_if_possible

The collaboration layer’s icon will appear in the action bar if there is enough room to display it there. If the action bar is full, the collaboration layer will be listed in the overflow menu.

The relevant feature must be enabled for the settings to have an effect; see the section on the collaborate menu above.

The sort order of predefined actions in the action bar is defined by configuration properties whose names follow the pattern com.unblu.conversation.actionbar.ui.<actionName>ActionSortOrder. The sort order of custom actions is defined on the custom actions themselves.

Which participants see the respective action’s icon in their action bar or an entry in the overflow menu depends on two more settings:

Launch calls

The possibility to launch calls is configured the same way as with collaboration layers:

Both options are only available if com.unblu.messenger.callEnabled is true.

Participant information popup

When you click a participant’s avatar in the action bar, a popup appears displaying various information about the participant.

The About section of the popup shows the following information:

  • The user’s approximate location. This information is determined based on the user’s IP address, which is compared to a table of IP address blocks and their location.

  • The user’s language. How Unblu determines a user’s language is described in detail in the article on setting the locale.

  • The operating system and browser the user’s running. If Unblu knows the version of the operating system and/or browser, this information will be included as well. If the version is unknown, Unblu will display the term Other.

    The operating system name displayed in the popup depends to an extent on the browser used. Thus someone using Google Chrome on Ubuntu is reported as running the operating system Linux Other. If they’re using Firefox, on the other hand, Unblu reports that the operating system is Ubuntu Other.
  • The user’s authentication status. If they haven’t been authenticated, the lock icon is open and has the label Unauthenticated.

    If the user’s authenticated identity has been propagated—​because they launched a chat from within e-banking, for example—​the lock icon is closed, and the popup shows their propagated user ID as well as their email address and phone number (if available).

The popup shows device-related information for each device the user is currently accessing the conversation with. This means that there can be multiple entries for both the operating system and browser as well as the language. Because of the method for determining a user’s location, there may even be multiple entries for their location.

By default, assigned agents, secondary agents, and ghost participants have access to the information listed above. To change which conversation participants have such access, modify the configuration property com.unblu.conversation.ui.showPersonDetails.

The popup that appears when you click a user’s avatar may include other buttons:

The Collaboration options section beneath the About section lists all the ongoing collaboration sessions in the conversation.

The Actions section beneath the Collaboration options section lists all predefined and custom actions that can be invoked on the user. The sort order of the predefined actions is defined with com.unblu.conversation.person.action.ui.changeParticipationVisibilityActionSortOrder and com.unblu.conversation.person.action.ui.changeAssigneeActionSortOrder. The sort order of custom actions is defined on the custom actions themselves.

Other actions

There are a number of other actions that can be added to the action bar or the overflow menu:

All the configuration properties listed above affect the action bar in both the Agent Desk and the Floating Visitor UI. One setting is only relevant in the Agent Desk, com.unblu.conversation.actionbar.ui.changeVisibilityActionDisplayMode. It provides secondary agents with a means to change their visibility to other participants in a conversation. The setting only has an effect if com.unblu.conversation.lifecycle.allowSecondaryAgentsToChangeVisibility is true.

The call UI action bar

In audio and video calls, the message view is replaced by the call UI. The call UI action bar has its own set of configuration properties.

The values the properties can take are the same as those outlined in the section "Collaboration layers" above.

The list of messages

The list of messages in a conversation
Figure 11. The list of messages in a conversation

To speed up loading conversations with lots of messages, you can limit the number of messages preloaded when you open the conversation with com.unblu.conversation.messaging.ui.numberInitiallyDisplayedMessages. If the user scrolls up the conversation, Unblu automatically loads older messages once they almost reach the top of the currently displayed list of messages.

The number of messages loaded is determined by com.unblu.conversation.messaging.ui.numberOfAdditionalMessagesDisplayedWhenScrolledToTop. While the older messages are being loaded, the user sees a system message stating what Unblu is doing. You can adapt the text of the message by editing the text property com.unblu.conversation.messaging.ui.loadingMoreMessagesLabel.

When users hover over a message, Unblu displays the actions that can be invoked on the message in question. The sort order of predefined actions is defined by the following configuration properties:

The sort order of custom actions is defined on the custom actions themselves.

The configuration properties mentioned in this section affect the list of messages in the visitor UI, too.

The layer action bar

The layer action bar contains the tools that can be used in a collaboration layer:

  • Mark mode Mark mode icon allows users to mark an area of the collaboration layer. An agent could use this to point a client to a form field they need to fill in.

  • Remote control Remote control icon allows users to take control of the collaboration layer and click elements of a shared website, for example.

  • Scroll lock Scroll lock icon activates scroll lock in the collaboration layer.

The tools displayed in the action bar are the ones the participant in question is authorized to use in that particular collaboration layer. The article Configuring and manipulating collaboration layers describes the relevant configuration properties.

The layer top bar

The layer top bar holds the button to maximize the view of the collaboration layer, and a button to stop collaborating on the layer. It displays a label stating which type of collaboration is taking place in the layer.

The layer top bar
Figure 12. The layer top bar

The Stop button will only be displayed to participant types allowed to stop the type of collaboration layer in question. You can specify this in the conversation template. Filter the template’s configuration properties by the term stop to review the options available to you.

The About Unblu Spark modal page

The settings menu of the agent and admin UIs includes the link About Unblu Spark. You can configure what appears in the modal page with the following text properties:

  • com.unblu.desk.about.productInfoLabel displays information about the version of Unblu Spark the agent’s using. By default, this includes the version number.

  • com.unblu.desk.about.additionalAboutText can be used to display additional information in the modal page. By default, it contains a link to the Agent Desk guide.

    You can use Markdown to format the additional text.

Customizing the Floating Visitor UI and collaboration space

When a visitor clicks the launcher button on your website, the Floating Visitor UI opens. For information on customizing the launcher button, refer to the relevant section of the UI theming cheat sheet.

The Floating Visitor UI

The Floating Visitor UI includes a number of different customizable screens.

The welcome screen has at most three parts, labeled in the picture below:

  1. The action bar

  2. The conversation list

  3. The engagement UI

The Floating Visitor UI welcome screen
Figure 13. The Floating Visitor UI welcome screen

The PIN entry screen is for entering a PIN to join an existing conversation.

The Floating Visitor UI PIN entry screen
Figure 14. The Floating Visitor UI PIN entry screen

The chat screen is essentially the same as the Agent Desk message view. It consists of the action bar, the list of messages, and the message input field.

The Floating Visitor UI chat screen
Figure 15. The Floating Visitor UI chat screen

The action bar

Many of the possibilities for customizing the action bar were already discussed above. This section focuses on those parts of the action bar that are only present in the Floating Visitor UI but not the Agent Desk.

The call UI action bar

For the call UI action bar, there’s one configuration property that’s only in the Floating Visitor UI:

Apart from that, the configuration properties used to configure the call UI action bar in the Agent Desk, described above, also affect the call UI action bar in the Floating Visitor UI.

The conversation list

The conversation list is displayed once a user has at least one ongoing conversation. It lists all ongoing conversations, but can be configured to include ended conversations, too.

To display ended conversations, enable com.unblu.visitorsession.showEndedConversations. Ended conversations that meet the following requirements will be displayed:

  • The conversation was initiated by a visitor, not an agent.

  • At least one participant transmitted a message.

You can change these requirements with the following configuration properties:

By default, active and ended conversations appear in a single list. To display them in separate lists, set com.unblu.visitor.ui.endedConversationsDisplayMode to IN_ARCHIVE. This adds two toggle buttons to the UI that allow visitors to switch between the lists of active and ended conversations.

Conversation list with active and archived conversations in separate lists

The buttons use the flat toggle button style, but you can customize their appearance, including their width and the gap between them, with the configuration properties starting with com.unblu.visitor.conversationlist.toggle.*.

The labels of the two buttons are defined in the text properties com.unblu.visitor.ui.activeConversationsFilterButtonLabel and com.unblu.visitor.ui.endedConversationsFilterButtonLabel, respectively.

Each entry in the conversation list has the following elements:

  • The avatar of the assigned agent (if present) or conversation recipient. If there are multiple participants and com.unblu.conversation.ui.enableGroupConversationAvatar is enabled, Unblu displays the group avatar.

  • A primary title. The primary title is displayed immediately to the right of the avatar.

  • An optional secondary title. The secondary title is displayed to the right of the primary title and abbreviated with ellipses if necessary.

    If don’t want to show the secondary title in the conversation list, set com.unblu.visitor.ui.displaySecondaryTitleInConversationOverview to false.

  • The last message sent to the conversation. The last message is displayed beneath the primary and secondary titles.

The contents of the primary and secondary titles are determined as follows:

  • If a conversation has no topic and no assigned agent, its primary title is the recipient of the conversation, that is, the account, named area, or team it’s been assigned to. It won’t have a secondary title.

  • If a conversation has no topic but it has an assigned agent, its primary title is the name of the assigned agent. Its secondary title is the recipient of the conversation.

  • If a conversation has a topic but no assigned agent, its primary title is the topic of the conversation. Its secondary title is the recipient of the conversation.

  • If a conversation has a topic and an assigned agent, its primary title is the topic of the conversation. Its secondary title is the name of the assigned agent.

You can configure the format to display an assigned agent’s name in. See com.unblu.person.displayname.agentDisplayNameEvaluationOrder for further details.

For conversation recipients, you can choose whether to display their name or a static name for that type of recipient with the following properties:

You can specifiy the static name for each type of recipient in the following text properties:

The engagement UI

The engagement UI is the screen of the Floating Visitor UI that visitors use to start a conversation with your organization. It can be configured in various scopes:

  • Globally

  • For a single Unblu account

  • For a named area

  • For an API key

You can specify the types of engagement visitors are able to initiate with the following configuration properties:

To add the controls that allow visitors to start conversations with the various engagement types from the visitor UI welcome screen, you need to set the configuration property from the list below that corresponds with the engagement type in question to true:

These configuration properties are only available in the Account Configuration interface if the corresponding *.startWith*Enabled configuration property is true. For example, com.unblu.visitor.ui.engagement.showAudioCallEngagementOption isn’t available unless com.unblu.messenger.startWithAudioCallOptionEnabled is true.

You must also enable the feature in general for the configuration properties above to have an effect. Enabling, say, embedded co-browsing on the engagement UI doesn’t have an effect unless embedded co-browsing is enabled for the Unblu account in question.

The options to launch a chat, video call, and an audio call are displayed as buttons. By default, the chat button uses the primary button style. The audio and video buttons use the secondary button style. You can change this with the appropriate configuration property listed below:

All other options are displayed as links.

With the configuration property com.unblu.conversation.message.allowSeeTypingIndicator, you can specify which participant types see the typing indicator when another participant is entering a text message. This property is available in the conversation and conversation template scopes.

The list of messages

Customizing the list of messages is discussed above.

The collaboration space

The collaboration space consists of:

  • The area displaying the collaboration layer

  • The collaboration layer controls

Configuring the collaboration is discussed in the article Configuring and manipulating collaboration layers.

See also