What are Custom Workbots?

Custom Workbots are Microsoft Teams apps you create that can leverage the Workato bot platform under the hood. You can fully customize your bot's identity, i.e.:

• Branding (bot name, bot logos, accent color)
• Custom OAuth profile (bot ID, App secret)
• Permissions

These Microsoft Teams apps can then be sideloaded into your Microsoft Teams groups or channels for use by your members.

When would I need custom Workbots?

1. You want multiple, purpose-specific bots in your Microsoft organization. For example, you may want to have HRBot, ITBot, DevOps bots installed within your organization.

3 bots installed into 1 Microsoft organization

2. You want control over your bot's branding, i.e. bot name, bot logos (full color & transparent outline) and accent color,

3. You want control over your bot's permissions. By default, Workbot for MS Teams requests for a minimum set of permissions:
   
   - User.Read,
   - User.Read.All,
   - Group.Read.All,
   - offline_access,
   - TeamsAppInstallation.ReadWriteForUser,
   - AppCatalog.ReadWrite.All
   
   Your enterprise bot can additionally include:
   
   - User.ReadWrite.All,
   - Group.ReadWrite.All,
   - Directory.Read.All,
   - Directory.ReadWrite.All.

Creating a custom Workbot

Prerequisites

Before you begin, ensure that you have been assigned at least one of the following roles in your Microsoft organization:

Application administrator
Cloud application administrator
Global administrator
Privileged role administrator

You can check your role assignments from https://portal.azure.com/ (opens new window) ➤ Users ➤ You (click on your name) ➤ Assigned roles.

Check your assigned roles

Getting started

To begin, head to Tools ➤ Workbot.

If you don't see Workbot, make sure your Workato team or account has access to Workbot

In the Custom tab, at the bottom of the page, click on Create a custom bot.

Missing custom tab

If you don't see the Custom tab, make sure your Workato team or account has access to Custom OAuth profiles

Step 1: Create a bot in Microsoft App Studio

Step 1 is done entirely on App Studio in Microsoft Teams.

#	Steps	Description
1	Install App Studio	In MS Teams, from the left navigation bar, click the ellipsis, then search & install App Studio.
2	Create new app	In App Studio, navigate to the Manifest editor tab, and click Create new app.
3	Key in app details	Key in the following fields in your App details: Fields Description Short name Short name for your bot, e.g. OpsBot. Full name (optional) Full name of your bot, e.g. Opportunities Bot. App ID Click Generate to generate an App ID. Package name Key in your package name in reverse domain format, e.g. com.workato.your_bot_name. Version Typically 1.0.0 if it's a new bot. Short description Give a short description of your bot. Full description Give a long description of your bot. Microsoft will detect and reject your full description if it contains the same text as your short description, so make sure they are different. Website https://www.workato.com Partner information Optional, skip. Privacy statement https://www.workato.com/legal/privacy-policy Terms of use https://www.workato.com/legal/terms-of-service Branding You can (and should) use your own app icons. Just follow the exact dimensions requested by Microsoft. To use the default Workbot icons, right-click and save the following bot images: Full color (192x192 pixels) Transparent outline (32x32 pixels). Image above looks blank, but it's there! Use #108291 as the accent color.
4	Capabilities: Add personal tab(optional)	Click on Add a personal tab and fill in the following fields: Name: Getting started Entity ID: gettingstarted Content URL: https://docs.workato.com/workbot-for-teams/getting-started.html Website URL: https://docs.workato.com/workbot-for-teams/getting-started.html
5	Obtain Client ID	Under Capabilities ➤ Bots, click Set up. Give your bot a name. Under Scopes, select Personal, Team and Group Chat scopes. Once the bot is created, take note of its Bot ID (it’s under your bot name). The Bot ID will serve as your bot’s Client ID. Keep it handy - you’ll need it to configure the custom OAuth profile in Workato.
6	Obtain Client secret	Under App passwords, click on Generate new password. Store the generated password in a safe place. Keep the password handy - it’s your Client secret and you’ll need it to configure your custom OAuth profile in Workato.

