Handoff to a live agent using Microsoft Teams

Using Microsoft Teams as a channel for live agent handoff is a great option for organizations that are already using Microsoft Teams as their primary messaging application. Typically agents prefer to manage end-user conversations using the Teams client application they are already familiar with.

Handoff to an agent using Microsoft Teams

Using Microsoft Teams as a handoff channel for live agents requires additional configuration. Before configuring this feature you should first be familiar with the standard handoff functionality. Learn more

Handoff with Microsoft Teams exposes agent functionality that is similar to the agent experience in the agent webchat application. Agents using Teams also benefit from integrated MS Teams video calls, which can seamlessly transition text conversations to rich voice or video interactions.

Screen shot of an agent creating a Teams video link

Agents simply use the "meeting" command to generate and send a teams meeting link to the end user.

Steps to configure Handoff using Microsoft Teams


Global admin permissions for your organizations Azure Active Directory are required to complete this setup

  1. Enable the Teams channel for your Health Bot instance

    In the management portal for your Health Bot instance navigate to Integration > Channels > Microsoft Teams and enable the teams channel. Learn more about enabling the Microsoft Teams channel

  2. Create a security group to authorize agents

    An Azure Active Directory (AAD) security group is used to authorize agents. Define a security group and add the members that should be allowed to login as agents. Only the agents in the group will be authorized to interact with the agent experience in MS Teams.

    To create a security group open your organizations Azure portal. Navigate to AAD > Groups and create a new group. Learn more about creating security groups in your Azure Active Directory

    Make note of the Object ID for your agent security group.

    Security group object ID

  3. Register an Enterprise application

    In the Azure portal navigate to your organizations AAD and create a new App Registration. Learn more about creating an app registration

    Take note of the Directory ID and Application secret that are required for the configuration

    Directory ID and Application ID

    Enable the relevant permissions for the application and ask a Global Admin for the organization to "Grant Admin consent"

    API permissions and Admin consent

    The following Microsoft Graph API permissions are required for this feature:

    • Directory.read.all
    • Group.read.all
    • OnlineMeetings.readwrite.all
    • User.read
  4. Generate a client secret

    Navigate to the Certificates & Secrets for the App Registration. Create a new client secret and copy the secret to your clipboard.

    Client secrets

Update the Teams configuration

You are now ready to add the AAD details you have collected in the previous steps to your Health Bot configuration.

  1. Open the Health Bot management portal and Navigate to Configuration >> Conversation > Handoff >> Microsoft teams.
  • Make sure "Handoff" is enabled

  • Add the IDs and Secrets to the Agent authentication section

  1. Add a default user for Teams Video calls (optional) When creating Teams meeting links the logged-in agent is assigned as the meeting organizer by default.

    In some cases Teams users do not have appropriate permissions to create a Teams meeting and then the default meeting organizer will be assigned.

    Get the Object ID for the user from your organizations active directory. Navigate to the user list and copy the ID from the users profile.

    Screen shot of user object ID in Azure portal

Create an agent login scenario

Agents need to be logged in to the agent experience by the bot. The bots login scenario needs to be mapped to a language model before you can use it.

  1. In the Health Bot management portal navigate to Languge >> Models >> New. Create a new language model

  2. Set the model to the RegEx method and create a regex pattern that will trigger the login scenario

  3. Map the model to the built-in agent login scenario.

    screenshot of the agent login language model

  4. You can now test the agent experience. Open your bot in Microsoft Teams and type "login". If you are part of the Agent security group, the bot will authorise you as an agent and show the agent options.

    screen shot of the agent login experience

You have completed the configuration required for using Handoff with Microsoft Teams.