Configure handoff to any generic engagement hub

Copilot Studio lets you hand over agent conversations seamlessly and contextually to a human agent through an engagement hub.

With some custom development, you can configure your agent to hand off conversations to any engagement hub. This guide describes how you can do this.

Prerequisites

• You need to have built an agent using Copilot Studio.
• You need an engagement hub that can interact programmatically using APIs or SDK.

Overview

A full handoff to an engagement hub follows this pattern:

1. An end user interacts with the engagement hub's chat canvas.

2. The engagement hub routes the incoming chat through built-in chat routing capabilities to an agent.

3. A custom adapter relays the incoming chat messages from the engagement hub to a Copilot Studio agent.

4. Once the end user triggers handoff, Copilot Studio starts handoff with full conversational context.

5. The custom adapter intercepts the handoff message, parses the full conversation context, and seamlessly routes the escalated conversation to a skilled human agent, based on availability.

6. The end user's chat is seamlessly and contextually handed off to a human agent who can resume the conversation.

To hand off the conversation to a human agent, you need to build a custom handoff adapter.

Build a custom handoff adapter

An adapter bridges conversations to and from your agent engagement hub by relaying and transforming messages between end users, agents, and human agents.

Most popular agent engagement hubs provide software development kits (SDKs) or document their APIs publicly, enabling you to build such adapters.

It's outside the scope of this document to cover what a custom adapter could contain. However, the following sample handoff message, based on what Copilot Studio generates as part of our standard handoff to a live agent experience, can help get you started.

These code snippets and samples allow you to extract context from the conversation to seamlessly and contextually hand off agent conversations to any generic engagement hub.

Sample handoff message payload

Handoff is currently only supported over Direct Line. Learn more about interacting with an agent over Direct Line. Upon handoff, an event activity called handoff.initiate is raised and sent to the adapter.

You can see a full sample handoff message activity on our GitHub site.

Extract context from handoff message

To use conversational context, you must parse the handoff.initiate event activity. The following snippet of code parses the handoff.initiate event activity and extracts the conversational context. See the full code sample on GitHub.

public void InitiateHandoff(string botresponseJson)
{
    BotResponse response = JsonConvert.DeserializeObject<BotResponse>(botresponseJson);

    // Look for Handoff Initiate Activity. This indicates that conversation needs to be handed off to agent
    Activity handoffInitiateActivity = response.Activities.ToList().FirstOrDefault(
        item => string.Equals(item.Type, ActivityTypes.Event, System.StringComparison.Ordinal)
        && string.Equals(item.Name, HandoffInitiateActivityName, System.StringComparison.Ordinal));

    if (handoffInitiateActivity != null)
    {
        // Read transcript from attachment
        if (handoffInitiateActivity.Attachments?.Any() == true)
        {
            Attachment transcriptAttachment = handoffInitiateActivity.Attachments.FirstOrDefault(a => string.Equals(a.Name.ToLowerInvariant(), TranscriptAttachmentName, System.StringComparison.Ordinal));
            if (transcriptAttachment != null)
            {
                Transcript transcript = JsonConvert.DeserializeObject<Transcript>(transcriptAttachment.Content.ToString());
            }
        }

        // Read handoff context
        HandoffContext context = JsonConvert.DeserializeObject<HandoffContext>(handoffInitiateActivity.Value.ToString());

        // Connect to Agent Hub
        // <YOUR CUSTOM ADAPTER CODE GOES HERE>
    }
}