Contact usRequest a demo

Reassigning conversations with the Unblu web API

When the assigned agent of the conversation is removed from a conversation, the conversation ends unless it’s reassigned to a new agent.

This is important when you set up a permanent, long-running conversation between each client and their advisor, usually when the customer first becomes a client of the firm. When a client changes advisors, you need to transfer their long-running conversation to their new advisor. Agents can do this in the Agent Desk, but you can also automate the task with the Unblu web API.

The discussion below uses the Unblu terms "agent" and "visitor" to refer to the advisor and the client, respectively.

Reassigning a conversation to a new agent using the web API

To reassign a conversation to an agent who isn’t already a participant in the conversation, call the endpoint /invitations/forwardConversationToAgent. The call must include the personId of the new agent.

The text of the optional comment field appears in the agent’s view of the conversation as a message from the previous assigned agent, that is, the agent the conversation is being forwarded from. The visitor doesn’t see it.

Once the new assigned agent accepts the forwarding, the previous assigned agent is removed from the conversation and can no longer access it. If you want them to remain in the conversation, add the new assigned agent to the conversation by calling /conversations/{conversationId}/addParticipant, then make them the assigned agent by calling /conversations/{conversationId}/setAssigneePerson.

Reassigning a conversation to a participating agent using the web API

It isn’t possible to forward a conversation to an agent who’s already participating in the conversation. As a result, you can’t simply call /invitations/forwardConversationToAgent if the future assigned agent is already a participant in the conversation.

To assign a conversation to a different participant, proceed as follows:

  1. If the new assigned agent is a hidden participant, you must first change their visibility by calling /conversations/{conversationId}/changeParticipantVisibility. Make sure you include the query parameter hidden=false.

  2. Call /conversations/{conversationId}/setAssigneePerson to change the conversation’s assigned agent.

  3. If necessary, remove the previous assigned agent from the conversation by calling /conversations/{conversationId}/offboardParticipant. If you include something in the comment field, it isn’t visible in the conversation.

    Once you remove the agent from the conversation, they can no longer access it.

  4. If your organization uses the ../../../knowledge-base/configuration/conversations/awaited-person-type.html, you can also call the endpoint /conversations/{conversationId}/setAwaitedPersonType to set the awaited person type.

See also