Microsoft Teams Deployment

Understand how to set up and deploy a OneBot App for Microsoft Teams

Written By Ben Lehmann

Last updated 16 days ago

Overview

This document is a guide to creating and setting up a new OneBot app to work with the Microsoft Teams chat client.

There are four stages to creating and setting up OneBot to run inside of Teams:

Create a Teams configuration in the OneBot portal.
Create a new bot inside the Developer Portal.
Create an MS Teams app for the bot.
Distribute the package to your organisation.

Before you begin

Some aspects of the setup happen concurrently, and you will need to transfer information between them during the process. Therefore, it is easier to have both your OneBot service portal and the Teams client open during setup.

Finally, if you do not already have it, you will need to Add the Developer Portal to Teams to create the bot and the app for Teams, or use equivalent functionality provided by the Developer Portal at https://dev.teams.cloud.microsoft/home.

Note

The Microsoft Developer Portal has a toggle option to use the New Developer Portal. However, we find the default portal is more reliable for setting up new Teams bots.

Create a Teams configuration in your OneBot portal

Create a new assistant

Teams Chat clients are created as part of OneBot Assistants. To create a new Teams Chat client, you first need have a OneBot assistant to attach it do. If you don’t already have an assistant, use these steps to create one.

Navigate to the Assistants view using the site navigation on the left of the page.
Click +New button in the top-right.

Select the type of assistant you want from the New Assistant popup, and click Confirm.

Give the assistant a Name and optionally a Description, and click Save.

Create a new Teams Chat client

Select Chat Clients view from left panel.
Click the Create Chatbot plus button.

Select the Microsoft Teams chat client from the popup and click Confirm.

Give the Teams Chat client a Name and optionally a Description, and click Save. This creates the new chat client connection inside of OneBot.

Capture the chat client endpoint

Microsoft Teams communicates with OneBot via an Endpoint. Copy the Endpoint from the chat clients Settings tab in your OneBot assistant to use when creating a new Teams bot app.

Navigate to Settings for the client by selecting the Settings tab.
Click the Copy button to the right of the Endpoint text field and paste it somewhere safe for later use when configuring your Teams bot app.

Create a new bot app

Switch over to Microsoft Teams and open the Developer Portal there, either from the sidebar or by searching for it from the View more apps menu.

Open the Developer Portal

To open the Developer Portal inside Teams, follow these steps.

Click on View more Apps button at the bottom of the side-navigation.
Type developer into the search field.
Click on the Developer Portal app to open it.

Note

Right-clicking on an app in the sidebar will pin it there for easy access.

Create a new bot

Select the Tools tab at the top of the developer portal.
Click Bot Management to open the Bot Management view.

Click + New Bot to add a new bot

Give the bot a name and click Save

This will create your new bot and synchronise it using a new connection to Azure, so you may see a slight delay while this happens.

Configure your new bot

Once your new bot has been created, the first thing is to add the Bot endpoint address copied to the clipboard, earlier.

Paste this endpoint address into the Endpoint address field and click Save. This configures the bot, so it knows where to talk back to.

Working down through the other options in the left side-panel:

Select Channels and make sure to have Microsoft Teams selected.

Leave Meeting event subscriptions empty.

The final configuration stage for your bot is to create a secret for the bot to use as a password for secure authentication.

Note

Once you click away from the secret generation dialogue box, there is no way to view it again. If you find the secret is not copying correctly, or the dialogue closes before you capture the secret, simply generate a new secret to use instead.

Continuing your Bot Configuration:

Click Client secrets to create a new Secret (password) for the bot to use.
Click + Create your first client secret to open the client secret generation dialog. If you already have a client secret configured, use the + New client secret button in the top-right.

Copy the client secret. You will need this in a moment to complete setting up your OneBot Assistant’s chat client for Teams.

❗️ Warning

Be sure to clear the clipboard and dispose of any records of the secret: it can be used to access the Teams client.

Complete Teams configuration in the OneBot portal

Configure your bot’s secure secret

Switch back to your OneBot portal.
Click Change next to the Password text field to open the change password dialog.

Paste the copied secret into the Bot Password and Repeat Bot Password and then click Change to set the password for the Bot.

Configure your bot’s ID

