Microsoft Teams Integration

Contents

Overview of the integration
Notes
Caution
Integration process
Step-by-Step Integration Process
List of files to download

Caution: Use the Teams Developer Portal to deploy your Azure Bot app in MS Teams. This is because App Studio has been phased out by Microsoft from 31 December 2021 onwards.

To help you set up this integration, you can download the relevant documentation. Open url.png See List of files to download

Note: Microsoft Azure is constantly evolving. As such, some of the screens shown in the procedures below may be different from the ones in the final interface.

Overview of the integration

Microsoft Teams integration enables you to add a Service Bots virtual agent to Microsoft Teams. Users and corporate employees will both be able to communicate with this virtual agent.
Integrate bot in Teams - Discussion example.png

This is performed via two products.

Azure Bot Service: Microsoft Azure service specially designed for developing bots using Azure Bot apps. Bots are connected to channels in order to make them available in different solutions, including the MS Teams platform.

Microsoft Teams: A collaborative platform that enables discussions among users or teams within a given company. These discussions can also be with a bot, and in particular with the Service Bots virtual agent.

Notes

The avatar of the Service Bots virtual agent in MS Teams has a hexagonal shape that is easily identifiable.

Teams avatar.png

Users can search for the virtual agent by name in the search field at the top of the MS Teams window if they belong to a team where the Azure Bot app is installed. If this is not the case, they can search for the virtual agent in the MS Teams app catalog and run the Azure Bot app.
Depending on the scope of the Azure Bot app, the virtual agent may be mentioned in a team discussion using the @shortname instruction.

Caution

The integration requires a configuration outside Self Help and Service Bots.
- You must first ensure that the different platforms are able to communicate.
- Proxies may prevent the integration from working correctly.

Integration process

You can integrate a Service Bots virtual agent in Microsoft Teams in four steps:

Step 1: Create an Azure Bot app in Azure Bot Service

Step 2: Associate the Service Bots virtual agent with the Azure Bot app in Self Help

Step 3: Test the Service Bots virtual agent in MS Teams

Step 4: Deploy the Azure Bot app in MS Teams

Step-by-Step Integration Process

Prerequisites

1. The Service Bots virtual agent must first be created.

Open url.png See How to create a virtual agent

2. The Self Help projects associated with the Service Bots virtual agent must be accessible to the user, AuthenticatedUser.

3. The different platforms used in the integration must be able to communicate.

Create an Azure Bot app in Azure Bot Service

Step 1: Create a new Azure Bot app

1. Log in to the Microsoft Azure portal.

2. Click More services to the right of the services displayed. Next, select Categories > AI + Machine Learning in the menu pane.

3. Select Bot Services in the right pane and click + Create in the toolbar.

4. Click Load more at the bottom of the page and select the Azure Bot service.

5. Click Create.

Azure - Create bot app - Azure Bot.png

The window for creating the new app will appear.

Step 2: Enter information on the new Azure Bot app

1. Enter information on the app.

Azure - Create bot app - Bot informations.png

Bot handle: Unique ID of the bot.
example ezvsample

You cannot modify this value once the bot is created.
Copy the ID and paste it in your text editor in order to store it temporarily. It will be required when specifying the Service Bots endpoint and when associating the virtual agent with the Azure Bot app.

Subscription: Name of your subscription to the Azure service.

Resource group: Resource group associated with the Azure solution.

You can click Create new to create a new one.

Pricing tier: Pricing tier of your subscription to the Azure service.

F0: Free-of-charge usage.
S1: Usage with an SLA.

Microsoft App ID:

Type of App: Select the relevant option, i.e. Multi Tenant or Single Tenant.
Note: If you select Single Tenant, the tenant ID will be required when associating the virtual agent with the Azure Bot app.

Creation type: Select Create a new Microsoft App ID.

2. Click Review + Create.

Correct the errors, if any.

3. Click Create.

A summary of the information will appear.
The Azure Bot app ID and secret (password) will be generated.
The Azure Bot app will be deployed on the Azure portal.

Step 3: Specify the Service Bots endpoint

