Building an App for Microsoft Teams

This article provides step-by-step instructions on how to build a Microsoft Teams App with bot functions. This App must next be connected to the main MI application to be able to access content in Metric Insights and process queries submitted by your MS Teams users.

PREREQUISITES:

1. Create a New Application on the Azure Portal

In the Azure Portal go to Home > App registrations and click [+New registration]

  1. Name: Give the App a descriptive name
  2. Supported account types: Select the "Accounts in this organizational directory only (OneDrive plugin only - Single tenant)" option
  3. Redirect URI (optional): Select the "Web" option in the Platform drop-down menu and leave the URL field empty
  4. [Register]

2. Save the Essentials

This is how a registered App looks like

Make sure to copy the Directory (tenant) ID, Object ID, Application (client) ID and Display name Essentials.

3. Create a Secret Key

On the newly created App page go to Manage > Certificated&secrets

  1. Click [+ New client secret]
  2. Description: Add a short description of the secret
  3. Expires: Select when the secret will expire
  4. [Add]
  5. Check the secret in the list

NOTE: Check the generated manifest (Manage > Manifest> AAD Graph App Manifest tab). Pay attention to values accessTokenAcceptedVersion (it should be set to «AzureADandPersonalMicrosoftAccount») and signInAudience (it should be set to «2»).

4. Create a New App in the Bot Framework

Go to https://dev.botframework.com/bots/new page

  1. Display Name: Give the bot a descriptive name
  2. Bot handle: Add a handle, which is a short abbreviation for the URL of the bot
  3. Message Endpoint: Add an address that points to the server where the MI Chatbot is installed (not the MI Application itself)
  4. App type: Select the "Multi Tenant" option
  5. App ID: Insert the Application (client) ID of the previously created app in the provided field
  6. Set confirmation for User Agreement
  7. Click [Register]

5. Connect the Bot to the "Microsoft Teams" Channel

Open the Channels tab

Click the MS Teams icon in the Add a feature channel section to add MS Teams to channels.

6. Create an App Package

To install and run the application, MS Teams needs a special app package that contains several files describing how the app works. Those files are an App manifest in JSON format and two icons. You can find the full guide on how to create an app package in this article.

6.1. Prepare Application Manifest File

Here is how the App manifest looks like:

  1. id: Paste an Application (client) ID from the created Azure app here
  2. packageName: Give the app package a descriptive name
  3. name: Enter the short and long names of the app here
  4. developer: Type the name of the developer team and add URLs to the company websites
  5. botId: Add an Application (client) ID from the created Azure app here
Manifest example 
{   
   "\$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.12/MicrosoftTeams.schema.json",   
   "version": "1.0.0",   
   "manifestVersion": "1.12",   
   "id": "87632230-a1f5-4f8d-be2b-0f94eff05a30",   
   "packageName": 
   "insightsdemo",   
      "name": {     
      "short": "Insights (demo)",     
      "full": "MetricInsights Chatbot (demo)"   
},   
   "developer": {     
      "name": "MI Python Team",     
      "websiteUrl": "https://demo.metricinsights.com",     
      "privacyUrl": "https://demo.metricinsights.com",     
      "termsOfUseUrl": "https://demo.metricinsights.com"   
},   
   "description": {     
      "short": "MI Chatbot",     
      "full": "Conversation Chatbot for MI Application."   
},   
   "icons": {     
      "outline": "outline.png",     
      "color": "color.png"   
},   
   "accentColor": "#D85028",   
   "staticTabs": [],   
   "bots": [     
   {       
      "botId": "87632230-a1f5-4f8d-be2b-0f94eff05a30",       
      "scopes": [         
         "personal",         
         "team",         
         "groupChat"       
      ],       
      "isNotificationOnly": false,       
      "supportsCalling": false,       
      "supportsVideo": false,       
      "supportsFiles": false     
   }   
   ],   
   "validDomains": [],   
   "showLoadingIndicator": true,   
   "isFullScreen": true,   
      "authorization": {     
         "permissions": {       
            "resourceSpecific": [         
            {           
               "name": "Member.Read.Group",           
               "type": "Application"         
            },         
            {           
               "name": "Owner.Read.Group",           
               "type": "Application"         
            },         
            {           
               "name": "TeamMember.Read.Group",           
               "type": "Application"         
            }       
         ]     
      }   
   } 
}

6.2. Prepare Icons

The App Package should contain a color and outline icon. They will be used in MS Teams for the newly created app. The limitations and requirements for both the colored version of the icon and the outline one are in detail described in the app package creation manual.

6.3. Validate the App Package

Gather an app manifest and two icons into an archived folder. To make sure you did everything right, validate the package in the app validator.

7. Upload the App Package to MS Teams Chat Client

In the Microsoft Teams go to Apps and open Manage your apps

  1. Click Upload an app
  2. Select Submit an app to your org and choose the app package from the PC
    • If you are an administrator, select Upload an app to your org's app catalog

8. Configure MS Teams Connection in Metric Insights

Access Admin > Distribution > Microsoft Teams and open Info tab

  1. Client ID: Insert Application (client) ID from the Azure portal here
  2. Client Secret: Paste the created Secret ID in this field
  3. Tenant: Enter the Directory (tenant) ID here
  4. Bot ID: Insert Object ID in this row
  5. Bot Name: Type the bot's name in this field

Don't forget to [Save].

9. Finish Setting the Chatbot

There are two more steps.

9.1. Synchronize the Teams

Open the Teams tab and click [Sync Teams].

9.2. Enable MS Teams

Go to Chatbot tab and set the Microsoft ID of azure active directory to "true" or "1".

NOTE: If the bot is unresponsive after finishing the steps above, the chatbot container restart may be required.