Contact usRequest a demo

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.

The support period for version 6 ended on 29 August 2023. We no longer provide support or updates for this version. You should upgrade to the latest version of Unblu.

Deputy management

Deputy management is intended for scenarios where Unblu is used as a communication tool to support long-term advisor-client relationships.

In the advisor-client set up, a permanent, long-running conversation is set up on the Unblu system between each client and their advisor, usually by an administrator when the customer first becomes a client of the firm. This way of configuring conversations as long-term, persistent entities contrasts with the more common live support model where conversations are initiated on demand when customers visit a website and are ended when they leave.

The long-term conversation becomes both the medium and the permanent record of the relationship between that client and that advisor. It is only ended is the client leaves the firm.

In such scenarios there are times when other people at the firm, apart from the principal advisor, may need to have access to or to participate in a conversation. For example, if the principal advisor is unavailable, either momentarily or for a longer period, an assistant or an temporary advisor may need to jump in to answer a question.

At the same time, it is also important to maintain the primary relationship between the advisor and their client and for the client not to be given the impression that they are being passed around from agent to agent.

Deputy management aims to address this use-case, with an eye to maintaining the balance between responsiveness and relationship building.

Terminology

Deputy management is actually a combination of three different Unblu features:

  • Long-running conversations

  • Secondary agents

  • Hidden participants

The concept of long-running conversations was covered above. For details on secondary agents and hidden participants see the Secondary Participants section.

The mapping between the roles in the deputy management scenario and the technical Unblu terms is as follows:

  • Principal Advisor: In Unblu this is the Assigned Agent or Assignee of the conversation. There is only one such person in any conversation.

  • Client: In Unblu this is the Primary Visitor, Visitor or Context Person of the conversation. There can be more than one visitor per conversation, but in the deputy management scenario there is only ever one, the client.

  • Deputy: In Unblu this is a Secondary Agent who is also a Hidden Participant in the conversation. There can be more than one such person in a conversation.

Assistant or fellow advisor as deputy

How deputies are organized and assigned is entirely up to your organization. In some cases it may make sense to have a dedicated assistant act as deputy to a group of principal advisors, being available to cover situations where a principal is unavailable. In such cases the assistant would be added as a deputy to all the conversations assigned to all the principals in the group.

In other cases a firm may have a group of advisors who all act as deputies for each other. In this case each conversation would be set up with one client, one principal and all other advisors as deputies.

Note that this scenario is accommodated by the fact that the Inbox is divided into two tabs: My Conversations and Secondary Conversations. The conversations for which the agent is the principal advisor will be under My Conversations while the conversations for which the agent is a deputy will be under Secondary Conversations.

Setting up conversations with deputies using the Web API

We will look at two different scenarios: Setting up existing conversations with deputies, and adding deputies to new conversations.

All calls use V3 of the Web API. In the examples below we use <prefix> in place of the initial part of the call URL. You must substitute the appropriate string, for example:

www.bank.com/co-unblu

Existing conversations

Add hidden participant

For each conversation that you wish to add a deputy to, use the conversations/addParticipant with the hidden flag set to true to add the deputy as a new hidden participant. The general form of the call is

GET <prefix>/rest/v3/conversations/<conversationId>/addParticipant?
    personId=<string>&
    connectedViaExternalMessenger=<boolean>&
    hidden=<boolean>&
    expand=<propertyName>

Here’s an example call adding a person with personId ABC123 as a hidden participant to conversation XYZ456:

GET www.bank.com/co-unblu/rest/v3/conversations/XYZ456/addParticipant?personId=ABC123&hidden=true

Set conversation configuration

After adding the hidden participant you will need to ensure that the configuration of notifications and forwarding is correct. The relevant configuration properties are:

To set these properties, first read the existing configuration with conversations/read, alter the returned structure, and then write it back with conversations/updateConfiguration.

The general form of the read call is:

GET /conversations/read?id=<conversationId>&expand=configuration

The general form of the write call is:

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

{
    "<property1>": "<value1>",
    "<property2>": "<value2>",
    ...
    "<propertyN>": "<valueN>"
}

Here’s an example setting the notification and read indicator properties for conversation XYZ456:

First read the existing conversation configuration with conversations/read:

GET /conversations/read?id=XYZ456&expand=configuration

returning (for example):

{
    "$_version": "5c90b6e9e361ba797014795f23620167",
    com.unblu.conversation.notification.assignedAgentNotificationRule":
        "UNREAD_BY_ALL_AGENTS_EXCLUDING_HIDDEN"
}

