Configure handoff to Dynamics 365 Customer Service

When your customers need to speak with a human agent, your agent can seamlessly hand off the conversation. With the capabilities of the Chat Add-in for Dynamics 365 Customer Service, you can connect both text (messaging) conversations, and voice conversations (in classic chatbots).

Note

Connect to Dynamics 365 Customer Service with a voice-enabled agent. For more information, see Use interactive voice response in your agents.

When your agent hands off a conversation, it shares the full history of the conversation and all variables collected in the interaction. Your Dynamics 365 Customer Service routes incoming escalations to the right queue, and a live agent can seamlessly resume the conversation. For more information about how to use handoff in agent conversations, see Hand off to a live agent.

You can also enable single sign-on (SSO) to allow agents to sign users in if they're logged in to the page where the agent is deployed. For more information, see Configure single sign-on with Microsoft Entra ID and Pass authentication token to agent during single sign-on in live chat.

Web app

Prerequisites

• Sign in with an account that has at least OC_Admin and Agent Author roles.
• Have a product license for Copilot Studio and a product license for the Chat Add-in for Dynamics 365 Customer service.
• Your agent and Dynamics 365 Customer Service must be in the same environment.
• For end-to-end capabilities to work as expected, you must publish your agent.

Warning

Copilot Studio agents with names that are longer than 30 characters will fail to connect when you follow the instructions in this article. Ensure your agent's name contains less than 30 characters before you proceed.

Connect your agent to Dynamics 365 Customer Service

1. In Copilot Studio, open your agent, and go to the Channels page.

2. Under Customer engagement hub, select the Dynamics 365 Customer Service tile.

3. Select Connect.

   Note

   • The Dynamics 365 Customer Service package installation must be in the same environment as the agent.
   • If you're using Application Lifecycle Management (ALM), you might see a message that we can't determine if Dynamics 365 Customer Service integration is enabled for the environment. For more information, see Agents with Application Lifecycle Management.

4. Select View in Omnichannel to continue configuring the agent connection in Dynamics 365 Customer Service.

Important

To test the agent on your custom website, you must use the embed code that's specified in the chat widget you set up in Dynamics 365 Customer Service. If you use the embed code from Copilot Studio, handoff doesn't work. For more information, see Embed chat widget in your website or portal.

Agents with Application Lifecycle Management

Suppose you set up Application Lifecycle Management (ALM) for your agents, and are exporting and importing agents between development (unmanaged) and test or production (managed) environments. In that case, you might see a message that we can't determine if Dynamics 365 Customer Service integration is enabled for the environment.

If the agent you exported has Dynamics 365 capabilities enabled, you can ignore this message. The agent can still work properly. The message will disappear after you export the latest version of your agent from your development environment and then import it into a targeted test or production environment with managed agents.

If you continue to see the message after you export and import the latest version of your managed agent, make sure to remove any unmanaged layers:

1. Sign in to Power Apps and select the managed agent's environment.

2. In the navigation menu, select Solutions, and then select the solution that contains the agent with the unmanaged layer.

3. Next to the agent component in the solution, select More commands (⋮), and then select See solution layers.

   

4. Select the unmanaged layer, and then select Remove unmanaged layer.

   

If your agent doesn't have Dynamics 365 capabilities enabled, the message is always displayed.

Configure inactivity timeout to close conversation

Dynamics 365 Customer Service expects a conversation to end after a period of inactivity. This feature is important to ensure the supervisor view displays the correct ongoing conversations and manages agent loads and metrics correctly. When you create an agent from Dynamics 365 Customer Service, the default agent content includes two topics: Session Timeout Reminder and Session Timeout. These topics use the Inactivity trigger to first remind the user, and then close the conversation after a set inactivity timeout value, which can be configured in the topic. But if you create the agent from the Copilot Studio portal, those topics aren't included in the agent. To create them, proceed as follows.

Create a Session Timeout topic

1. Go to the Topics page.

2. Select Add a topic and From blank.

3. Hover the trigger Phrases and select the Change trigger icon.

   

4. Select Inactivity from the list.

5. Select Edit in the Trigger node to configure the inactivity duration.

6. Select the desired duration value from the list. Alternatively, use the Formula option and enter a value in seconds. This value is the amount of inactive time it takes for the topic to trigger.

7. Select the channel it applies to by using the Condition option. For Dynamics 365, under the Condition block, select Select a variable, select the System tab, and Activity.Channel.

8. Select Omnichannel from the dropdown.

9. Finally, add a message, and at the end, add an End conversation node so the conversation ends. Select the Add node icon , point to Topic management, and then select End conversation.

10. Save and publish your agent.

Manage your agent's Dynamics 365 capabilities

1. Go to the Channels page.

2. Under Customer engagement hub, select the Dynamics 365 Customer Service tile.

   Here you can disconnect your agent and find the link to go to the Dynamics 365 Customer Service admin center to view the connection details.

Disconnect your agent from Dynamics 365 Customer Service or disable the connection

