Get Started with the Getting Started Sample App

[Richard Moe]

*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:

Pre-requisites

• Visual Studio Code—while you may use any IDE of your choice, we recommend you use this powerful and easy to use free tool
  • https://code.visualstudio.com/
  • NOTE: When installing, setting "open with" for the file and directory contexts can be helpful
• Node.js
  • https://nodejs.org/en/download/
  • NOTE: This gives you npm, Node Package Manager
• Tunneling software like Ngrok. https://ngrok.com/download
• The Bot Emulator
  • https://docs.microsoft.com/en-us/bot-framework/debug-bots-emulator
  • NOTE: make sure to pin the emulator to your task bar because it can sometimes be difficult to find again
• Git command line tool
  • https://git-scm.com/

Getting and initializing the sample

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:

• Open a command prompt in the parent directory into which you want to install the sample project.
• Clone the repo:
  • git clone https://github.com/OfficeDev/microsoft-teams-sample-get-started

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:

• Navigate to the Node subdirectory (cd microsoft-teams-sample-get-started\Node).
• Run the Node Package Manager tool:
  • From the command prompt, run: npm install

You now have all the required packages, and are ready to start up your IDE and get the code running:

• Open microsoft-teams-sample-get-started folder with VS Code.

Running the sample

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:

• Purely local - For bots, you can test your experience in the Bot Emulator. For other content, you can run locally and address content through “http://localhost”
• Locally hosted in Teams - This involves running locally with tunneling software, and creating a package to sideload into Teams. This allows you to easily run and step-debug your app within the Teams experience.
• Cloud hosted in Teams - This truly simulates (or is) production level support for a Teams app experience. It involves uploading your solution to your cloud provider of choice (we recommend Azure), and creating a package to sideload into Teams.

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.

Running locally

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.

Purely Local - Bot Emulator

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

Purely Local – Tabs

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.

Running Locally, in Microsoft Teams

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.

Setting up Ngrok

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:

• In a terminal, go the directory where you have ngrok.exe installed.
• Run ./ngrok http 3978 --host-header=localhost:3978
• This will launch Ngrok to listen on the port you specify. In return, it will give you an externally addressable URL, valid for as long as Ngrok is running.
  • Note: if you stop and restart Ngrok, you will get a new address.
• Copy the secure address (https) to your clipboard (e.g. https://2d1224fb.ngrok.io)

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.

Registering a Bot in the Microsoft Bot Framework

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: 

• Using your work or school account, sign in to the Microsoft Bot Framework site https://dev.botframework.com/ and click on the "My bots" tab to register a new bot.

• Display name – Give your app a name. This does not have to be unique. This will be the name displayed in Teams. (In the screenshots below, the name "Dorothy Bot" was used.)

• Note: If you decide to change the Display Name or icon after your bot is registered, it may take several days before your new name or icon will show up in your Teams client.

• Bot handle – Create a unique identifier for your bot.

• Note: This is unchangeable and may be visible to the public. If you change the Display name of your bot, your Bot handle will remain the same.

• Long description – Enter a long description which may appear in channels or directories.

• Note: In Microsoft Teams, the Store information will come from the Seller Dashboard.

Next, you need to configure your Bot service endpoint where services like Microsoft Teams will find your running bot instance:

• Messaging endpoint – Paste the Ngrok URL that you copied to your clipboard and append the appropriate endpoint to it. For our samples, again, our code is listening for messages on "/api/messages”, so for example you’d enter “https://2d1224fb.ngrok.io/api/messages”
• Create Microsoft App ID and password – This button will take you to the Application Registration Portal, where you can create a unique Microsoft App ID and password. You’ll need to log in again with your same identification.

• App name – This should prepopulate with the Display name from the registration
• App ID – This is a unique GUID created for your app, e.g. 93fed3d5-6782-462e-8a58-6a3e83ca6eab
• Generate an app password to continue – Click this button to generate an app secret aka password. E.g. qgSctpqT89ZdfAymt66Ukgf
• Note: You’ll need to copy and save this in a secure location as you will need this, and the app ID later.

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.

Enable Microsoft Teams as a channel

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.

Configure the Sample code to use your new information

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:

• MICROSOFT_APP_ID – This is the bot’s app ID you registered above.
• MICROSOFT_APP_PASSWORD – The secret from your registration.
• BASE_URI – Since our sample logic includes tabs and other non-bot features, we’ve made routing simple by allowing you to set the BASE_URI of your instance. In this case, you should use the full endpoint from Ngrok, e.g. https://2d1224fb.ngrok.io

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.

Check it – is Ngrok working?

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.

Checklist:

• Ngrok is running, listening on port 3978.
• You’ve registered your bot.
• You’ve inserted the bot registration values into your “Launch – Teams Debug” profile.
• You’re running the sample using the “Launch – Teams Debug” profile.

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:

• Modify the endpoint in the upper left corner to show the Ngrok URL plus the “/api/messages” suffix.
• Enter the App ID and Password from the Bot Framework registration.
• Click Connect.
• Then test the app by typing a command. For example, to tell the bot to create a task for you titled "Make Coffee," type the command "create Make Coffee." (Note: this bot does not make you coffee.)

Sidebar - Talk 1-on-1 to your bot in Microsoft Teams

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.

The 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:

• manifest.json file (the schema that defines your app experience)
• Color icon (92 x 92 pixels)
• Outline icon (20 x 20 pixels)

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

Update 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:

• For the “id”, replace with the app id that you got when registering the bot. 

•  For the “bots:botId,” use this app id again.

• For this sample, we have a compose extension, which at its core is just a bot, and we’ll use the same id here as well

Tabs 

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/”

Valid Domains

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:

Create your package

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.

Sideload your app

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.

Check it – Sample Tabs

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

Check it – Compose Extension

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.

• Click on the Conversation tab, in either 1:1 bot conversation or in the channel into which the app was sideloaded.
• Click on the ellipses under the message box.
• Click on your App.

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.

One more learning moment – updating the manifest

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:

Wait, one more - Re-running Ngrok

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:

• Update the Bot Framework endpoint.
• Update the Manifest to use the new address.
• Update the BASE_URI environment variable.

In Conclusion  

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.

As always, we welcome your feedback. We look forward to seeing what great experiences you can bring to Microsoft Teams.