*THE CONTENT IN THIS ARTICLE IS NOW OBSOLETE. FOR UP-TO-DATE GETTING STARTED INFORMATION PLEASE VISIT OUR DOCS HERE.
So you want to build your own Microsoft Teams app, eh? Well you’re in luck, we’ve got just the sample app to get you started. We call it, appropriately enough, the Microsoft Teams sample Get-Started app.
To get you started with the Get Started app, we wanted to provide you the step-by-step processes you can follow to get up and running yourself, on your machine on your copy of Microsoft Teams. We’re going to walk through the Node.js version of the project; we provide .NET/C# version for those of you thus inclined, and a lot of the steps and techniques will be similar. We’ll walk you through the steps in detail so even you non-programmers can participate. As an added bonus for engineers of all levels, you’ll also get a glimpse into some techniques and tricks you can use when you build your own great Microsoft Teams app that actually does something useful.
The Get Started sample is designed to be a simple all-in-one Teams app for you to play with. It shows many of the current Teams capabilities, all wrapped up into a single project. You can see how a bot, tab, compose extension, and even a connector will work. While this is not the recommended project structure or approach we suggest you take, as you will be leveraging your own services on the platform(s) of your choice, it illustrates a full end-to-end app so you can see what you might want to do in your own project.
Without further ado, let’s get started with Get Started:
Microsoft hosts much of its sample code in GitHub, a web-based Git version control repository. If you’re not familiar with Git or GitHub, we recommend you review the Git documentation and follow the GitHub Hello World guide.
To download this sample from GitHub:
You now have both the Node.js and the .NET/C# source files copied into your local directory.
Next, we need to make sure we get all the required Node.js packages, including the Bot Framework and Bot Framework Teams extension packages:
You now have all the required packages, and are ready to start up your IDE and get the code running:
Microsoft Teams apps can contain one or more capabilities, and the ways to run or even host them may be different. In general, though, we will discuss the following methods of running a Teams app:
Note that none of these testing solutions fully replicates the end user experience for a Store-distributed app, as the app installation process does some of the capability checks, like scope, at install time.
For purely local or local Teams testing, you’ll need to run your experience locally. Note again that the following covers Node.js only.
For most samples, we provide a launch.json config file for ease of debugging within Visual Studio Code. One the Node folder, choose the Debug menu, and select the "Launch" configuration that matches your intent.
Optionally, you can choose to run node directly, in the terminal: from the same directory containing the app.js file, run node app.js to start your app.
Our bot samples are designed to run out of the box within the Bot Emulator. This allows you to test some of the core 1:1 logic of the bot, see rough layout of messages and perform simple tests.
To test in the Bot Emulator, you need to first start your app. Select and run the pre-built “Launch - Emulator” debug configuration. This should launch your bot web service, display a sample web page in your default browser and, in Visual Studio Code’s output window, you should see:
restify listening to http://[::]:3978
Notice the Port number that your bot services is listening on: 3978. By default, we use 3978 for Node.js bots and 3979 for .NET/C#.
Next, launch the Bot Emulator. In the box at the top, you are asked to enter your endpoint URL. This is the endpoint to which the emulator will attach. By default, our bot samples will listen for events with the route path ending in “/api/messages”. For the Bot Emulator, we’ll set our endpoint to be: http://localhost:3978/api/messages. Again, note that we’ll point the emulator to our default Node.js port: 3978. You’d use 3979 if you want to try the .NET/C# sample.
The Bot Emulator will ask you to enter the Microsoft App ID and Microsoft App Password. The values here must match the one you have set in your bot code. In our case, within our “Launch – Emulator” config, we’ve set both values to be blank (“”) so you can keep these blank here, and just hit “Connect.”
Connecting to your service will likely trigger the
conversationUpdate event. A great Teams bot will reply with a welcome message; for our sample bot you should see the following:
Your bot should now work for basic 1:1 messaging. Note that since we are not running within Teams, channel-specific information will not function. In the sample case though, you can try simple commands like “create Make Coffee Task.”
As our Node.js samples use services like Restify or Express, you can also test capabilities like Tabs when you run the sample locally. Simply hit the endpoint directly in your browser via http://localhost:PORT where PORT will be default set by the application, again 3978 for Node.js or 3979 for .NET/C#.
For our sample, let’s check out the routing for our Tabs. Open "/microsoft-teams-sample-get-started/Node/ tabs/tabs.js" file and note the endpoint for one of the tabs is "/tabs/about"
With your app running (via Launch – Emulator or directly in the terminal), open a browser window and go to http://localhost:3978/tabs/about. This should yield the following screen showing that you are running the About tab on localhost.
You can access other endpoints directly as well, and results will depend on the sample. See each sample for more information.
For this particular sample, running the tabs outside of Microsoft Teams is less interesting, so let’s get the sample running inside.
As Microsoft Teams is an entirely cloud-based product, it requires all services it accesses to be available from the cloud. Therefore, to enable our samples to work within Teams, we need to either publish our code to the cloud, or make our local running instance externally accessible. We can do the latter with tunneling software.
While you can use any tool of choice, we use and recommend Ngrok and will use this in our examples below.
Ngrok creates an externally addressable URL for a port you open up locally on your machine. As mentioned, we typically use port 3978 for Node.js and 3979 for .NET. For our sample app, you’ll want to perform the following steps:
By running this locally using a tool like Ngrok, you get to take advantage of such things as step debugging and rapid code iteration. To see this in action though, you need to have something to run against, so let’s register a bot.
Bots in Teams must be built upon the Microsoft Bot Framework. For our samples, as part of the package download process, you’ll get the Bot Framework and in most cases, the Bot Framework Teams extension packages.
In addition, every bot must be registered in the Bot Framework, so it is accessible by the services it uses like Microsoft Teams. Our samples are designed for you to run yourself, so you’ll need to create your own bot identity, which consists of a Microsoft App ID and password. Here’s how:
Next, you need to configure your Bot service endpoint where services like Microsoft Teams will find your running bot instance:
When done with this stage, you’ll return to the Registration page, with the app ID filled in, that matches the one created above. Check the box at the bottom, and click “Register” to create your new accessible Bot Framework bot.
By default, new bots are registered to be accessible by Skype and Web Chat. After registering, you’ll be taken to your bot Channels page. From here, you can select “Microsoft Teams” from the Add a channel list. Simply slide the “Disabled” to “Enabled” and hit Done. This enables your bot to work in Microsoft Teams, once we do the following, of course.
Now that you’ve registered your own bot, you’ll need to make the sample app assume that bot’s identity. This means you’ll need the sample code to use your Microsoft App ID and password when it’s running, so that Teams can validate that it’s talking to the right service.
By default, our Teams app samples expose environment variables you can configure, in one place, to set important information like this. For our projects with a .vscode/launch.json file, you can modify the environment variables stored there. Typical environment variables are:
For this sample, open up the launch.json file and select the “Launch – Teams Debug” block. Replace the above environment variables with the values from your bot registration. Once you run that profile via the Debug option in VS Code, your code will validate that it is the registered bot.
Note: if you choose to run the app directly, via “node app.js” from the command line, you’ll need to set the environment variables in your app.js code directly. For ease of use, though, we recommend you use the launch configuration file provided.
Before we move on, let’s make sure your app is running and registered properly. This is an optional step but one we recommend you try when you're first setting up your environment.
We’re going to leverage the Bot Framework portal to ensure your running code is accessible from the cloud. In your registered bot’s details page, click “Test” – you should be able to type “hello” and get a response – in this case, an “I’m sorry…” response. This response is coming from your local code! Put a breakpoint or two, or even change the response message to prove it. So far so good!
And if that’s not enough, you can also test using the Bot Emulator. Here’s how:
While our sample is designed to be a full app experience with 1:1 and channel bots and tabs, you are far enough along in the process to be able to talk directly to your bot in Teams right now. Here’s how:
Click the Chat icon in the sidebar. In the Search box, paste in the bot’s app ID and press Enter.
At first the bot won’t be displayed in the list. Click the “People” tab underneath the Search box to see your bot in the list. Click on the bot. This should initiate a chat with your bot. Here you can communicate directly with the bot. Type "help" to see the commands available: "create," "find," and "link."
It’s that easy. And once again, note that you are running your local bot code, but accessing in Teams. This is all you need to test basic 1:1 conversation features. However, if you want to actually leverage Microsoft Teams functionality, and make the sample available in channels, you’ll need to create a Microsoft Teams app package.
To get the full Microsoft Teams app experience, you’ll need to create a Microsoft Teams app package, for use in sideloading into a team. Note that this is the same process you would go through if you are opting to create a Microsoft Teams app package for Office Store submission.
A Microsoft Teams app package consists of the following:
(For more details, see the Create the package for your Microsoft Teams app.)
The above gets built into a Zip package, which will then be sideloadable into a team. More on that below.
With our Microsoft Teams sample apps, we have provided sample packages for you, as well as showing you the individual files within. This all should live in the project folder’s “TeamsAppsPackages” subdirectory. Note that in most cases, these packages are not usable as is – you have to register, build, and run it yourself. That’s the point of the samples after all.
The first step is to get your Microsoft Teams app content defined, in the manifest.
The manifest provides Microsoft Teams all the information it needs to work with your app. Find the manifest by going to your subdirectory “\microsoft-teams-sample-get-started\Node\TeamsAppsPackages” and opening manifest.json.
App and Bot IDs
You can keep most of the information in this file, the metadata that describes the app, as is, with a few important exceptions:
Since we’re already here, let’s update the tab URLs to point to our running Ngrok instance. Note that in non-sample real life, you may very well have separate endpoints and services handling your tabs and bots, which is totally fine. For our sample purposes though, we’re providing all app support in one running service, served up to Teams via our Ngrok instance.
Update the contentUrl and websiteUrl for both the static tab and the configurable tab to use your Ngrok instance. Make sure you keep the pathing, e.g. “/tabs/index/”
Add your Ngrok URL to the list of valid domains. (Don't include the protocol; for example, specify "1a2b3c4d.ngrok.io", not "https://1a2b3c4d.ngrok.io".) This is a safety check to ensure a Teams tab doesn’t allow venturing into unknown territory.
Save your new version of the manifest.json, making sure to keep the name as is. We’re on to the next step:
You can simply replace the existing manifest in the zip file we have provided, or you can create your own new zip file package. For the latter, make sure you add the icons, and make sure all content is at the top level of the zip file.
That’s it. You have a suitable sideloadable package. Pick your favorite test team and sideload it.
Since channels depend on the manifest to communicate with your app, you must first sideload your package containing the manifest into Microsoft Teams. To access sideload functionality, you’ll need to go to your selected team’s dashboard: click the “…” next to your team name, and select “View team” from the dropdown. On the team dashboard, click on "Apps," then in the lower right corner, click the "Sideload an app". It will prompt you to navigate to your zip file.
Sideloading your app means that all the capabilities defined therein should be available both in the team you loaded into, and in the personal scope. Let’s verify.
Microsoft Teams has two different types of tabs you can access – teams tabs (currently configurable only) and personal tabs (currently static only). Our sample app has both, so here’s how to check each type.
Test your configurable tab in a channel
In the team in which you sideloaded the package, select a channel and click the "+" icon next to the tabs and select the app called "Tasks App."
After clicking on the Tasks App icon, it will ask you to name your tab. Then it will create a new tab for you. Once again, it is pre-populated with "dummy" data.
Test your static tab
Click the “Apps” icon in the sidebar to enter personal scope. Your sideloaded static tab should appear as an App in the list, under the Sideloaded section.
Sideloaded apps should also be visible in the 1:1 chat canvas. The static tabs are labeled "My Tasks" and "Info." Click on "My Tasks." For the sake of providing an example, the sample app has pre-populated the static tab with sample tasks assigned to "Me."
As part of our sample app, we have provided a sample compose extension flow. This compose extension is powered by the same bot service, and uses the same ID. In fact, per above you used the same Microsoft App ID for both the bot ID and the compose extension ID.
The sample compose extension simulates a user “searching” through the tasks in our SaaS in order to insert a rich card into the chat stream. Like all things in our sample, all data is randomized and non-persistent – it is designed to show the overall flow (and the code behind it) for illustration purposes only. Let’s try it.
It will give you a Search box. Enter fake data, e.g. “coffee,” and select one of the fake tasks that are returned. This will insert it into the chat stream, and provide you an opportunity to provide additional information, like @mentioning a colleague so they can see the fake task too.
Please note: searching for a given task does not actually work.
Any future changes to the manifest will require you to re-sideload the sample app. (It’s not necessary to delete the app as long as the App ID hasn’t changed.)
For example, as a final test, in the manifest.json file, change the app name. In the example below, we changed it to "Dorothy App:"
Re-package and sideload the app again in Teams, and note the name change:
While you can leave your Ngrok running for as long as you want, when you do choose to stop and restart it, it will generate a new URL for you. This will require you to change the following to get you back up and running:
So there you go. You built your own Microsoft Teams app, and it feels great! And now that you are an expert in running our sample app, we encourage you to play around, look at the code, make changes, step through, and in general learn through doing. We got you started, the rest is up to you.
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.