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.

Delegating the queue to a third-party system

This article describes how to replace Unblu’s built-in queue and conversation request dispatching system with a third-party system.

Unblu offers a powerful, flexible system for queueing and dispatching conversation requests. However, if one of your use cases involves deploying Unblu in a multichannel contact center environment, you may prefer to integrate Unblu into your existing automatic call distribution (ACD) system.

It’s important to consider all the implications of delegating the Unblu queue to a third-party system. For example, Unblu no longer has up-to-date information regarding agents' availability or the capacity to handle requests from different domains or named areas. This means that Unblu also can’t display such information to your visitors.

Overview

Delegating the queue relies on the webhooks and web API endpoints that Unblu provides:

You register webhooks to inform your ACD system of incoming conversation requests and changes to a conversation’s status. For example, a conversation request initiated by a visitor to your website triggers a webhook event. If you register a webhook that subscribes to this event, your ACD system can use the webhook delivery to route the conversation request to the appropriate agent.
You make calls to endpoints of the Unblu Web API to inform Unblu of changes to a conversation initiated by your ACD system or a system linked to it. For example, if an agent forwards a conversation to another agent, you make a call to a Web API endpoint to ensure that the conversation is handed over to the next agent.

The following sections describe how to implement some common use cases.

Assigning incoming conversation requests

To assign a new conversation request to an agent via your ACD system, follow the steps below.

Register a new webhook for the queue event assignment_request.created. You may do so either in the Account Configuration interface (as described here) or by calling the Web API endpoint /webhookregistrations/create.
When a visitor has completed the onboarding process and their conversation is queued, it triggers the assignment_request.created event.

The payload delivered to your webhook contains an element named links which in turn contains an array of links. You can supply the agent selected by your ACD system with the appropriate link to join the conversation.

The links are intended to be opened in a browser. Only one of the links to the conversation may be used, and it can only be used once.

By opening the link, the agent redeems the assignment request and is automatically assigned to the conversation. This also triggers the event assignment_request.redeemed. Register a webhook for this event if you want your ACD system to react to it.
If a visitor doesn’t wait for their conversation request to be answered, this triggers the queue event assignment_request.revoked. You should register a webhook for this event, too. Doing so enables your ACD system to react to this change, for example by updating the agent’s availability status.

Requeuing conversations

When a visitor initiates a conversation, use the Web API endpoint /invitations/requeueConversation to move the conversation to the queue. To do so, the call creates an assignment request invitation, and the state of the conversation is changed to QUEUED.

Inviting another agent to join a conversation

Unblu has webhooks to notify third-party systems of invitations sent to agents and web API endpoints to invite agents and teams to conversations.

Agent invitation webhooks

When an agent is invited to join a conversation, this triggers the agent invitation event agent_invitation.created. To forward the invitation with your ACD system, register a webhook for the event, either in the Account Configuration interface or via a call to the Web API endpoint /webhookregistrations/create.

The payload delivered as a result of the agent_invitation.created event contains both the token to redeem the invitation and an array of links by which to do so.
When an agent opens one of the links, they automatically redeem the invitation and join the conversation.
To update the new agent’s status in your ACD system, register a webhook for the event agent_invitation.redeemed.
If the invitation is revoked, this triggers the event agent_invitation.revoked. We recommend that you register a webhook for this event, too, so that your ACD system can respond to revocations.

There are no webhook events related to invitations sent to teams as opposed to agents. If you rely on webhooks to synchronize Unblu with a third-party system, you should set com.unblu.conversation.invitation.allowInviteTeam so that no one may invite teams to join a conversation.

There’s a way of working around this limitation using the web API discussed in the next section.

Invitation web API endpoints

Unblu has web API endpoints to invite both individual agents and teams to conversations.

To invite an individual agent to a conversation, call the endpoint /invitations/inviteAgentToConversation.
To invite an entire team to a conversation, call the endpoint /invitations/inviteTeamToConversation.

As mentioned in the previous section, team invitations don’t trigger any webhook events.

Forwarding a conversation to another agent

Unblu has webhooks to inform third-party systems when an agent forwards a conversation. It also has web API endpoints that let you forward conversations to another agent or a team.

Webhooks for conversation forwardings

If an agent forwards a conversation within the Agent Desk, you must let your ACD know that there is a conversation waiting for the new agent. You must also remove the original agent from the conversation once the new agent joins. To do so, complete the following steps:

Register a webhook for the agent forwarding event agent_forwarding.created.
As with inviting an agent, the payload delivered to the webhook contains the information required for the new agent to join the conversation.
Redeeming the forwarding triggers the event agent_forwarding.redeemed. Register a webhook for the event.
When the webhook is delivered, you can call the Web API endpoint /conversations/{conversationId}/offboardParticipant to remove the original assigned agent from the conversation.
You should also register a webhook for the event agent_forwarding.revoked. That way, your ACD system can react if the original assigned agent changes their mind about forwarding the conversation.

There are no webhooks for invitations sent to teams or named areas. You should therefore limit agents to forwarding conversations to agents. To do so, set com.unblu.conversation.invitation.allowForwardToTeam and com.unblu.conversation.invitation.allowForwardToNamedArea so that no one may forward conversations to teams or named areas.

Web API endpoints for forwarding conversations

There are web API endpoints for forwarding conversations to agents and teams.

To forward a conversation to an agent, call the endpoint /invitations/forwardConversationToAgent.
To forward a conversation to a team, call the endpoint /invitations/forwardConversationToTeam.

As noted above, there aren’t any webhooks for invitations sent to teams. If your third-party system requires on webhook events, avoid using this endpoint.

Revoking invitations and forwardings

You can revoke invitations and forwardings by calling the web API endpoint /invitations/{invitationId}/revoke.

Revoking an invitation or forwarding triggers the webhook event agent_invitation.revoked or agent_forwarding.revoked, respectively.

Leaving a conversation

You can configure your ACD system to react to participants leaving Unblu conversations.

Visitors

There aren’t any webhook events related to a visitor leaving a conversation. However, you can specify that conversations should end when the context person closes their browser with the configuration property com.unblu.conversation.lifecycle.autoEndOnDisconnect. If you register a webhook for the conversation event conversation.ended, your ACD system can react as you see fit.

Agents

An agent may choose to end or leave a conversation if a visitor doesn’t respond for a long time.

Agents should end or leave conversations using the Agent Desk. If the agent leaves and you want the conversation to continue, make sure that the configuration property com.unblu.conversation.lifecycle.autoEndOnLeave is set so that the assigned agent’s departure doesn’t end the conversation.

When the visitor types a new message, they automatically initiate Unblu’s reboarding process. If they choose to resume the conversation, this triggers the queue event assignment_request.created.

You can handle this the same way you would handle a new incoming conversation request.

This is only possible if you have activated the unassigned state for the type of conversation in question. See the description of com.unblu.conversation.lifecycle.enableUnassignedState for further information.