1. Click Go to resource.

2. Select Configuration in the menu pane.

Azure - Create bot app - Bot informations - Messaging endpoint.png

3. Specify the Messaging endpoint field.

Replace the values highlighted in yellow with the values of your environment.

{ServerAddress}: Address of the Self Help server where the Service Bots virtual agent was created.
{BotHandle}: Bot ID. Copy and paste the ID you stored in your text editor when creating the app in step 2.

https://{ServerAddress}/selfhelp/api/servicebots/msteams-agents/{BotHandle}

4. Click OK.

Step 4: Retrieve the new Azure Bot app ID and secret (password)

Step 4.a: Retrieve the app ID

1. Copy the Azure Bot app ID in the Microsoft App ID field and paste it in your text editor in order to store it temporarily. It will be required when associating the virtual agent with the Azure Bot app and when deploying the app in MS Teams.

Azure - Create bot app - ID copy.png

Step 4.b: Generate and retrieve the client secret

Note: The client secret that was automatically generated when the new Azure Bot app was created cannot be copied. You must create a new one.

1. Click Manage next to the Microsoft App ID field.

Azure - Create bot app - Secret manage.png

2. Click + New client secret at the top of the Client secrets section.

Azure - Create bot app - Secret display.png

The window for creating a client secret will appear.
Azure - Create bot app - Secret add.png

3. Enter the description and expiry date of the new client secret.

4. Click Add.

The client secret of the new Azure Bot app will be generated.
The window for creating the client secret will close.
The new client secret will appear in the list of client secrets.

5. Copy the client secret displayed in the Value field and paste it in your text editor in order to store it temporarily. It will be required when associating the virtual agent with the Azure Bot app.

Azure - Create bot app - Secret copy.png

6. Return to the window for creating the new Azure Bot app.

Step 4.c: Retrieve the Azure Bot app tenant ID

Note: Only if you selected the Single Tenant option in the Microsoft App ID > Type of App field.

1. Select Configuration in the menu pane.

2. Copy the tenant ID in the App Tenant ID field and paste it in your text editor in order to store it temporarily. It will be required when associating the virtual agent with the Azure Bot app.

Azure - Create bot app - App Tenant ID copy.png

Associate the Service Bots virtual agent with the Azure Bot app in Self Help

1. Select Channels > MS-Teams in the Online Studio menu.

2. Click Create an association.

3. Specify the information related to the new Azure Bot app.

Self Help - Association informations.png

Virtual Agent: Select the Service Bots virtual agent you want to associate with MS Teams.

Microsoft App ID: Copy and paste the Azure Bot ID you stored in your text editor when creating the app in step 4.a.

Microsoft client secret: Copy and paste the client secret you stored in your text editor when creating the Azure Bot app in step 4.b.

Microsoft Type of App: Select Single Tenant or Multi Tenant depending on the option you selected when creating the Azure Bot app in step 1.2.

Microsoft Tenant Id: (Note: Only if you selected the Single Tenant option) Copy and paste the tenant ID you stored in your text editor when creating the Azure Bot app in step 4.c.

Microsoft Bot Handle: Copy and paste the bot ID you stored in your text editor when creating the app in step 2.

Skin: Skin used for Self Help procedures that are displayed in the virtual agent's side pane (Dialog Friendly metadata = False).

4. Click Associate.

The virtual agent will be associated with MS Teams via the Azure Bot app.
Information on the Azure Bot app will appear in the Details pane when you click the name of the virtual agent.

Test the Service Bots virtual agent in MS Teams

Step 1: Test the virtual agent using the Web Discussion channel

1. Go to the Azure portal.

2. Select the new Azure Bot app.

3. Click Test in Web Chat.

A conversation panel will appear to the right.
Azure - Web app chat channel.png

4. Check that the Azure Bot app interacts correctly by typing different messages in the conversation panel.

Step 2: Test the virtual agent using the MS Teams channel

1. Add the MS Teams channel to the list of channels.

Select Channels > Microsoft Teams.

Read the terms of use and click Accept.

