Microsoft Teams Bot (Non-App Store) Setup Guide

Suggest Edits

This guide will walk you through the process of setting up a Microsoft Teams bot for Moveworks. Along the way, you will capture the following information to provide to your Customer Success team.

Microsoft Graph App ID
Microsoft Graph Tenant ID
Microsoft Graph Secret Value
Teams Application Link (to retrieve the app GUID)

The Customer Success team will provide a secure email that you can use to transfer the above information to Moveworks.

Pre-requisites

Ensure that you have a Microsoft Azure Pay-As-You-Go subscription already setup (or some other subscription)
1. The subscription must be applied under the global subscription filter.
2. If it is not, search for the Directory + Structure configuration page and enable the subscription so that it shows up globally.
Ensure that you have administrative rights to the main tenant in Microsoft Azure console
1. This includes the ability to create resource groups under the above subscription.
Ensure that you have a Teams administrator who can create and manage applications and set policies
Ensure that you have an App Service Plan created so that you can create the resource successfully and avoid the Cannot create a v2 converged app error.

Capturing the Tenant ID

You can find the Tenant ID prior to the call by visiting the following URL. Replace <domain_name> with your company domain name.

https://login.microsoftonline.com/<domain_name>/.well-known/openid-configuration

You will receive a JSON response. Look for the key token_endpoint and find the Tenant ID in the url.

