Get started on the Microsoft Teams platform with Node.js and App Studio

The Microsoft Teams developer platform makes it easy for you to extend Teams and integrate your own applications and services seamlessly into the Teams workspace. These apps can then be distributed to your enterprise or for teams around the world.

To extend Microsoft Teams, you need to create a Microsoft Teams app. A Microsoft Teams app is a web application that you host. This app can then be integrated into the user's workspace in Teams.

Prepare your development environment

The first thing you'll need to do is prepare your development environment. You'll need to make sure custom app uploading is enabled for the Office 365 organization you want to build your app in. If you need a dedicated development tenant, you can sign up for the Office 365 developer program. For additional information see Setup your development environment.

Download and host your app

Follow these steps to download and host a simple "hello world" app in Teams.

Get prerequisites

To complete this tutorial, you need the following tools. If you don't already have them you can install them from these links.

If you see options to add git, node, npm, and code to the PATH during installation, choose to do so. It will be handy.

Verify that the tools are available by running the following in a terminal window:


Use the terminal window that you are most comfortable with on your platform. These examples use Bash (which is included in Git), but these scripts will run on most platforms.

$ git --version
git version

$ node -v

$ npm -v

$ gulp -v
CLI version 4.0.2

You may have a different version of these applications. This should not be a problem, except for gulp. For gulp you'll need to use version 4.0.0 or later.

If you don't have gulp installed (or have the wrong version installed), do so now by running npm install gulp in your terminal window.

If you have installed Visual Studio Code, you can verify the installation by running:

code --version

You can continue to use this terminal window to run the commands that follow in this tutorial.

Download the sample

We have provided a simple Hello, World! sample to get you started. In a terminal window, run the following command to clone the sample repository to your local machine:

git clone


You can fork this repo if you want to modify and check in your changes to your GitHub repo for future reference.

Build and run the sample

Once the repo is cloned, change to the directory that holds the sample:

cd msteams-samples-hello-world-nodejs

In order to build the sample, you need to install all its dependencies. Run the following command to do this:

npm install

You should see a bunch of dependencies getting installed. Once they are finished, you can run the app:

npm start

When the hello-world app starts, it displays App started listening on port 3333 in the terminal window.


If you see a different port number displayed in the message above, it is because you have a PORT environment variable set. You can continue to use that port or change your environment variable to 3333.

At this point, you can open a browser window and navigate to the following URLs to verify that all the app URLs are loading:

Host the sample app

Remember that apps in Microsoft Teams are web applications exposing one or more capabilities. For the Teams platform to load your app, your app must be reachable from the internet. To make your app reachable from the internet, you need to host your app.

For local testing you can run the app on your local machine and create a tunnel to it with a web endpoint. ngrok is a free tool that lets you do just that. With ngrok you can get a web address such as (this URL is just an example). You can download and install ngrok for your environment. Make sure you add it to a location in your PATH.

Once you install it, you can open a new terminal window and run the following command to create a tunnel. The sample uses port 3333, so be sure to specify it here.

ngrok http 3333 -host-header=localhost:3333

Ngrok will listen to requests from the internet and will route them to your app running on port 3333. You can verify by opening your browser and going to to load your app's hello page. Please be sure to use the forwarding address displayed by ngrok in your console session instead of this URL.


If you have used a different port in the build and run step above, make sure you use the same port number to setup the ngrok tunnel.


It is a good idea to run ngrok in a different terminal window to keep it running without interfering with the node app which you might later have to stop, rebuild and rerun. The ngrok session will return useful debugging information in this window.

There is a paid version of ngrok that allows persistent names. If you use the free version your app will only be available during the current session on your development machine. If the machine is shut down or goes to sleep the service will no longer be available. Remember this when sharing the app for testing by other users. If you have to restart the service it will return a new address and you will have to update every place that uses that address.

Remember, make a note of the URL of your app because you will need this later when you register the app with Teams using App studio. Notepad works fine for this purpose.

Deploy your app to Microsoft Teams

At this point you have an app hosted on the internet, but you have no way yet of telling Teams where to look for it, or even what your app is called. To do this you now have to create an app package. This is little more than a text file that contains the app manifest and some icons that the Teams client will use to properly display and brand your app. You can manually create this app package, or you can use App Studio, a tool that runs in Teams that will simplify the process of registering the app. App Studio is the recommended way of creating and updating the app package.

