Creating a New Bot for Teams

This article focuses on the steps required to start developing a new Bot and taking the first steps to publishing this Bot into Teams.

We are going to take you through the first steps of (1) creating the Web App Bot in Azure, (2) connecting this to the Code your Bot is going to run, (3) defining your Bot’s Manifest and uploading into Teams, before (4) testing the Bot in Teams and looking forward.

Before we start, a Quick Word on Client App IDs

Before we get started, we can take a quick look at Client IDs.

These IDs identify Apps within the Microsoft Cloud and so we typically find *everything* we do has a Client ID, and that it will be one of the key variables we have to supply to facilitate communication between Apps.

We saw how this works for an Azure App Registration to communicate with Dynamics, and now we will see this in action for the new Bot we create.

When we create our Web App Bot in Azure – this will be given a Client ID for the Bot. This Client ID represents the identifier for our App (in this case, a Bot) in the Cloud – and can be used alongside the Client Secret to communicate with the App, particularly so that other Apps can pass or receive messages with the App.

We can see this Client ID in Azure:

This must then match the manifest of our Bot in Visual Studio, as this is the manifest that we pass to Teams so that the App that is Teams can communicate with the App that is our Bot to bring the two together:

This allows the connection between how we publish our code into Azure to control what the Bot does for us, and how we upload the manifest into Teams to connect our Bot into Teams.

With that in mind – we are going to look at this process step by step:

(1) Defining a New Bot Service in Azure

To get started with this approach, we can use the following steps to create ourselves a new Web App Bot and connect this into Teams:

In Azure, we can create a new Bot Service and then select Web App Bot as the type of Service we want to create:

This will then let us set the name and parameters for our new Bot:

Bot Handle

The Development Name for our Bot

Pricing Tier

For Development purposes, we can use the F0 Free Pricing Tier.

Bot Template

Initially we can leave this as the default Echo Bot C# template

App ID and Password

We can leave these to auto-create so that Azure generates us a new Client ID and secret.

This will then create our Bot in Azure – this is created in two components, the Web App Bot definition and behind it the App Service.

We can see both in our Resources List in Azure:

This means that we the container that we can publish our code into directly from Visual Studio.

At present this is just a ‘generic’ bot in a way and so not connected to Teams.

In Azure, we can add the Channel connection to add the link between our Bot in the Cloud and Teams:

This will ask us the type of Teams we can connecting with, and confirm our consent for Teams and the Bot the exchange information.

Once done, we can see the connection running for our Bot App.

(2) Deploying our Bot Project into the Bot Service

Now we have the Bot defined, we will want to publish some of our custom logic into the Bot and start seeing the Bot contribute to our Business Logic within Teams.

The best place to start is a good initial HelloWorld style Bot or other Template that we use before we start adding our bespoke logic in.

In a previous article in this series, we look at our starter Bot Project here and can use this Visual Studio Project to get started – there is also the Microsoft Teams Bot Example Project available via GitHub here.

Once done and we have our starter Bot in Visual Studio – we can then deploy our code from Visual Studio into the Bot Service in Azure.

Publishing to Azure is built into the DNA of Visual Studio these days and so is easy to manage through the options in Publish:

This will deploy our Bot to the App Service as the container for our code – which is connected to the Web App Bot that manages the chat communication and the channel connector we have setup between our Bot and Teams.

We can actually test our Bot outside of Teams using the Test in Web Chat area in Azure and this gives us a means of Unit Testing that our code is uploading correctly and we have the foundation in place.

However our Bot is looking to work with Teams and so take the Teams Message and other inputs into its execution, which means that chances are it won’t do much outside of Teams!

So our next step is to see the Bot in Teams.

(3) Building our Manifest Package for Teams

Adding a Bot into Teams means connecting the intended instance of Teams to the logic running in our App Service in Azure – the Channels connection defines that our Bot is able to connect to Teams, but the Manifest Package is the Solution File that we upload into a particular Teams Instance to add our Bot into that Channel or set of Channels in a Team.

To do this, we have to build our Manifest XML and package up for Teams.

My preference is to do this in our Visual Studio Project so we can define the XML in the same Project as the core logic, and so we can see a Folder containing an example manifest in our starter project – but this is not absolutely necessary, the Manifest XML and Images Files can be built entirely independently of the Visual Studio Project Files depending on preference.

Drilling into our XML here:

The key element initially is ensuring we insert our Application Client ID into both the ‘id’ tag and the ‘botid’ tag – this will inform Teams on upload of the Manifest of your connection to the container in Azure.

We must also supply a Short Name, Full Name and icons for the Bot.

Finally we define the Commands that the Bot makes available – this is the list of commands that are shown in Teams Chat as what’s possible.

The article here drills into the full detail of the Manifest File in relation to a Teams Bot.

However whilst we are getting up and running, the main areas for each are ensuring we have our Client ID correct and we have the details of the Bot Name and Icons ready to go.

Once we have this – we can compress our Manifest files into a ZIP and use this ZIP to upload our Bot into Teams.

Zip up the Files in our Manifest Folder and we are ready to go!

(4) Add our Bot to Teams

Right – we’ve done all our steps to build up to getting our Bot into our instance of Microsoft Teams.

We do this by opening Teams (Web or Desktop is fine here) and navigating into More Apps:

Here we have options to add various commercial or publicly available Apps to how we use Teams.

We also have an option for Upload a Customised App that allows us to add our bespoke developed App into Teams – and this is the option we want here to add our new Bot into Teams.

NOTE: To do this, you will need to be a suitably powerful Admin who is allowed to add Apps to Teams in Teams Global Policy Settings – otherwise the Upload a Customised App option will not appear

This will ask us for our Manifest ZIP file and we can supply this to add our Bot into Teams.

When it’s not quite right – we will get a Parsing Error that will ask us to format the Files or Structure in our ZIP, or the XML Content in our Manifest File, and usually we will have one or two loops to get it right as any files or unexpected content will prompt Teams to reject it!

But once its gone in right – we will see our App installed into Teams.

We are not quite done yet as we still need to add our new Bot into 1 or more Teams. (this step can be automated using Graph API but for now, we can do manually)

To add our Bot, we click on the App here and this will present an option for Add to a Team, which we can use to then select a Team and make our Bot available in all the Channels for that Team.

Now we can test our Bot.

Moving into a Channel in the Team, we can start a new Chat in the Channel with @SSO or the Short Name of our Bot and this talks to the Bot – this will offer us the list of commands possible for the Bot, as dictated from our Manifest File.

NOTE: We can have additional commands in the code of our Bot, just that only those well defined in the Manifest will appear to the User as ‘what can I do’.

We can now run our commands and see the outcome of our custom code running within Teams:

In the case of this simple example, coming from the code here:

Example Action

WhoAmI Action

These being invoked from our central OnMessageActivityAsync Method in the main TeamsConversationBot.cs code:

This shows the connection from Teams to our logic in Azure and ultimately the code we have published to run there.

What Next?

Looking forward, now we have our Bot added to Teams, we can update our code and simply publish to our Azure Web App to add new functionality or implement changes.

Publishing to Azure being our only required step to release new changes.

(so I would always recommend having Dev, Test and Live instances of your Bot so you can have an effective release cycle – particularly as any changes will be immediately published to all instances of the Bot, and this could be many Teams or even many Clients depending on how widespread your Bot is installed!)

But from my side, we’ve got our Bot, now we want to do something more exciting with it – and coming from my background, that means start thinking how our Bot can work with Dynamics 365 and Power Automate.

So our next article here is going to take a dive into the code and how we can start adding Business Logic into our Bot.