Then alter the structure by adding or replacing the appropriate properties, then write it back with the POST call:

POST <prefix>/rest/v3/conversations/XYZ456/updateConfiguration

{
    "$_version": "5c90b6e9e361ba797014795f23620167",
    "com.unblu.conversation.notification.assignedAgentNotificationRule":
        "UNREAD_BY_ALL_AGENTS_INCLUDING_HIDDEN",
    "com.unblu.conversation.notification.contextPersonNotificationRule":
        "UNREAD_BY_ALL_AGENTS_INCLUDING_HIDDEN",
    "config:com.unblu.conversation.notification.secondaryAgentNotificationRule":
        "UNREAD_BY_ALL_AGENTS_INCLUDING_HIDDEN",
    "com.unblu.conversation.message.markAgentMessagesAsReadCondition":
        "READ_BY_ALL_EXCLUDING_HIDDEN",
    "config:com.unblu.conversation.message.markVisitorMessagesAsReadCondition":
        "READ_BY_ALL_EXCLUDING_HIDDEN"
}

Note the $_version property. This property is used to avoid concurrent modifications to data structures. You read the structure, get the current version hash and write it back with changes using that hash. If another process has in the meantime changed the structure, the hash will be different and your write will fail, in which case you must try again.

New conversations

For new conversations you can create the conversation with the hidden participant(s) and the appropriate conversation configuration with a single call to conversations/create while setting the expand parameter to configuration in order to write the configuration substructure of the conversation data. The general form of the call is:

POST <prefix>/rest/v3/conversations/create?expand=<propertyName>

{
    "$_type" : "ConversationData",
    "topic" : <string>,
    "recipient" : <ConversationRecipientData>,
    "participants" : <list<ParticipantData>>,
    "assigneePersonId" : <string>,
    "contextPersonId" : <string>,
    "state" : <EConversationState>,
    "initialEngagementType" : <EInitialEngagementType>,
    "locale" : <string>,
    "tokboxSessionId" : <string>,
    "conversationTemplateId" : <string>,
    "links" : <list<ConversationLink>>,
    "externalMessengerChannelId" : <string>,
    "sourceId" : <string>,
    "configuration" : <map<string,string>>,
    "text" : <map<string,map<string, string>>>
}

The body of the post is a ConversationData object. The most significant sections for deputy management are the participants property, which is an array of ParticipantData objects, and the configuration property which is a map of configuration settings (it should be identical to the one mentioned above in the section on existing conversations).

Here is an example of setting up a conversation with a client (ABC123), principal advisor (DEF456) and one deputy (GHI789) on account JKL012.

POST <prefix>/rest/v3/conversations/create?expand=configuration

{
    "$_type": "ConversationData",
    "accountId": "JKL012",
    "recipient": {
        "$_type": "AccountData",
        "id": "JKL012",
        "displayName": "Main Account",
        "avatar": null
    },
    "participants": [
        {
            "$_type": "ParticipantData",
            "state": "ACTIVE",
            "personId": "ABC123",
            "hidden" : "false"
        },
        {
            "$_type": "ParticipantData",
            "state": "ACTIVE",
            "personId": "DEF456",
            "hidden" : "false"
        },
        {
            "$_type": "ParticipantData",
            "state": "ACTIVE",
            "personId": "GHI789",
            "hidden" : "true"
        }
    ],
    "assigneePersonId": "DEF456",
    "contextPersonId": "ABC123",
    "state": "ACTIVE",
    "initialEngagementType": "CHAT_INVITE"
    "configuration": {
        "com.unblu.conversation.notification.assignedAgentNotificationRule":
            "UNREAD_BY_ALL_AGENTS_INCLUDING_HIDDEN",
        "com.unblu.conversation.notification.contextPersonNotificationRule":
            "UNREAD_BY_ALL_AGENTS_INCLUDING_HIDDEN",
        "config:com.unblu.conversation.notification.secondaryAgentNotificationRule":
            "UNREAD_BY_ALL_AGENTS_INCLUDING_HIDDEN",
        "com.unblu.conversation.message.markAgentMessagesAsReadCondition":
            "READ_BY_ALL_EXCLUDING_HIDDEN",
        "config:com.unblu.conversation.message.markVisitorMessagesAsReadCondition":
            "READ_BY_ALL_EXCLUDING_HIDDEN"
    }
}