Custom context panels

What custom context panels are for

A custom context panel puts one of your own web applications right next to the conversation in the Agent Desk. Agents can look up a customer, check an order, or fill in a form without leaving the Unblu UI.

The panel’s URL can carry details of the conversation, such as the ID of the visitor or of the assigned agent. Your application reads these details from the URL and shows the matching information as soon as the agent opens the panel. For example, a panel with the URL https://crm.example.com/customers?id=${conversation.contextPerson.sourceId} opens the visitor’s record in your customer relationship management (CRM) system.

You decide which agents see a panel, in which desk, and in which conversations.

Creating a custom context panel

To create a custom context panel, open Context panels in the Account Configuration interface. The overview lists the account’s panels.

Click New context panel to open the panel editor. To change an existing panel, click it in the overview. Its page has the same settings as the editor:

Enabled: Whether the panel can appear in conversations. New panels are enabled by default.
Icon: The icon shown in the agent’s context bar. The icon is required. It must be a JPG or PNG file no larger than 5 MB. The recommended dimensions are 256 × 256 px.
Name and Description: The name and description of the panel. You can translate both in the Translations section of the editor.
Show panel header: Whether the name and description appear at the top of the open panel. The setting is on by default.
Keep alive when closed: Whether the panel keeps its state when the agent closes it. The setting is off by default. For information on what happens when the agent closes and reopens a panel, refer to Closing and reopening panels.
URL: The page the panel loads. It must be an absolute http or https URL of at most 2000 characters, and it can contain URL variables. The editor warns you if the URL uses http, because browsers block insecure content on a secure page.
Participation types: The agents the panel is shown to: Assigned agent, Secondary agent, Ghost, or any combination of them. Select at least one.
Allowed features: The browser features the panel can use. The options are Microphone, Camera, Screen capture, Fullscreen, Geolocation, Storage access, and Clipboard write.
Frontends: Whether agents see the panel in the Agent Desk, the Single Conversation Desk, or both. In the editor, the Single Conversation Desk is labeled Agent Single Conversation Desk. Select at least one.

You can also manage panels with the web API endpoints /conversationcontextpanels/create, /conversationcontextpanels/{conversationContextPanelId}/read, /conversationcontextpanels/search, /conversationcontextpanels/update, and /conversationcontextpanels/{conversationContextPanelId}/delete. They require the ADMIN role, and you must call them on the internal entry path.

A new panel doesn’t appear in any conversation until you add it to a conversation template.

URL variables

A panel’s URL can contain the following variables:

${conversation.id}: The ID of the conversation.
${conversation.sourceId}: The source ID of the conversation.
${conversation.contextPerson.id}: The ID of the conversation’s context person, usually the visitor.
${conversation.contextPerson.sourceId}: The source ID of the context person.
${conversation.assignedAgent.id}: The ID of the assigned agent.
${conversation.assignedAgent.sourceId}: The source ID of the assigned agent.

Unblu rejects any other ${…} variable when you save the panel.

If a variable has no value, Unblu replaces it with the literal string null. For example, an anonymous visitor has no source ID, so for anonymous visitors, ${conversation.contextPerson.sourceId} becomes null.

Unblu URL-encodes each value before inserting it into the URL.

Use variables only in the path, query, or fragment of the URL. If the host contains a variable, Unblu doesn’t allow the panel’s origin in the Content Security Policy. With com.unblu.contentsecuritypolicy.mode set to ON, the browser then blocks the panel.

Adding custom context panels to conversation templates

By default, a conversation offers no custom context panels. Two configuration properties determine which panels it offers. You can set both on a conversation template (or on an individual conversation):

To offer specific panels, select them in com.unblu.conversation.contextpanel.selectedConversationContextPanelIds. The list includes disabled panels, but only enabled panels appear in the context bar. Drag the selected panels into the order you want the context bar to show them in. If a selected panel is deleted, the list shows it as Not found, followed by its ID.
To offer every enabled panel, set com.unblu.conversation.contextpanel.enableAllConversationContextPanels to true. The context bar then shows the panels sorted by their untranslated names. While the property is true, you can’t select individual panels.

Using custom context panels

When a conversation offers custom context panels, agents open them from the context bar of the Agent Desk or the Single Conversation Desk.

Who sees a panel

An agent sees a panel if all the following apply:

The panel is enabled.
The conversation offers the panel, either because it’s selected individually or because all enabled panels are offered.
The agent is working in a desk that the panel’s Frontends setting includes.
The agent’s participation type is one of the panel’s Participation types.

If one of these conditions stops being true while the agent has the panel open, the panel closes immediately. A change to a conversation template’s selection only reaches conversations that inherit changes to the template’s configuration. For information on inheriting template changes, refer to Configuration property scope and the configuration cascade.

Custom context panels in the context bar

The context bar shows the built-in panels first, then a divider, then the custom context panels.

Up to five custom context panels appear in the context bar. If a conversation offers six or more panels, the first four appear, followed by a button that shows the number of remaining panels, for example +3. Clicking the button opens a menu with the remaining panels. Each entry in the menu shows the panel’s icon and name. Hovering over an entry shows the panel’s description.

Panel headers and translations

If a panel’s Show panel header setting is on, the open panel has a header with the panel’s name and description, and a button to close the panel. The header also has a button to resize the panel if the panel can be resized and com.unblu.conversation.ui.allowResizingContextPanels is enabled for the user’s participant type. If Show panel header is off, the panel starts directly with its content, and it has no buttons to close or resize it. Agents then close the panel from its entry in the context bar, or by pressing Esc. A panel opened from the menu of remaining panels has no entry of its own in the context bar. Without a header, agents close such a panel by pressing Esc or by opening another panel.

The name and description of a panel appear in the conversation’s language. If the panel has no translation for that language, Unblu uses its untranslated name and description.

Closing and reopening panels

By default, Unblu discards a panel when the agent closes it. When the agent reopens the panel, it loads its URL again and starts from scratch.

If a panel’s Keep alive when closed setting is on, closing the panel only hides it. The page stays loaded, so when the agent reopens the panel, it’s in the state they left it in. For example, a form the agent started filling in still contains what they entered. The panel stays loaded while the conversation is open or until the agent reloads the Unblu UI.

Unblu reloads a panel whenever one of its URL variables changes value, even if the panel is kept alive. When this happens, the panel loses its state. For example, when an anonymous visitor logs in, ${conversation.contextPerson.sourceId} changes from null to their source ID, and the panel reloads with the new URL. Transferring the conversation to another agent changes the ${conversation.assignedAgent.id} and ${conversation.assignedAgent.sourceId} variables in the same way.

Security considerations

The values of URL variables, such as conversation and person IDs, leave Unblu and reach the host of the panel’s URL.
Unblu renders custom context panels without an iframe sandbox attribute. A panel on a different origin from Unblu is isolated by the browser’s same-origin policy. A panel on the same origin as Unblu isn’t.
If com.unblu.contentsecuritypolicy.mode is ON or REPORT_ONLY, Unblu adds the origin of each enabled panel to the frame-src directive of the desks in the panel’s Frontends setting. With the mode set to ON, a panel whose Frontends setting includes only the Agent Desk can’t be framed in the Single Conversation Desk and vice versa.

For information on the Content Security Policy that Unblu sends, refer to Content Security Policy (CSP).