Microsoft Teams Integration
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.
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.
- 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.
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.
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.
- 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.
- Type of App: Select the relevant option, i.e. Multi Tenant or Single Tenant.
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.
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.
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.
2. Click + New client secret at the top of the Client secrets section.
The window for creating a client secret will appear.
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.
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.
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.
- 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.
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.
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.
The window for creating the new Teams app will appear.
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.
- 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).
2. Click Save.
Step 2.b: Configure the visual identity of the virtual agent
1. Select Configure > Branding in the menu pane.
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.
The configuration window will appear.
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.
The window for configuring the command will appear.
- 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.
- Command: Enter the predictive text, i.e. text displayed in the conversation panel.
- Click Save.
The new command will be added to the list.
Step 2.d (optional): Integrate the portal in a Teams conversation tab
1. Select Configure > App features in the menu pane. Click Personal App in the right pane.
.2 Click Create your first personal app tab.
The window for configuring the tab will appear.
3. Specify the information on the new tab.
- Name: Name of the tab in the Teams conversation.
- Entity ID: Automatically generated unique ID of the tab.
- Content URL: URL of your portal.
- Website URL (optional): URL of your website.
4. Click Add.
Step 3: Install the Teams app and test the bot
1. Click Preview in Teams in the toolbar.
- The Teams app or Online Teams will run.
- The window for installing the app will appear.
2. Click Add.
- The chat window of the virtual agent will appear.
- The predictive text command will be displayed.
Step 4: Add the new Teams app to the list of Teams apps for the company.
1. Click Publish in the toolbar.
2. Select Publish to your org.
The publication window will appear.
3. Click Publish your app.
- The publication process will run.
- The request status will be displayed.
4. Ask the Teams administrator to validate the Teams app and make it available to all company employees.
See Microsoft documentation > Validate