If you select Disconnect, the application user that represents the agent in your Dynamics 365 Customer Service instance is disabled. Your agent effectively disconnects from the Dynamics 365 Customer Service environment and stops receiving any traffic from your Dynamics 365 Customer Service instance.

To add your agent back, you must connect it again.

Known limitations

See limitations when using Copilot Studio with the Chat Add-in for Dynamics 365 Customer Service.

Recommended extensions

The following extensions aren't required to hand off to Dynamics 365 Customer Service, but they provide agent authors with a better experience by providing extra variables and actions.

Install Dynamics 365 Copilot Studio extension.

Classic

Prerequisites

• Sign in with an account that has the System Administrator role.
• Have a product license for Copilot Studio and a product license for the Chat Add-in for Dynamics 365 Customer service.
• Environments:
  • Your agent environment and Dynamics 365 Customer Service environment must be in the same geographical region.
  • To use voice capabilities, your tenant and environment must be in these geographies:
    • Asia
    • Australia
    • Canada
    • Europe
    • India
    • Switzerland
    • United Kingdom
    • United States
• Register an application with Microsoft Entra ID.
• For end-to-end capabilities to work as expected, your agent must be published.

Connect your agent to Dynamics 365 Customer Service

Note

If you connected your agent to Dynamics 365 Customer Service engagement before November 2021, the settings on the Dynamics 365 Customer Service tile will look as if they haven't been configured. This is a known issue. It doesn't affect the agent or its Dynamics 365 capabilities. Select Enable to refresh the settings and show the actual connection details.

1. In Copilot Studio, open your agent, and go to the Channels page.

2. Under Customer engagement hub, select the Dynamics 365 Customer Service tile.

3. Select Enable.

   • If the required extensions aren't installed, a message warns you that your agent doesn't have access to the variables, or actions it needs.
   • If you're using Application Lifecycle Management (ALM), you might see a message that we can't determine if Dynamics 365 Customer Service integration is enabled for the environment. For more information, see Agents with Application Lifecycle Management.

4. Under See the environment this bot is connected to, select the environment where you have Dynamics 365 Customer Service integration turned on. Your agent and Dynamics 365 Customer Service must be in the same environment for Analytics for Dynamics 365 Customer Service to work for your agent.

   If you didn't set up Dynamics 365 Customer Service in that environment, a message invites you to begin a trial.

5. Select See how to register a new Application ID and follow the steps to find or create the app registration for Copilot Studio.

6. On the Azure portal go to App registrations, then select Overview. Copy the Application (client) ID.

7. Return to the Dynamics 365 Customer Service configuration panel in Copilot Studio, and paste the Application ID in the Application ID box.

   Important

   Dynamics 365 Customer Service models agents as "application users." As a result, the Application ID that you use must be unique to your Copilot Studio agent. Reusing an Application ID across agents will cause error code 1004 (DuplicateBotAppId).

8. Select Add your agent.

   Copilot Studio uses a Teams channel to communicate with Dynamics 365 Customer Service. If one isn't turned on, a Teams channel is enabled when you select Add your agent.

9. Select the View details in Dynamics 365 link to continue configuring the agent connection in Dynamics 365 Customer Service.

Important

To test the agent on your custom website, you must use the embed code that's specified in the chat widget you set up in Dynamics 365 Customer Service. If you use the embed code from Copilot Studio, handoff won't work. For more information, see Embed chat widget in your website or portal.

To add voice capabilities after you connect your agent to Dynamics 365 Customer Service, you must disconnect the agent from your Dynamics 365 Customer Service and reconnect it.

Agents with Application Lifecycle Management

If you set up Application Lifecycle Management (ALM) for your agents, and are exporting and importing agents between development (unmanaged) and test or production (managed) environments, you might see a message that we can't determine if Dynamics 365 Customer Service integration is enabled for the environment.

If the agent you exported has Dynamics 365 capabilities enabled, you can ignore this message. The agent continues to work properly. The message will disappear after you export the latest version of your agent from your development environment, and then import it into a targeted test or production environment with managed agents.

If you continue to see the message after you export and import the latest version of your managed agent, make sure to remove any unmanaged layers:

1. Sign in to Power Apps and select the managed agent's environment.

2. In the navigation menu, select Solutions, and then select the solution that contains the agent with the unmanaged layer.

3. Next to the agent component in the solution, select More commands (⋮), and then select See solution layers.

   

4. Select the unmanaged layer, and then select Remove unmanaged layer.

   

If your agent doesn't have Dynamics 365 capabilities enabled, the message is always displayed.

Manage your agent's Dynamics 365 capabilities

1. Go to the Channels page.

2. Under Customer engagement hub, select the Dynamics 365 Customer Service tile.

   Here you can disconnect or disable your bot, refresh the connection, or open the Dynamics 365 Customer Service admin center to view the connection details.

Disconnect your bot from Dynamics 365 Customer Service or disable the connection

