Configure Microsoft Teams

The article outlines the steps required to set up Microsoft (MS) Teams as a chat Channel for Luma. Once the setup is complete, users will be able to send and receive messages from Luma using Microsoft Teams. 

Pre-requisites

Before configuring the Teams, provide permission to Custom apps in your organization.

To do so, follow the below steps:

• Login to your Microsoft Teams account through the URL https://admin.teams.microsoft.com. As an administrator, you can configure and manage app permission policies in the Microsoft Teams admin center. You can apply organization-wide settings, use the global (organization-wide default) policy, and create and assign custom policies to individual users or users in a group.

  Open

  

• On the Global app permission policies page, click Org-wide app settings to configure the required settings.

• Under Third-party apps, adjust the following settings to control access to third-party apps:

  1. Allow third-party or custom apps in Teams: This controls whether users can use third-party or custom apps. This must be turned on for the Luma Custom App to work.

  2. Allow any new third-party apps published to the store by default: This controls whether new third-party apps published to the Teams app store are automatically available in Teams. You can only set this option if you allow third-party apps. This can be turned off and is not required for the Luma Custom App.

• Under Custom apps, turn on Allow interaction with custom apps. This setting controls whether users can interact with custom (sideloaded) apps. Note that this is different from allowing users to upload custom apps. This must be turned on for the Luma Custom App to work. 

• Click Save for org-wide app settings to take effect. 

Open

Configurations on MS teams

Earlier Apps Studio, now Developer Portal on MS Teams, lets you create and distribute line-of-business applications that were built specifically for your organization. The following steps will walk you through creating an application on the Microsoft Teams portal and configuring the same to connect to your Luma instance.

Create Application

First step is to create an application on MS Teams. The application will be configured as a Bot for your organisation and will connect to your Luma instance . To create the application on MS team, do the following:

1. Log in to MS Teams https://teams.microsoft.com/. Sign in to the Microsoft Teams client with an account that has either the global administrator or Microsoft Teams service administrator role enabled to publish apps for your organization. Learn more about using administrator roles to manage Teams.

2. On Left hand navigation, click on the more button. Search and select Developer Portal from the list.

3. On Developer Portal, navigate to Apps. This tab lists the bot available for your organisation through MS Teams.
   Click on 'New app' to start building the app to connect to Luma.
   Add ‘Name’ for your app. This is the name for your Bot and is visible to the end-users in MS Teams. The app is now available on the portal.

4. You will now be redirected to App Details page. Add the below mandatory details to create and configure the application:

   1. Under Basic Information→ App names, add Short Name and Full Name for your app in App Name section. Short Name is used to identify the bot on MS teams.

   2. In Descriptions section, Add Short Description and Full description for your App. The two descriptions should be detailed and different.

       

   3. Scroll down to the Developer Information section and add Developer details . Enter bot developer name and a valid website URL.

       

   4. On the App URLs section, add URLs to your Privacy statement and Terms of Use.

   5. Now, click on Save to save the app details. A sucess message appears “App <app name> updated successfully“.

5. Now Navigate to the Branding section to set the icons for your bot.

   1. Upload a Color icon image in .png format (192x192) . This is your application icon and appears at the top of the chat channel.

   2. Upload another image for the Outline icon in .png format (32x32). This is your application icon that appears in the left hand navigation.

6. Details will be auto saved.

Setup bot

Now that your application is created, next steps is to add bot capabilities for your application. Follow the below steps to configure your application to connect to your Luma instance.

1. On the App features tab, select the Bot tab.

2. Click on the ‘Create a new bot’ link to create a new Bot.

3. Alternatively, you may navigate to Developer Portal → Tools menu and click on Bot Management.

4. Click on ‘New Bot’.

5. Add the Bot name. This is the name for your bot in MS Teams. This is how users will identify the bot in MS Teams once all the configuration steps are completed. Bot Name is not editable once created.

6. The Bot is now successfully created. System autogenerates Bot Id. This id will be used in Channel configuration in Luma. Copy and save the id for use in later steps.

7. Next step is to add the Endpoint Address. This refers to your Luma instance, the bot should connect to.

   1. Follow the below steps to obtain the endpoint URL from Luma Virtual Agent

      1. Login to your Luma Bot builder instance as an administrator.

      2. Navigate to Bot → Configurations → Channels.

      3. Click on Microsoft Teams tile.

      4. On Configure Channel page, copy the Message URL.

         Note: We can also use the ‘https://dev.teams.microsoft.com/bots/<BOT_ID>/configure’

   2. On MS Teams, under Bot Management, select your bot and navigate to Configure tab.

   3. Paste the Endpoint URL (copied in the step 4) in Configure → Bot endpoint address and click Save.

8. Next step is to generate a secret key for MS Teams and Luma to communicate. Navigate to Client Secrets tab.

9. Click on 'Add a client secret for your bot'.

10. A new client secret key is generated. Copy and save the key for use in later steps. This Secret Key will be used for channel configuration in Luma.
    Note: The secret key is visible only once and cannot be viewed again. Ensure that you copy and retain the key in a text editor for future use.

Bot Permission Setup

Once the Bot is ready, the next step is to provide required permissions to the Bot, so that it can communicate with your Luma Virtual Agent tenant. To do so, follow the below steps:

1. Navigate to Developer Portal → Apps and select your App.