Once you've obtained both the Client ID and the Client secret, head back to Workato. Proceed to Step 2.

Step 2: Configure the custom OAuth profile

Steps	Description
1	Under Bot name, key in your bot's name.
2	Under Client ID, copy your Bot ID and paste it into the field.
3	Under Client Secret, copy your App password and paste it into the field.
4	Under Application ID, copy your App ID and paste it into the field.
5	Click Save.

Step 3: Configuring your custom bot to talk to Workato

Copy the Messaging endpoint, and head back to MS Teams App Studio.

#	Steps	Description
1	Configure messaging endpoint	Go back to MS Teams ➤ App Studio ➤ Manifest editor ➤ Your bot ➤ Capabilities ➤ Bot. Configure the messaging endpoint field with the Workato messaging endpoint.
2	Whitelist Workato as a valid domain	Go to Finish ➤ Domains and permissions. Under Enter a valid domain, enter *.workato.com After adding the *.workato.com domain, it will appear under Additional valid domains.
3	Test and distribute: resolve outstanding issues	On the right side of the page, resolve any outstanding issues. If left unresolved, you may run into issues with installation and/or downloading your app package (a.k.a. manifest). These issues are typically related to fields in Details ➤ App details and/or Capabilities ➤ Bots.
4	Test and distribute: download manifest	Click on Download to download your app's manifest into your default download folder. Keep this file handy - you'll need it for the next step.
5	Sideload app: Go to MS Teams admin center	Head over to https://admin.teams.microsoft.com/policies/manage-apps (opens new window)
6	Sideload app: Upload manifest	Click on +Upload. Select the downloaded file to upload your bot into your organization’s app store. In MS Teams, you should then be able to discover and find your bot in the Microsoft tenant app catalog (opens new window) under Built for {your_name}.
7	Sideload app: Add to team or channel	From the Microsoft tenant app catalog (opens new window), find and click on your app. If you do not see your app, sign out & sign in to Teams again. Click on the arrow next to Add and choose Add to team. Type in a team or channel name to add your app to.

Step 4: Configure redirect URLs for authentication

#	Steps	Description
1	Got to portal.azure.com (opens new window)	On the top search bar, type in and select App registration. You should see your bot listed here - click on it.
2	Add the redirect URIs	From the left navigation bar, click on Authentication. Under Platform configurations, click on +Add a platform ➤ Web. Enter the following redirect URI: https://www.workato.com/auth/skype/callback (opens new window) Next, add the following URIs to the list of Redirect URIs: https://www.workato.com/users/auth/skype (opens new window) https://www.workato.com/oauth/callback (opens new window) IMPORTANT: Near the top of the page, click on Save.

Step 5: Establishing a Workbot connection with a custom Workbot

#	Steps	Description
1	Go to App connections	In Workato, go to App connections (opens new window) and create a new Workbot for MS Teams connection.
2	Configure connection	Under Advanced settings, choose the API scope(s) you want to use. By default, the minimum permissions User.Read, User.Read.All, and Group.Read.All will be requested. Under Custom OAuth profile, select the custom OAuth profile you want to use. Click Connect. Authenticate yourself and authorize the permissions when prompted.

Common issues: MS Teams Permissions & Setup policies

If you encounter permissions issues when sideloading your app in the MS Teams admin center (opens new window) or during authentication, please check the following settings in the MS Teams admin center (opens new window).

#	Steps	Description
1	Org-wide app settings	Go to Teams apps ➤ Manage apps. Click on Org-wide app settings. Under Third-party apps, ensure that Allow third-party apps is set to On. Under Custom apps, ensure that Allow interaction with custom apps is set to On.
2	Permission policies	Go to Teams apps ➤ Permission policies. Click on your org-wide policy. Under Third-party apps, ensure that Allow all apps is set; alternatively, ensure that your app has been allowed. Under Custom apps, ensure that Allow all apps is set; alternatively, ensure that your app has been allowed.
3	Setup policies	Go to Teams apps ➤ Setup policies. Click on your org-wide policy. Ensure that Upload custom apps is set to On.