If you select Disconnect bot, the application user that represents the bot in your Dynamics 365 Customer Service instance is disabled. Your bot is effectively disconnected from the Dynamics 365 Customer Service environment.

To add your bot back, you need to connect it again, starting at Step 3.

If you select Disable, the connection between your Dynamics 365 Customer Service instance and Copilot Studio is disabled. Your bot stops receiving any traffic from your Dynamics 365 Customer Service instance.

Refresh the connection

If you select Refresh, the connection between your bot and the Dynamics 365 Customer Service instance is tested and verified.

It's a good idea to refresh the connection after you add your bot to a Dynamics 365 Customer Service workstream to make sure that the connection was successful.

Voice-based capabilities

The Copilot Studio telephony extension adds several actions and variables to Copilot Studio.

Select Enable voice to turn voice capabilities on or off for the entire bot, not for individual bot sessions or connections. When voice is enabled, any connection with the bot can use voice, text, or both voice and text.

Important

If an agent is connected to an Dynamics 365 voice workstream or queue and takes calls, and the voice is disabled, the calls will start to fail. Ensure that the agent is disconnected from Dynamics 365 workstreams or queues before you disable voice in the Copilot Studio configuration.

Set survey consent

Use this action to ask callers if they're willing to take a survey at the end of their call.

1. Add the action.

2. Select Add input for destination topic, and then select surveyConsent (boolean).

   

3. Select Yes or No, or enter a custom response.

   

Set customer locale and handoff to Dynamics 365 Customer Service

Use this action to ask callers for their preferred language.

1. Add the action.

2. Select Add input for destination topic, and then select customerLocale (string).

   

3. Select a variable that defines the locale code, or enter a locale code.

   Refer to the list of languages supported in Dynamics 365 Customer Service for valid locale codes. Only a subset of these languages is supported in Copilot Studio. For more information, see Supported languages.

   

Send uninterruptible voice message

Use this action to send a voice message that the caller can't interrupt.

1. Add the action.

2. Select Add input for destination topic, and then select UninterruptibleMessage (string).

   

3. Select a variable that defines the message content, or enter a message.

   

Transfer the call to a different phone number

Use this action to transfer the call to a different phone number.

1. Add the action.

2. Select Add input for destination topic, and then select TargetPhoneNumber (string).

   

3. Select a variable that defines the phone number to transfer the call to, or enter a phone number.

   

   Warning

   Don't add a plus symbol, "+", before the phone number.

   The phone number you enter must have the Make calls privilege. Without it, transfers to the number will fail.

Hang up

Use this action to end the call.

Add the action.

bot.CustomerPhoneNumber

This variable contains the customer's phone number, also known as CallerID.

You can use the "Is Empty" condition with bot.CustomerPhoneNumber to find out the customer's communication channel. If the conversation is from a call, "Is Empty" always returns False. If it's from messaging, "Is Empty" always returns True.

bot.OrganizationPhoneNumber

This variable contains the phone number the customer dialed.

Dynamics 365 variables

Dynamics 365 Customer Service provides more context variables for Copilot Studio agents.

Authoring considerations

Authentication isn't supported for voice-based handoff to Dynamics 365 Customer Service instances. If you set up authentication for your agent, the authentication variables don't include authentication information when they're sent to your Dynamics 365 Customer Service instance.

Warning

For voice-based handoff capabilities to work, both your agent and Dynamics 365 Customer Service environments must be hosted in a datacenter in the United States, Canada, Europe, United Kingdom, Asia, or Australia geographies. Otherwise, voice capabilities don't work, and you don't receive any error messages or warnings.

If your agent incorporates adaptive cards, make sure you use Bot Framework Composer so that the voice agent correctly reads their speak property.

If your topics include markdown content, the voice agent reads the asterisk (*). Adjust your markdown content accordingly, and always test your agent using voice to make sure you get the desired result.

Known limitations

See limitations when using Copilot Studio with the Chat Add-in for Dynamics 365 Customer Service.

For limits on the size of variables that are shared with Dynamics 365 when Copilot Studio transfers the conversation, see Copilot Studio maximum channel data message size limits.

Recommended extensions

The following extensions aren't required to hand off to Dynamics 365 Customer Service, but they provide bot authors with a better experience by providing extra variables and actions.

Typically, the extensions are automatically installed in your Dynamics 365 Customer Service environment. However, if the environment that you connected Dynamics 365 Customer Service to isn't the same environment your agent is in, you need to manually install the extensions.

Text and voice handoff

For both text and voice handoff, install the following extensions in this order:

1. Power Virtual Agents telephony extension
2. Dynamics 365 Copilot Studio extension
3. Dynamics 365 Voice Copilot Studio extension

Text (messaging) handoff

For only Text (messaging) handoff, install Dynamics 365 Copilot Studio extension.

After installing the Dynamics 365 Copilot Studio extension, if you still see a message warning you that your agent doesn't have access to the variables and actions it needs for voice calling, and you don't need voice capabilities, you can safely ignore it.