2. On the App Features → Bot tab,

   1. Under Identify your bot, select the bot created in the above steps.

   2. In case, you do not find your bot in the dropdown,

      1. Find the Bot ID via the Azure Portal (refer to steps 1-5 in section- Configuration on Azure Portal ).

      2. Copy the Bot ID/Application Client ID.

      3. Select ‘Enter Bot ID’ and paste the Bot ID

   3. Under What can your bot do?, select “Upload and download files” . This allows file attachment through your Bot.

   4. Under 'Select the scopes in which people can use this command', select Personal. This represents the scope in which people can use this command.

   5. Click Save.

   6. Now navigate to the Domains tab and all the valid domains supported for your organization.

       

Configurations on Azure Portal

Once your application on MS Teams is ready, next step is to assign Permissions to your application to communicate with Luma. Follow the below steps to assign the required permissions.

1. Login to Azure Portal with admin credentials.
   https://portal.azure.com/

2. Alternatively, you can directly connect to Azure portal by navigating to Tools → Identify Platform management (preview) --> Open in Azure.

3. Select App Registrations from Azure Services list.

    

4. Now on All applications list, search for your application. You application is identified by the Bot name. (You can also search using the BOT ID)

5. Click on your application to view application details. You are now on application overview page. The Application (client) Id here is the same as system generated Bot ID in Setup Bot → Step 6.

    

6. Now, navigate to API permissions and click on Add a permission button to request permissions for your application to communicate with Luma.

    

7. On Request API permission screen, Click on Microsoft Graph.

8. Click Application permissions,select the below permissions:

   1. Under User, select User.Read.All

       

   2. Under AccessReview, select AccessReview:Read.All

       

   3. Under Directory, select Directory.Read.All
      
      

       

   4. Click on Add Permissions to update permissions for your application. Requested permissions will now appear in the API Permission list. Click 'Grant admin consent' button. 

   5. The system now prompts a message to grant consent for requested permissions. Click Yes to update.
      
      

       

   6. Once the permissions are added, the Success message "Successfully granted admin consent for the requested permissions." will appear.

       

9. All required permissions have been assigned to your application.

10. Navigate to Manifest

11. Modify the value for the accessTokenAcceptedVersion to Value 2 and ‘Save’ the Manifest file

Note: This may take several minutes to get the update reflected.

Enable MS Teams in Luma

The last step in the configuration is to enable MS Team in Luma. Follow the below steps to configure MS Team chat channel on Luma.

1. Log in to your Bot builder UI for your Luma instance with Administrator credentials. Navigate to Bot → Configurations → Channel Configuration tab.

2. Click on Microsoft Teams.

3. On Configure channel page, add the following details:

   • Add App ID. This is the Bot ID auto-generated by MS teams in Setup Bot → Step 6. The ID is also available on the App Overview page on the Azure portal. Copy and paste Bot ID in App ID field on Luma UI.

• Add Password. This is the Secret Key or Password auto-generated by MS teams in Setup Bot → Step 10. Copy and paste the Password in the Password field on Luma UI.

• On User Reconciliation for Channel Authentication, select the fields for user reconciliation in Field Name. Click on Set.
  This step is to set fields to be used for user Auto Authentication through the channel. You may select multiple fields, sorted in order of validation.
  
  

• Toggle the Status button to set to Active.

• Click Save.

The Channel is now configured.

MS Teams is now configured for your tenant.

Test your App

Once the configuration is complete, test your App to verify it can connect to your Luma tenant. To do so:

1. Visit the following link and sign in with your credentials. Your Bot should be available in the list. It may take some time to load for the complete list of bots.
   https://dev.botframework.com/bots

2. Select your Bot and click on Microsoft Teams on Connect to Channel.

3. Next, launch the Bot with MS Teams.

4. The Bot should now be available in your Teams

5. Send a ‘Hi’ message to the Bot from Teams. The Bot should connect to the tenant and respond with the configured Suggest skills.

6. The Conversation should also be available in Bot builder → Conversation history.

Publish your App

Once the App has been tested successfully, publish the app to be available for all organization users.

1. Navigate to MS Teams → Developer Portal.

2. Under Apps, select your app and click on Publish.

3. On the pop up, click on ‘Publish to your Org’.

    

4. Click on Publish your App.

5. Your app is now submitted for approval from the administrator. Once approved, the Bot will be available in your Teams store under 'Built for your Org'.

Troubleshoot

Question: The user appears Anonymous and not auto-authenticated.

Answer: Following are the reasons why a user may not be auto-authenticated:

1. The User (user’s email address) is unavailable as a Registered user in Luma Virtual Agent. You may contact your Luma administrator to add the user.

2. Multiple users in Luma Virtual agent are available with the same email. You may remove the duplicate accounts.

3. The App ID and Client ID does not have the required permissions. Verify the permissions as in Step → Configurations on Azure Portal.

Question: If you are facing issue with the error “AADSTS700016: Application with identifier '68dafaa0-5755-4433-8f47-3e174c5ed131' was not found in the directory 'Bot Framework'. This can happen if the application has not been installed by the administrator of the tenant or consented to by any user in the tenant. You may have sent your authentication request to the wrong tenant.”

Answer: Follow the steps

1. Go to your Azure portal and navigate to Azure Active Directory.

2. From there, go to "App registrations" and select your app.

3. Next, click on the "Authentication" tab.

4. In the "Supported account types" section, switch between "Single Tenant" and "Multi-tenant" options.

5. After making the changes, try accessing your bot again. Your bot should now be back online.

Now, navigate back to the "Supported account types" section and select either Single-tenant or Multi-tenant, depending on your preference.