For either method you will need the following:

  • The URL where your app can be found on the internet.
  • Icons that Teams will use to brand your app. The sample comes with placeholder icons located in "src\static\images. App Studio also will provide default icons if needed.

Use App Studio to update the app package

App Studio is a Teams app that you can install from the Teams store. It simplifies the creation and registration of an app.

To install App Studio in Teams, click on the app store icon at the bottom of the left hand bar, and search for App Studio.

Finding App Studio in the Store View

Once you find the tile for App Studio, click on it and choose install in the dialog that pops up.

Installing App Studio

Once App Studio is installed click on the Manifest editor tab to begin creating the app package for your Teams app.

App Studio

The sample comes with its own pre-made manifest, and is designed to build an app package when the project is built. On .NET this is done in Visual Studio, and on Node JS this is done by typing gulp at the command line in the root directory of the project.

$ gulp
[13:39:27] Using gulpfile ~\documents\github\msteams-samples-hello-world-nodejs\gulpfile.js
[13:39:27] Starting 'clean'...
[13:39:27] Starting 'generate-manifest'...
[13:39:27] Finished 'generate-manifest' after 11 ms
[13:39:27] Finished 'clean' after 21 ms
[13:39:27] Starting 'default'...
Build completed. Output in manifest folder
[13:39:27] Finished 'default' after 62 μs

The name of the generated app package is You can search for this file if the location is not clear in the tool you are using.

In the next part of this walkthrough you are going to modify this app package by selecting the Import an existing app tile in the Manifest Editor.

Importing an existing app

Once the app package has been imported App Studio should look like this:

Importing the app package

Click on the tile for your newly imported app, Hello World.

Newly imported app view

There is a list of steps in the left-hand side of the Manifest editor, and on the right a list of properties that need to be filled in for each of those steps. Since you started with a sample app, much of the information is already filled out. The next steps will walk you through changing the parts that still need to be updated.

App details

Click on the App details entry under Details. Click the Generate button to create a new app id.

Your new app id should look something like: 2322041b-72bf-459d-b107-f4f335bc35bd.

Look through the rest of the App details in the right hand pane, and familiarize yourself with some of the entries such as Developer information and Branding. These sections are important if you are writing a new app for distribution.

Capabilities: Tabs

Tabs are among the simplest elements to add to a Teams app. The sample app already supports several tabs, and you can enable them as follows.

Team tab

Your app can only have one Team tab.

Adding a Teams tab

In this sample, the Team tab is where your configuration page goes. Click on the ... symbol at the end of the entry and choose Edit from the drop-down. Change the URL to where should be replaced by the URL that you used above when hosting your app.

Personal tabs

Your app can have up to 16 tabs, including the team tab.

Personal tabs are represented differently from the team tab. You should see Hello Tab already listed in the personal tabs list. At the moment it has a placeholder value com.contoso.helloworld.hellotab. Click on the ... symbol at the end of the entry and choose Edit from the drop-down. The following dialog will appear.

Adding a personal tab dialog

There are two fields that you need to update with your app URL.

  • Change Content URL to
  • Change Website URL to

Where should be replaced by the URL that you used above when hosting your app.


Bots are the most common way to add functionality to your app. The hello world sample already has a bot as part of the sample, but it has not been registered with Microsoft yet.

Adding a bot

The bot that was imported from the sample does not have an App ID associated with it yet. You will have to create a new bot so that App Studio can create a new App ID and register it with Microsoft. Note that this is the App ID for the bot, which is different from the App ID that we created for the app in a earlier step. Each bot in an app requires its own App ID.

Click the delete button next to the Imported bot in the bot list.

Now there are no bots left to show. Click Setup. This will display the Set up a bot dialog.

Adding a bot dialog

Add a bot name such as Contoso bot, and select all three buttons under scope.

Choose Create bot to exit the dialog. App Studio will spend a moment registering your bot with Microsoft, and then should display your new bot in the bot list. Now would be a good time to open a text file in notepad and copy and paste your new bot id into it. You will need this id later.

Click Generate New Password, and make a note of the password in the same text file you noted your Bot app ID in. This is the only time your password will be shown, so be sure to do this now.

Update the Bot endpoint address to, where should be replaced by the URL that you used above when hosting your app.