{"token_endpoint":"https://login.microsoftonline.com/<tenant_id_here>/oauth2/token" ….

Create the AzureBot in Your Tenant

Navigate to https://portal.azure.com/#create/Microsoft.AzureBot
Fill out the information as follows:
1. Bot handle - should be named the bot name that was approved.
  1. You can use “Moveworks” as a placeholder if this has not been decided.
2. Subscription - This should default to "Pay-as-you-go” or another subscription that you have available.
3. Resource Group - Create new group for the bot.
4. Resource Group Location - Choose lowest latency.
  1. For example: "West US 2" if you are on the west coast, or "East US 2" if you are east coast based.
5. Pricing tier - Set this to F0 (this is a free tier).
  1. Note: While the licensing structure is pay-as-you-go for messages in premium channels, it is unlimited for standard channels such as MS Teams. Therefore when choosing F0 as the pricing tier, the bot resource does not cost anything and the bot will not incur any additional fees (resource groups are also free). For more information, see this page.

Messaging Endpoint leave this blank for now and we will revisit it later in the configuration.
Under Microsoft App ID,
1. Type of App - select Multi Tenant for the selection.
  1. Multi Tenant is a required setting, since many of the Microsoft Teams backend endpoints use botframework.com as the domain.
Select Create new Microsoft App ID and hit Review + create
1. You will see “Validation Passed“.
2. After reviewing the selections, hit Create and your deployment will be in process.

Configure the AzureBot settings

Find the Azure Bot bot that was created by waiting for the deployment to finish and then clicking on the “Go to resource” button. Or, by searching for the bot in the Azure console.

Navigate to Bot Profile on the left hand pane.
Upload the approved bot icon to the Icon field.
1. Note: The bot icon MUST be 30x30 or 50x50, otherwise the icon will not reflect properly in Teams.
Set the Display name of the bot to the approved bot name or set this to “Moveworks” temporarily.
Click Apply.
Navigate to Configuration on the left hand pane.
1. Copy the Microsoft App ID
Add the following URL based on your region (where is the string in the "Microsoft App ID" you copied in the above step).
1. US Region: https://app.moveworks.ai/<MSappId>/api/messages
2. EU Region: https://app.am-eu-central.moveworks.ai/<MSappID>/api/messages
3. Canada Region: https://app.am-ca-central.moveworks.ai/<MSappID>/api/messages
4. Australia Region: https://app.am-ap-southeast.moveworks.ai/<MSappID>/api/messages
5. Note: If you are installing your Moveworks bot in a GovCloud, please follow this guide: https://help.moveworks.com/docs/microsoft-teams-bot-gcch-access-requirements
  
  ⚠️
  Only use non "US Region" messaging endpoints if your Azure tenant and Moveworks installation are explicitly not hosted in the US region.
  If you have any questions please reach out to your Moveworks team.
Add the Microsoft Teams Feature Channel
1. Navigate back to your Azure bot configuration.
2. Select the Channels tab on the left. Beneath Add a feature channel, select the Microsoft Teams icon and on the next screen, click Save.

Grant API Permissions to Microsoft Graph token associated with the AzureBot

Generate Secret

Under the AzureBot settings, click on Manage (shown in parenthesis beside the Microsoft App ID title).
Then click on Certificates and Secrets on the left hand pane.
Under Client Secrets select the New client secret option.
Enter a name such as “Moveworks Bot” and set an expiration date, we recommend 2 years. Please provide the Moveworks team with the exact date of expiration.
Copy the Secret value and save it to provide to the Moveworks Customer Success team via secure email.
1. Make sure you do not skip this step as the Client Secret value will be blocked from plain text view after.

Add API Permissions

Navigate to API Permissions on the left hand pane.
Select Add a Permission and choose Microsoft Graph.
On the Request API Permissions screen, select MS Graph.
Select Application permissions instead of Delegated permissions for all below permissions in Steps 5-6.
Add the necessary permissions for the Teams bot.
1. User.Read.All
2. TeamsAppInstallation.ReadWriteSelfForUser.All
(Optional) If you are utilizing the O365 integration in Moveworks, please add the following permissions:
1. Provision access to/create Office 365 groups:
  1. Group.ReadWrite.All
2. Display end-user facing Sharepoint articles as an IT knowledge base:
  1. Sites.Read.All
3. To direct users to apps or device actions in the InTune Company Portal:
  1. DeviceManagementApps.Read.All
Ensure all permissions have admin approval granted. Once granted the green check mark should appear.

Verify the Azure Manifest

Navigate to the Manifest section and verify signInAudience is set to AzureADandPersonalMicrosoftAccount and accessTokenAcceptedVersion is set to 2.

Provide the Credentials to the Moveworks Customer Success team

If you have not received the secure email, contact your Moveworks Customer Success team and let them know that you have completed the MS Teams bot setup in Azure. They will provide a secure email requesting the following:

Microsoft Graph App ID
Microsoft Graph Tenant ID
Microsoft Graph Secret

Add the Bot to Your Organization in Teams

After providing the Customer Success team with the necessary information, you will need these assets to publish the app:

color.png - the color bot icon (192 x 192)
outline.png - the sidebar outlined bot icon (32 x 32)
manifest.json - the bot configuration

Using the following file template to create the manifest.json file, replace the <MSAP_ID> and <BOT_NAME> text in the template below, with your Microsoft App ID and the name of your bot respectively. If you have not decided on a name yet, you can use the name “Moveworks” as a temporary placeholder name.

{
    "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.12/MicrosoftTeams.schema.json",
    "manifestVersion": "1.12",
    "version": "1.0.0",
    "id": "<MSAP_ID>",
    "packageName": "com.moveworks.bots",
    "showLoadingIndicator": false,
    "developer": {
        "name": "Moveworks.ai",
        "websiteUrl": "https://www.moveworks.ai",
        "privacyUrl": "https://www.moveworks.com/privacy-policy",
        "termsOfUseUrl": "https://www.moveworks.com/terms",
        "mpnId": "6107273"
    },
    "icons": {
        "color": "color.png",
        "outline": "outline.png"
    },
    "name": {
        "short": "<BOT_NAME>",
        "full": "<BOT_NAME>"
    },
    "description": {
        "short": "An artificial intelligence chatbot that can assist you with IT-related issues.",
        "full": "Hi! I am <BOT_NAME>, an artificial intelligence (AI) chatbot that can assist you with IT-related issues. I can answer IT questions and help manage any service requests you have."
    },
    "accentColor": "#000000",
    "bots": [
        {
            "botId": "<MSAP_ID>",
            "scopes": [
                "personal",
                "team"
            ],
            "supportsFiles": false,
            "isNotificationOnly": false
        }
    ],
    "permissions": [
        "identity",
        "messageTeamMembers"
    ],
    "validDomains": [
        "*.moveworks.ai",
        "*.moveworks.io",
        "*.moveworks.com",
        "*.*.moveworks.ai",
        "*.*.moveworks.io",
        "*.*.moveworks.com"
    ],
    "webApplicationInfo": {
        "resource": "https://moveworks.ai",
        "id": "<MSAP_ID>"
    },
    "configurableProperties": [
        "name",
        "shortDescription",
        "longDescription",
        "smallImageUrl",
        "largeImageUrl",
        "accentColor",
        "developerUrl",
        "privacyUrl",
        "termsOfUseUrl"
    ]
}

Prepare the Assets For Microsoft Teams.

Zip the color.png, outline.png, and manifest.json files into a single zip file.

Example color.png file:

Example outline.png file (the file is transparent, so hard to see):

Tip: You can right click and save the example images in .png format as placeholders if the bot avatar has not been finalized yet.

Notes:

This must be done on the same operating system that you will add the application from.
- If the files are zipped on a Mac, they must be uploaded to the Microsoft Teams app on a Mac. Vice-versa for Windows systems.

Do not place the items into a folder before zipping. Simply select the three files and compress them.

Do not rename any of the files - the Teams client will expect the files to be named as listed above.

Deploy the Bot to Microsoft Teams

Open the Microsoft Teams Desktop App.
Click Apps (on bottom left corner).
Click Manage your apps.
Select Upload a custom app and then select the zip file that you generated.
Select Submit an app to your org and then select the zip file that you generated.
Click Install.

Get the Microsoft Teams Application GUID

Go back to the apps section of Microsoft Teams.
Click on Built for your org.

Select your new bot
Click the link icon to Copy link

Send this link to your Customer Success team so that they can retrieve the GUID from it.

(Optional) Apply a Custom App Policy

Moveworks is able to ensure that the bot’s functionalities are only accessible by approved users during development. The bot will be visible in the MS Teams app store but users will not be able to communicate with it.

In some cases our customers would like to have more granular control over this access. You can do this in the Microsoft Teams Administration Console.

Navigate to https://admin.teams.microsoft.com/.
Go to the dashboard on the left → Select Teams apps> Setup policies -> Add New Policy.
Create a custom app policy to allow the bot you just created.
1. NOTE: If a user is assigned a custom policy, that policy applies to the user. If a user isn't assigned a custom policy, the global policy applies to the user. This means if the org is using custom app setup policies already, then you will need to add the bot to all the app setup policies.
2. Please ensure that your Customer Success team is aware of any custom policies.

Pre-launch Steps

The steps below should be completed when the bot is ready for go-live.

Pin the App to the Microsoft Teams Sidebar

Pin for all employees

Visit admin.teams.microsoft.com.
From the options on the left, select Teams apps ⇨ Setup policies.
Click on the Global (Org-wide default) policy and then click Edit.
Toggle the order of the apps so that the installed bot application is below the Chat option.

Pin Teams app for a specific group of users

Visit admin.teams.microsoft.com.
From the options on the left, select Teams apps ⇨ Setup policies.
Click on the + Add button to create a new Teams app setup policy (more info here: https://docs.microsoft.com/en-us/MicrosoftTeams/teams-app-setup-policies)
Toggle the order of the apps so that the installed bot application is below the Chat option.

Now you can select which users you want this specific policy to apply to. There are two options here - manual method and a Powershell method.
1. Option A: Manually enter users to add to the policy
  1. Go back to the Setup policies page, select the newly created App setup policy and click Manage Users.
  2. Enter the names of users you want the policy to apply to. Click Apply..

Option B: Create policy for a specific group of users in Azure using Powershell
1. Locate your group in Azure that you want to apply the policy to. Copy the object id for the group.
2. Open Powershell and enter the following commands. Once complete this can take up to 72 hours to take effect, depending on the size of the group. See here for more information.
```
New-CsGroupPolicyAssignment -PolicyType TeamsAppSetupPolicy -GroupId <group_id> -PolicyName "Moveworks Bot Users" -Rank 1

Get-CsGroupPolicyAssignment -GroupId <group_id>
```
  Replace the group_id with the correct value above. The group_id is the Azure object id and “Moveworks Bot Users” is the name of the policy you used in the previous step.Example based on above:
```
New-CsGroupPolicyAssignment -PolicyType TeamsAppSetupPolicy -GroupId 57cdf267-5ab7-43bc-b7ad-4c55cc905e40 -PolicyName "FirstLineWorker" -Rank 1

Get-CsGroupPolicyAssignment -GroupId 57cdf267-5ab7-43bc-b7ad-4c55cc905e40
```

FAQ

Q: Can a user unpin the bot in Teams?

A: Moveworks Bot can be unpinned from the sidebar in Microsoft Teams by the user.

Q: What's the behavior in Teams?

A: Moveworks Bot will remain removed from the current Teams session, however once the user logs out of teams and logs back on the app setup policy kicks in and re-adds Moveworks Bot.

Q: Can a user move the left sidebar icon around?

A: user can move the Moveworks Bot around in the left side bar, however the App Setup Policy will overwrite this once the user logs off and logs back onto teams.

Q: What should I do if I get an error when uploading the bot?

A: Try using Microsoft’s App Validation tool, this will tell you if there are any issues with the package you are uploading.

Contacting Us

You can reach the Customer Success team anytime at [email protected] or over the support channel we establish in your team’s messaging platform.

Updated 21 days ago