|This document describes version 6 of Unblu. If you’re using the latest major version of Unblu, go to the documentation of the latest version.|
Unblu provides a number of different message types for Live Chat conversations. Each message type provides a different set of features, geared to different use cases.
Most of the message types will be of particular interest when you want to integrate dialog bots into Unblu.
The main message types can be grouped into two overarching categories, messages and questions. System messages are a special category of messages and are discussed separately.
Messages allow visitors to respond using the text input field at the bottom of the Messaging View.
|Wherever Markdown may be used, its characters count towards the length of the element’s content.|
Text messages are just that: messages containing text.
Depending on the value of the configuration property com.unblu.conversation.messaging.ui.chatMessageAsMarkdownEnabled, the text may also contain Markdown.
Please consult the description of the
TextPostMessageData type in the Web API reference for further details.
|Card messages are available from Unblu version 6.12.0 onwards.|
Card messages group related information in a single container, a card. A card may contain an image, a title, text, and actions such as buttons and links. It must contain at least one of these four elements. Each element on the card is independent of the others.
The sections below outline the properties of the various card elements. For further details, please consult the description of the
CardPostMessageData type in the Web API reference.
The image is always displayed at the top of the card.
It always takes up the full width of the card (256 pixels) and is 144 pixels high, giving an aspect ratio of 16:9. If the aspect ratio of the image does not match that of the image field, the image is cropped from the center out.
If the UI is maximized, the image is enlarged to a maximum width of 400 pixels. Its aspect ratio stays the same.
The title uses a bold font and is positioned immediately below the image.
It must be no more than 64 characters long.
The text is displayed beneath the title and must be no longer than 640 characters.
It may contain Markdown provided the feature is enabled. However, Markdown headings are not permitted.
Actions appear stacked vertically after the text of a card.
Each card may have a list of up to five actions.
The text of an action may not exceed 24 characters in length.
If the text does not fit in the available space, it is truncated with an ellipsis.
There are five different types of action:
Internal links are displayed as links. They open in the same browser tab. An internal link must be a valid URL.
External links must also be valid URLs. In addition to being displayed as links, external links display an external URL icon to indicate that they will open in a new browser tab.
Co-browsable links initiate a universal co-browsing session. They appear as links sporting a co-browsing icon .
If universal co-browsing requires approval from any participants in the conversation, clicking on the link will request their approval.
Buttons are used for reply messages and reply messages with a technical value. They are displayed in the style of secondary buttons.
When a user clicks on the button of a reply message, the action’s text is sent to the conversation as a message.
When a user clicks on the button of a reply message with a technical value, the label of the button is displayed as a message in the conversation. The technical value is sent to the bot that sent the list message for further processing.
After clicking on a button, all of the buttons remain available.
You can include multiple actions of different types on a single card.
|List messages are available from Unblu version 6.13.0 onwards.|
List messages consist of a header, a list of at most ten list items, and actions. In the example below, the header has a green frame, the list items have an orange frame, and the action has a yellow frame.
Each element is described below. For further details, please consult the description of the
ListPostMessageData type in the Web API reference.
The header of a list message is similar to a card, except that it may not contain any actions. As with card messages, the header must contain at least one of the three elements permitted. The same restrictions regarding image size and title length apply. The text may be no more than 256 characters long.
List items are displayed beneath one another in the order in which they are sent to the Unblu server. The items take up the full width of the message.
A list item is made up of the following elements:
A title. The title is compulsory for each list item. It must be no more than 64 characters long and is displayed flush left.
An optional text. The text may be no more than 256 characters long and is displayed flush left.
An optional image. The image should be at least 128 by 128 pixels large. By default, the image is displayed aligned on the right. You can change this behavior with the configuration property com.unblu.conversation.messaging.ui.listMessageImageAlignment.
An optional action that is carried out when a user clicks on the list item.
Actions on list items allow you to provide users with more context for the choice they’re making than is possible with a set of actions beneath an entire list. If you add an action to one list item, we recommend that you add actions to the other list items, too, to provide a more consistent user experience.
Link actions—internal links, external links, and co-browsable links—on list items are displayed beneath the text on list items. Reply messages and reply messages with a technical value, on the other hand, aren’t displayed separately on list items.
A list message may contain at most ten list items.
Actions in lists work in the same fashion as actions in cards, and the same restrictions and limitations apply.
File messages are used to send files. You can include an optional caption, text explaining what the file contains or asking the recipient a question. The caption can contain Markdown provided the feature is enabled. As with other message types, you can also provide a fallback text for use in notifications and previews.
Strictly speaking, quick replies are not a separate message type. They provide visitors with a range of possible responses to a message. However, unlike multiple choice questions, the list of possible responses is not exhaustive.
Quick replies are displayed immediately above the standard text input field at the bottom of the Individual UI. The label of a quick reply may not be more than 40 characters long. If the length of the labels permit, quick replies are displayed next to one another:
If there are more than five quick replies, they are always stacked. Initially, at most five quick replies are displayed.
In the example above, there are eight quick replies. The button in the lower right-hand corner of the Conversation thread shows how many quick replies are hidden. It is also used to display the three hidden quick replies:
You can add up to 13 quick replies to a question. However, we recommend providing between three and five quick replies.
Unlike multiple choice questions, quick replies are not an exhaustive list of answers to a question. They are merely suggestions. If the answer a visitor wants to give is not listed, they can enter it themselves in the chat text input field.
Quick replies are no longer visible under the following circumstances:
The user selects a quick reply.
The user enters something in the text input field and sends the message.
The user receives a new message before selecting a quick reply or typing and sending a message.
Questions force visitors to select from a range of options, or to enter a particular type of response. In both cases, the chat text input field is locked.
Multiple choice questions offer visitors a fixed set of possible answers to a question. The visitor must choose one of the options offered for the Conversation to proceed.
As the image above shows, you can specify whether possible answers should be displayed as primary or secondary buttons. The width of each button automatically adapts to the label it sports, although you can specify a minimum width using com.unblu.conversation.messaging.ui.multiChoiceButtonMinWidth. If a button’s label is longer than the space available on a single line, the label is truncated with an ellipsis.
If there are more than six possible choices, only the first five answers are displayed. The remaining choices are relegated to an overflow menu. You can change the maximum number of choices displayed with com.unblu.conversation.messaging.ui.multiChoiceMaxVisibleButtons.
Please consult the description of the
MultichoiceQuestionPostMessageData type in the Web API reference for further information.
Text questions require participants to enter a response to a question. The response must be entered in a separate field provided for this purpose. The normal text input field is blocked.
You can also specify a minimum and/or maximum length for the response, a regular expression that it must match, and the possibility to decline to provide an answer to the question.
Please consult the description of the
TextQuestionPostMessageData type in the Web API reference for further information.
Rating questions require participants to select a value on a scale.
You can also specify whether it is possible to skip rating the conversation.
The description of the
RatingQuestionPostMessageData type in the Web API provides further information.
System messages are messages without an explicit sender. They are about a conversation rather than part of it, letting participants know when other people join or leave a conversation, or when the conversation’s state changes.
System messages also play an important part in conversation logs: they make it possible to reconstruct the course of a conversation beyond the messages that were exchanged between participants.
The picture below shows some examples of system messages:
The text properties used for system messages generally have keys that start with
While this information can be useful, system messages can also be distracting. There may be too many of them, or the information they provide may not be relevant to all participants. You may therefore want to restrict the system messages shown to different participants. There are three groups of configuration properties that allow you to do so:
Configuration properties whose keys begin with
Configuration properties whose keys begin with
Configuration properties whose keys begin with
In each case, you specify the conversation participants who should receive the system messages in that category.
|The possibility to configure system messages was introduced in Unblu 6.23.2.|
To see how the three groups differ, let’s consider some examples.
The configuration property com.unblu.conversation.message.allowSeeSystemMessagesForForwarding influences system messages related to conversation forwarding. System messages in this category are displayed when an agent forwards a conversation to a specialist team, for example.
Two of the text properties affected by the configuration property are com.unblu.conversation.message.forwardedToTeam and com.unblu.conversation.message.forwardedToTeamGeneral. The former is shown to the conversation’s context person, the latter to all other participants, including ghost participants.
Suppose we have the following configuration:
What happens when an agent forwards a conversation?
The context person will see a system message with the text in com.unblu.conversation.message.forwardedToTeam.
Any secondary visitors in the conversation will see a system message with the text defined in com.unblu.conversation.message.forwardedToTeamGeneral.
The agent will not see a system message related to forwarding the conversation.
Because the configuration property did not include
GHOST, the agent won’t see a system message related to the forwarding when they review the conversation log. If
GHOSTwere included, the conversation log would include a system message with the text from com.unblu.conversation.message.forwardedToTeamGeneral.
If the visitor were to review the conversation log — provided they had that option --, they would see a system message about the forwarding.
As this example shows, it would be wrong to assume that there cannot be different texts for different participants just because there is only one configuration property to influence whether a particular category of system message is displayed or not.
The configuration properties com.unblu.conversation.message.allowSeeDirectSystemMessagesForLayerLifecycle and com.unblu.conversation.message.allowSeeGeneralSystemMessagesForLayerLifecycle control who is shown system messages related to starting collaboration layers and switching between collaboration tools (remote control, mark mode, and scroll lock).
Suppose your support agents launch embedded co-browsing sessions by providing visitors with a PIN. You have included the following configuration in the Join embedded co-browsing conversation template:
This configuration will have the following effect:
When the visitor enters the PIN and the embedded co-browsing session starts, both the agent and the visitor will see a system message with the text from com.unblu.conversation.message.layerActivatedBySystem. This is because from a technical standpoint, the embedded co-browsing was launched by the system, not the agent. Thus neither the agent nor the visitor are the person directly responsible for launching the collaboration layer.
If the visitor were to stop the embedded co-browsing session, they would see a system message with the text from com.unblu.conversation.message.layerDeactivatedDirect, because they are the person who stop the co-browsing session. The agent would see a system message with the text from com.unblu.conversation.message.layerDeactivated.
If it were the agent who stopped the co-browsing session, the visitor would see a system message with the text from com.unblu.conversation.message.layerDeactivated. The agent, on the other hand, would not see a system message. Normally, they would be shown a system message with the text from from com.unblu.conversation.message.layerDeactivatedDirect, but they are not listed as in the configuration property com.unblu.conversation.message.allowSeeDirectSystemMessagesForLayerLifecycle.
If, after the first collaboration session has ended, the agent launches a new embedded co-browsing session in the same conversation, the visitor will see a system message with the text from com.unblu.conversation.message.layerActivated. The agent will not see a system message, because as before, they are the person who launched the layer, but they are not listed in com.unblu.conversation.message.allowSeeDirectSystemMessagesForLayerLifecycle.
Many configuration properties for system messages include
GHOST participants by default. This is to ensure that conversation logs provide a complete account of conversations, above and beyond the messages exchanged between the participants. However, this means that the conversation logs often include different system messages from the ones participants saw as the conversation unfolded.
In those cases where there are separate configuration properties for general and for direct system messages, the
GHOST participant should be included in both configuration properties. This is because when you review conversation logs, you do so as a ghost participant. As a result, who a ghost is depends on who is reviewing the logs, which in turn affects which messages are displayed in the conversation logs.
Suppose, as in example 2 above, that your support agents launch embedded co-browsing sessions by providing visitors with a PIN. You have included the following configuration in the Join embedded co-browsing conversation template:
com.unblu.conversation.message.allowSeeDirectSystemMessagesForLayerLifecycle=CONTEXT_PERSON (1) com.unblu.conversation.message.allowSeeGeneralSystemMessagesForLayerLifecycle=ASSIGNED_AGENT,CONTEXT_PERSON,GHOST
|1||'GHOST' no longer receives direct system messages|
Imagine your support agent invites another agent to join the conversation, and it is the secondary agent who stop the collaboration layer. When the assignee reviews the conversation logs, they will see that the secondary agent stopped the co-browsing session. However, when the secondary agent looks at the logs of the same conversation, they won’t see a system message telling them who stopped the co-browsing session, because they are the person who stopped the session, but the
GHOST doesn’t receives system messages related to the person who initiated a change in the layer life cycle.