Now would be a good time to save your text file if you have not done so already. You will add this information to your hosted app later in this walkthrough, which will allow secure communication with your bot.

Messaging extensions

Messaging extensions let users ask for information from your service and post that information, in the form of cards, right into the channel conversation. Messaging extensions appear along the bottom of the compose box.

Click on Messaging extensions under Capabilities in the left hand column of App Studio to begin configuring the messaging extension.

Adding a messaging extension

The sample messaging extension is listed in the right hand pane under Messaging Extensions. Click Delete again to remove this entry, and then click the Set up button following the same steps as you followed for bots. This will display the Messaging Extension dialog.

Select the Use existing bot tab, then Select from one of my existing bots. In the drop-down menu, select the bot you created in the section above. Add a Bot name and click Save to close the dialog.

Under the Command section, click Add. We're adding a search-based command, so choose the Allow users to query your service... option.

In the New command dialog enter the following values.

Under New command:

  • Command ID = getRandomText
  • Title = Get some random text for fun
  • Description = Gets some random text and images

Under Parameter:

  • Name = cardTitle
  • Title = Card title
  • Description = Card title to use

Once you're entered the information, click Save to close the dialog.

Register your app in Teams

You have now completed entering the details of your app, but two steps remain. First you must use the Test and Distribute section of App Studio to install your app in Teams, and second you must update your hosted application with the App ID and password for your bot. Remember that the sample expects to use the same App ID and password for both the bot and the messaging extension.

Click on the Test and distribute item under Finish in the left hand column of App Studio.

Testing your app

In order to upload your app to Teams, click the Install button under Test and Distribute.

Adding a messaging extension dialog

Click on the Search box in the Add to a team section and select a team to add the sample app to. Usually you will want to set up a special team for testing.

Click the Install button at the bottom of the dialog.

This finishes the App Studio portion of this walkthrough. You should now see your app running in Teams, however the bot and the messaging extension will not work until you update the hosted applications environment to know what the App IDs and passwords are.

The finished app

Update your hosted app

The sample app requires the following environment variables to be set to the values you made a note of earlier.


How you do that differs depending on how you hosted your app. The important thing about using environment variables is that these values are part of your environment - they can be accessed by the code for your app, but they are not exposed to third parties who might examine the files that make up your site.

If you are running the app using ngrok you'll need to set up some local environment variables. There are many ways to do this, but the easiest, if you are using Visual Studio Code, is to add a launch configuration:

    "type": "node",
    "request": "launch",
    "name": "Launch - Teams Debug",
    "program": "${workspaceRoot}/src/app.js",
    "cwd": "${workspaceFolder}/src",
    "env": {
        "BASE_URI": "",
        "MICROSOFT_APP_ID": "00000000-0000-0000-0000-000000000000",
        "MICROSOFT_APP_PASSWORD": "yourBotAppPassword",
        "NODE_DEBUG": "botbuilder",
        "NODE_CONFIG_DIR": "../config"


MICROSOFT_APP_ID and MICROSOFT_APP_PASSWORD is the ID and password, respectively, for your bot. NODE_DEBUG will show you what's happening in your bot in the Visual Studio Code debug console. NODE_CONFIG_DIR points to the directory at the root of the repository (by default, when the app is run locally, it looks for it in the src folder).


If you have not stopped npm from earlier in the tutorial, you'll need to run npm stop in order for Visual Studio Code to pickup your launch configuration variables correctly.

Configure the app tab

Once you install the app into a team, you will need to configure it to show content. Go to a channel in the team and click on the '+' button to add a new tab. You can then choose Hello World from the Add a tab list. You will then be presented with a configuration dialog. This dialog will let you choose which tab to display in this channel. Once you select the tab and click on Save you can see the Hello World tab loaded with the tab you chose.

Test your bot in Teams

You can now interact with the bot in Teams. Choose a channel in the team where you registered your app, and type @your-bot-name, followed by your message. This is called an @mention. Whatever message you send to the bot will be sent back to you as a reply.

Test your messaging extension

To test your messaging extension, you can click on the three dots below the input box in your conversation view. A menu will pop up with the 'Hello World' app in it. When you click it, you will see a number of random texts. You can choose any one of them and it will be inserted it into your conversation.

Choose one of the random texts, and you will see a card formatted and ready to send with your own message at the bottom.