Workato docs Return to Workato
Edit this page
GitHub (opens new window)
  • Introduction
  • Getting started
  • Product Updates (opens new window)
  • Concepts
  • Connecting apps
  • Building recipes

  • Running recipes

  • Troubleshooting

  • Data types and formulas

  • Tools
  • Files and attachments

  • Batch processing

  • Teams and collaboration
  • People Task by Workato
  • Recipe lifecycle management
  • On-prem connectivity
  • Key features
  • Workbot for Slack
  • Workbot for MS Teams
  • Workbot for Workplace
  • API Platform
  • Connectors

  • Universal connectors
  • Community connectors
  • Connector SDK
  • Custom OAuth profiles
  • Workato API
  • Security
  • Training & Certification
  • Contact us

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

Multiple app registrations 3 bots installed into 1 Microsoft organization

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

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

Assigned roles Check your assigned roles

# Getting started

To begin, head to Tools ➤ Workbot.

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:
FieldsDescription
Short nameShort name for your bot, e.g. OpsBot.
Full name (optional)Full name of your bot, e.g. Opportunities Bot.
App IDClick Generate to generate an App ID.
Package nameKey in your package name in reverse domain format, e.g. com.workato.your_bot_name.
VersionTypically 1.0.0 if it's a new bot.
Short descriptionGive a short description of your bot.
Full descriptionGive 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.
Websitehttps://www.workato.com
Partner informationOptional, skip.
Privacy statementhttps://www.workato.com/legal/privacy-policy
Terms of usehttps://www.workato.com/legal/terms-of-service
BrandingYou 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.
  1. Give your bot a name.
  2. 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).
  3. 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.
  1. Store the generated password in a safe place.
  2. 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
  1. Go back to MS Teams ➤ App Studio ➤ Manifest editor ➤ Your bot ➤ Capabilities ➤ Bot.
  2. Configure the messaging endpoint field with the Workato messaging endpoint.
2 Whitelist Workato as a valid domain
  1. Go to Finish ➤ Domains and permissions.
  2. 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
  1. Click on +Upload.
  2. Select the downloaded file to upload your bot into your organization’s app store.
  3. 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
  1. 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.
  2. Click on the arrow next to Add and choose Add to team.
  3. 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)
  1. On the top search bar, type in and select App registration.
  2. You should see your bot listed here - click on it.
2 Add the redirect URIs
  1. From the left navigation bar, click on Authentication.
  2. Under Platform configurations, click on +Add a platform ➤ Web.
  3. Enter the following redirect URI:
    https://www.workato.com/auth/skype/callback (opens new window)
  4. 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)
  5. 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
  1. In Workato, go to App connections (opens new window) and create a new Workbot for MS Teams connection.
2 Configure connection
  1. 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.
  2. Under Custom OAuth profile, select the custom OAuth profile you want to use.
  3. Click Connect.
  4. 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
  1. Go to Teams apps ➤ Manage apps.
  2. Click on Org-wide app settings.
  3. Under Third-party apps, ensure that Allow third-party apps is set to On.
  4. Under Custom apps, ensure that Allow interaction with custom apps is set to On.
2 Permission policies
  1. Go to Teams apps ➤ Permission policies.
  2. Click on your org-wide policy.
  3. Under Third-party apps, ensure that Allow all apps is set; alternatively, ensure that your app has been allowed.
  4. Under Custom apps, ensure that Allow all apps is set; alternatively, ensure that your app has been allowed.
3 Setup policies
  1. Go to Teams apps ➤ Setup policies.
  2. Click on your org-wide policy.
  3. Ensure that Upload custom apps is set to On.

← Personal connections Passing parameters →

Didn’t find what you are looking for?
Search our resource library View getting started guides, tutorials, training videos, webinars and FAQ Ask our community View questions and answers from other users and Workato experts. File a support ticket File a support ticket for critical issues that require a higher level of support.
Privacy Terms (844) 469-6752 Workato 2021