This guide will walk you through the process of setting up a Moveworks AI Assistant in Microsoft Teams. Along the way, you will capture the following information:

1. Microsoft Graph App ID
2. Microsoft Graph Tenant ID
3. Microsoft Graph Secret Value
4. Teams Application Link (to retrieve the app GUID)

Once you have these items, add the connector in Moveworks Setup by following this guide: System Connectors.

Pre-requisites

1. 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.
2. 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.
3. Ensure that you have a Teams administrator who can create and manage applications and set policies
4. 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.

Ensure Proper Networking Allowlist Rules

If you are leveraging a Firewall, CASB, or VDI, and have another layer of network firewall rules. Ensure the following Moveworks owned domain is in an allowlist so that Moveworks can render content in Microsoft Teams Task Modules.

• https://app.moveworks.ai

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 Azure Bot in Your Tenant

1. Navigate to https://portal.azure.com/#create/Microsoft.AzureBot

2. Fill out the information as follows:

   1. Bot handle - should be named the AI Assistant 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.

3. Messaging Endpoint leave this blank for now and we will revisit it later in the configuration.

4. Under Microsoft App ID,

   1. Type of App - select Single Tenant for the selection.

      

5. 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 Azure Bot settings

Find the Azure 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.

1. Navigate to Bot Profile on the left hand pane.

2. 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.

3. Set the Display name of the bot to the approved AI Assistant name or set this to “Moveworks” temporarily.

4. Click Apply.

5. Navigate to Configuration on the left hand pane.

   1. Copy the Microsoft App ID

6. Add the following URL based on your region (where<MSappId> 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 AI Assistant in a GovCloud, please follow this guide: /ai-assistant/chat-platform-experiences/microsoft-teams/ai-assistant-in-microsoft-teams-gcch-setup-guide

      Only use non “US Region” messaging endpoints if your Moveworks tenant is not hosted in the US region.

      If you have any questions please reach out to your Moveworks team.

      

      
      

7. 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

1. Under the Azure Bot settings, click on Manage Password (shown in parenthesis beside the Microsoft App ID title).
2. Then click on Certificates and Secrets on the left hand pane.
3. Under Client Secrets select the New client secret option.
4. 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.
5. Copy the Secret value and save it in a secure place.
   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

1. Navigate to API Permissions on the left hand pane.
2. On the Request API Permissions screen, select MS Graph.
3. Select Application permissions instead of Delegated permissions for all below permissions in Steps 5-6.
4. Add the necessary permissions for the Teams bot.
   1. User.Read.All
   2. TeamsAppInstallation.ReadWriteSelfForUser.All
5. (Optional) If you are utilizing the Microsoft 365 integration in Moveworks, please add the following permissions:
   1. Provision access to/create Microsoft 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
6. Ensure all permissions have admin approval granted. Once granted the green check mark should appear.

Configure in Moveworks Setup

Next you will add the Teams and MS Graph connector to Moveworks Setup by following this guide: System Connectors, using the following information:

• Microsoft Graph App ID
• Microsoft Graph Tenant ID
• Microsoft Graph Secret

If you are connecting multiple Teams tenants to a single Moveworks organization, refer to the Multi-Tenant Moveworks Setup Guide for guidance on naming and mapping your connectors.

Follow implementation steps in this guide. The configuration is similar whether you are connecting a single tenant or setting up a multi-tenant environment.

Add the AI Assistant to Your Organization in Teams

You will need these assets to publish the app:

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

Using the following file template to create the manifest.json file, replace the <MSAP_ID> and <AI_ASSISTANT_NAME > text in the template below, with your Microsoft App ID and the name of your AI Assistant 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": "<AI_ASSISTANT_NAME>",
        "full": "<AI_ASSISTANT_NAME>"
    },
    "description": {
        "short": "AI Assistant for enterprise data, automation, and info retrieval.",
        "full": "Hi! I am <AI_ASSISTANT_NAME>, an artificial intelligence (AI) Assistant that can find answers, automate tasks, and boost productivity."
    },
    "accentColor": "#000000",
    "bots": [
        {
            "botId": "<MSAP_ID>",
            "scopes": [
                "personal",
                "team"
            ],
            "supportsFiles": true,
            "isNotificationOnly": false
        }
    ],
    "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 AI Assistant 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 AI Assistant to Microsoft Teams

1. Open the Microsoft Teams Desktop App or navigate to the Microsoft Teams App in your browser.
2. Click Apps (on bottom left corner).
3. Click Manage your apps.
4. Select Upload a custom app and then select the zip file that you generated.
5. If you are an Admin of Teams, select Upload an app to your org’s app catalog.
   1. If not, select Submit an app to your org.
6. Select the zip file that you generated.
7. Click Install.

Get the Microsoft Teams Application GUID

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

3. Select your new bot
4. Click the link icon to Copy link

5. The URL has the GUID required to set up the chat bot surface, as described here: /ai-assistant/ai-assistant-overview/configure-moveworks-assistant#/

(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 AI Assistant 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.

1. Navigate to https://admin.teams.microsoft.com/.

2. Go to the dashboard on the left → Select Teams apps> Setup policies -> Add New Policy.

3. Create a custom app policy to allow the AI Assistant 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 AI Assistant to all the app setup policies.

Pre-launch Steps

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

Pin the App to the Microsoft Teams Sidebar

Pin for all employees

1. Visit admin.teams.microsoft.com.

2. From the options on the left, select Teams apps ⇨ Setup policies.

3. Click on the Global (Org-wide default) policy and then click Edit.

   

4. Toggle the order of the apps so that the installed AI Assistant application is below the Chat option.

Pin Teams app for a specific group of users

1. Visit admin.teams.microsoft.com.
2. From the options on the left, select Teams apps ⇨ Setup policies.
3. 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)
4. Toggle the order of the apps so that the installed AI Assistant application is below the Chat option.

5. 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..

2. 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 AI Assistant in Teams?

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

Q: What’s the behavior in Teams?

A: Moveworks AI Assistant 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 AI Assistant 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.