We now need to get the ID for the newly created Bot and add it as the Bot ID for this configuration. This can be tricky: copying it from the Developer Portal involves a little editing.

Switch back to Developer portal. If you left Teams as it was in the prior step, navigate back to see your new Bot by clicking Bots in breadcrumb trail the top-left. Alternatively, you can navigate to see your bots by going to Developer Portal > Tools > Bot Management as before.
Right-click on the Bot Id next to the Bot Name of your bot. (You have to right-click on the actual ID, and not just somewhere in the row.)
Click Copy to copy the entry to the clipboard. This copies the whole row, however, so it needs one more step to capture the Bot ID.
Paste the copied row somewhere, and then select just the Bot ID and copy this to the clipboard.

The final step is to paste the copied Bot ID into OneBot.

Switch back to your OneBot portal
Click the Change button to the right of the Bot ID field.
Paste in the Bot ID and click Change. If it has been pasted in correctly, the Bot ID will appear same as it does in the Bot Management view of the Developer Portal.

Create an MS Teams app for the bot

Create the app

We now need to create the app that will run on your Teams client.

Switch back to Teams and click on the Apps tab at the top of the view.
Click the + New app button in the top-left.

Give your new app a name in the Add app dialogue box that appears.
Click Add to create the app.

Configure basic information

Select Basic information from the left navigation panel in your App’s configuration view.
Give your OneBot App a Short name, found in the App names section.
Give your app a Long name (Optional)
Give it a Short description and a Long description by completing the respective fields.

⚠️ Caution

When naming your app, be aware that both the short and long descriptions will be prominent in the published app and the store, so it is worth getting these right.

Continuing down Basic information:

Leave the Version number as it is. This can be incremented as needed for later releases of the app.
Add the Developer or company name
Add your website address to Website
Add the URL to your company’s privacy policy to the Privacy policy field.
Add the URL to your any terms and conditions to the Terms of use field.
Click Save to finish creating the basic information setup for your app.

Configure branding

What you set here will be what appears in the app for your users. Be careful with the sizes for these options: Microsoft require sizes exactly as detailed on this page.

Select Branding from the left side-panel to setup the branding for your app.

Configure Teams features

Click App features tab in the side-panel to specify the Teams features to include in your app.
Select Bot

Select the bot that you just created from the Select an existing bot dropdown, but leave options under What can your bot do? unselected.
Select Personal under Select the scopes where people can use your bot to give yourself access to it.
Click Save to complete creating your Teams app.

Publish your bot to your organisation

You can preview your bot before distributing it to your organisation.

Preview your bot

Click Preview in Teams in the top-right of the view. You may be redirected via the web.

Click Add in the dialogue box that appears. This will take you into the chat, demonstrating how the app will appear in Teams. (Note: a workflow must be linked to your bot before it will respond to a chat message.)

Publish your bot

To publish the app to your organisation, head back into the Developer Portal in Teams

Select the Apps tab as before
Open the app you just created by clicking on its name.

Click Distribute in the top-right.

This presents a popup allowing you to either:

Download the app package
Publish to you organisation
Publish to the Teams Store (not covered here)

Publish to you organisation

Click Publish to your organisation to distribute your app, provided you have the rights.
In some cases, you will be allowed to publish it but will then need to approve it on the website itself.

Download the app package

Note

If you used the Preview feature from earlier in this guide, your app will already be installed in your Teams client. You may want to remove this preview version if you want to validate the downloaded app package.

Click Download the app package. This will save the file as a zip. file, allowing you to upload it to your Teams client directly.
Keep the file as a .zip file — don’t extract, unpack, or unzip it.
Click on the + Apps button in the sidebar of Teams to being uploading your app directly.
Click Manage your apps from the bottom of the left side-panel
Click Upload an app near to the top of the view.

This will open the Upload an app dialog that will allow you to select the app file.

Select Upload a customised app to select and upload the zipped package from your chosen download location

Click Add from the app dialogue box that appears to add it to your installed applications in your Teams client.
Clicking Open in the popup that appears will take you to your new app in Teams.

The app will be visible on the left sidebar. It can be pinned there to keep it visible as a Teams application by right-clicking on it and choosing Pin from the menu.