Configure hand-off to Dynamics 365 Customer Service

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

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

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

Prerequisites

Connect your bot to Omnichannel for Customer Service

Note

If you connected your bot to omnichannel engagement before November 2021, the settings on the Omnichannel tile will look as if they haven't been configured. This is a known issue. It doesn't affect the bot or the omnichannel connection, which will continue to run normally. Select Enable to refresh the settings and show the actual connection details.

  1. In Power Virtual Agents, edit your bot. In the left panel, select Settings, Agent transfers, and then select the Omnichannel tile.

    The bot management Agent transfers page.

  2. Select Enable.

    • If the required extensions aren't installed, you'll see a message that your bot doesn't have access to the variables or actions it needs.

      Message at the top of the Omnichannel configuration pane that says your bot doesn't have access.

    • If you're using Application Lifecycle Management (ALM), you may see a message that we can't determine if omnichannel integration is enabled for the environment. For more information, see Bots with ALM.

  3. Under See the environment this bot is connected to, select the environment where you have omnichannel integration turned on. If you haven't set up Omnichannel for Customer Service in that environment, you'll see a message inviting you to begin a trial.

    Message that says you haven't set up Omnichannel integration in this environment.

  4. Select See how to register a new Application ID and follow the steps to find or create the app registration for Power Virtual Agents.

    The Omnichannel configuration pane, with the Application ID section highlighted.

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

  6. Return to the Omnichannel pane in Power Virtual Agents and paste the Application ID in the Application ID box.

    Important

    Omnichannel for Customer Service models bots as "application users." Therefore, the Application ID that you use must be unique to your Microsoft Dataverse organization or environment.

  7. Select Add your bot.

    Power Virtual Agents uses a Teams channel to communicate with Omnichannel for Customer Service. If one isn't turned on, a Teams channel will be enabled when you select Add your bot.

  8. Select the View details in Omnichannel link to continue configuring the bot connection in your omnichannel interface.

Important

To test the bot on your custom website, you must use the embed code that's specified in the chat widget you set up in Omnichannel for Customer Service. If you use the embed code from Power Virtual Agents, hand-off won't work. For more information, see Embed chat widget in your website or portal.

To add voice capabilities after you've connected your bot to Omnichannel, you must disconnect the bot from your omnichannel service and reconnect it.

Bots with ALM

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

Message that we can't determine if this bot has Omnichannel enabled or disabled.

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

If you continue to see the message after exporting and importing the latest version of your managed bot, make sure to remove any unmanaged layers:

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

  2. In the left pane, select Solutions, and then select the solution that contains the bot with the unmanaged layer.

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

    Selecting solution layers in Power Apps.

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

    Remove unmanaged layer in Power Apps.

If your bot doesn't have omnichannel capabilities enabled, the message will always show.

Manage your bot's omnichannel capabilities

Select Settings, Agent transfers, and then select the Omnichannel tile. Here you can disconnect or disable your bot, refresh the connection, or open the Omnichannel admin center to view the connection details.

Disconnect your bot from omnichannel or disable the omnichannel connection

If you select Disconnect bot, the application user that represents the bot in your omnichannel instance is disabled. This effectively disconnects the bot from the omnichannel environment.

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

If you select Disable, the connection between your omnichannel instance and Power Virtual Agents is disabled. Your bot will stop receiving any traffic from your omnichannel instance.

Refresh the connection

If you select Refresh, the connection between your bot and the omnichannel instance is tested and verified.

It's a good idea to refresh the connection after you add your bot to an omnichannel workstream to make sure that the connection was successful.

Voice-based capabilities

The Power Virtual Agents telephony extension adds several actions and variables to Power Virtual Agents.

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.

List of voice-related actions that can be added to a node in Power Virtual Agents.

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).

    Add a Set survey consent action to a node in Power Virtual Agents.

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

    Set the response choice for the Set survey consent action.

Set customer locale and handoff to omnichannel

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).

    Add a Set customer locale and handoff to omnichannel action to a node in Power Virtual Agents.

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

    Refer to the list of languages supported in Omnichannel for Customer Service for valid locale codes. Only a subset of these languages is supported in Power Virtual Agents. For more information, see Supported languages.

    Set the response for the Set customer locale and handoff to omnichannel action.

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).

    Add a Send uninterruptible voice message action to a node in Power Virtual Agents.

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

    Set the input for the Send uninterruptible voice message action.

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).

    Add a Transfer the call to a different phone number action to a node in Power Virtual Agents.

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

    Set the phone number for the Transfer the call to a different phone number action.

Note

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.

  1. Add the action.

    Add a Hang up action to a node in Power Virtual Agents.

bot.CustomerPhoneNumber

This variable contains the customer's phone number. It's 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 Power Virtual Agents bots.

Authoring considerations

Authentication isn't supported for voice-based hand-off to omnichannel instances. If you've set up authentication for your bot, the authentication variables don't include authentication information when they're sent to your omnichannel instance.

Warning

For voice-based hand-off capabilities to work, both your bot and omnichannel environments must be hosted in a datacenter in the United States, Europe, Asia, or Australia geographies. Otherwise, voice capabilities don't work, and you won't receive any error messages or warnings.

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

If your topics include Markdown content, the voice bot will read the asterisk (*). Adjust your Markdown content accordingly, and always test your bot using voice to make sure you get the desired result.

Known limitations

See limitations when using Power Virtual Agents with the Chat Add-in for Dynamics 365 Customer Service.

The following extensions are not required to hand-off to Omnichannel, but they provide bot authors with a better experience by providing additional variables and actions.

Typically, the extensions are automatically installed in your omnichannel environment. However, if the environment that you connected omnichannel to is not the same environment your bot is in, you'll need to manually install the extensions.

For both text and voice hand-off

Install the following extensions in this order:

  1. Power Virtual Agents telephony extension
  2. Omnichannel Power Virtual Agent extension
  3. Omnichannel Voice Power Virtual Agent extension

For only text (messaging) hand-off

Install Omnichannel Power Virtual Agent extension.

If you still see the following warning after installing the Omnichannel Power Virtual Agent extension, and you don't need voice capabilities, you can safely ignore it.

Screenshot of the yellow warning that can be ignored.