Select the Microsoft Teams Commercial option and click Apply.

2. Display the new MS Teams channel.

Return to the overview in the Channels window.

Click Open in Teams in the Microsoft Teams channel .

A discussion will open in the Teams app or Online Teams.

3. Check that your virtual agent is able to interact correctly by initiating a team conversation.
Integrate bot in Teams - Discussion example.png

Deploy the Azure Bot app in MS Teams

Step 1: Create a new Teams app associated with the Azure Bot app

1. Log in to the Teams Developer Portal.

2. Select Apps in the menu pane and click + New app in the toolbar.

Deploy bot in Teams - Apps list.png

The window for creating the new Teams app will appear.
Deploy bot in Teams - App information.png

3. Enter the name of the new Teams app.

4. Click Add.

Step 2: Configure the new Teams app

Step 2.a: Specify general information

1. Specify the information on the new Teams app.

Deploy bot in Teams - App configuration - Basic information.png

App names:

Short name: Name of the Teams app displayed in the MS Teams search. This is similar to the name of an employee.
Full name: Text displayed after the name. This is similar to the job title for an employee.

App ID: Automatically generated unique ID of the Teams app.

Descriptions: Long and short descriptions of the Teams app. This will be displayed in the app catalog.

Version: Version number of the Teams app.

Developer information:

Developer or company name: Name of the Teams app developer.
Website: URL of the website associated with the Teams app. Note: URLs must use the SSL protocol.

App URLs: URLs of pages displaying the privacy statement and terms of use. Note: URLs must use the SSL protocol.

Application (client) ID: Copy and paste the Azure Bot app ID (Microsoft App ID) you stored in your text editor when creating the app in step 4.a.

Microsoft Partner Network ID (optional): Specify the ID of the partner in the Microsoft Partner Network (MPN).

Best Practice icon.png Enter ID 5377006 to identify your new Teams app as an EasyVista app in Microsoft. This will enable you to enjoy Microsoft monitoring and support.

2. Click Save.

Step 2.b: Configure the visual identity of the virtual agent

1. Select Configure > Branding in the menu pane.

Deploy bot in Teams - App configuration - Branding information.png

2. Define the virtual agent icon, shape and background color.

3. Click Update to download the files.

Note: Files must be in PNG format.

Step 2.c: Configure the bot functionality

1. Select Configure > App features in the menu pane. Click Bot in the right pane.

Deploy bot in Teams - App configuration - App features - Bot.png

The configuration window will appear.
Deploy bot in Teams - App configuration - App features - Bot information.png

2. Specify the information on the bot in Teams.

Identify your bot: Select the Enter a bot ID option. Copy and paste the bot ID (bot handle) you stored in your text editor when creating the app in step 2.

What can your bot do?: Select the actions your bot can perform.

Select the scopes: Select the relevant options for the bot's scope.

Personal: This enables users to have a direct conversation with the virtual agent.
Team: In team channels where the Teams app is installed, this enables users to mention and communicate with the virtual agent using the @shortname instruction.
Group Chat: In a conversation with several participants, this enables users to mention and communicate with the virtual agent using the @shortname instruction.

3. Click Save.

4. (optional) Enter the predictive text that will be suggested to users.

Note: The predictive text will be suggested to users in the conversation panel and will trigger actions when clicked.

Click Add a command.

Deploy bot in Teams - App configuration - App features - Bot information - Add command.png

The window for configuring the command will appear.
Deploy bot in Teams - App configuration - App features - Bot - Command information.png

Specify the information on the new command.
- Command: Enter the predictive text, i.e. text displayed in the conversation panel.
  example Help
- Description: Description of the action triggered by the command.
  example Display help procedure
- Select the scopes: Select the relevant options for the bot's scope.
  - Personal: This enables users to have a direct conversation with the virtual agent.
  - Team: In team channels where the Teams app is installed, this enables users to mention and communicate with the virtual agent using the @shortname instruction.
  - Group Chat: In a conversation with several participants, this enables users to mention and communicate with the virtual agent using the @shortname instruction.