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.

Before you start this tutorial

You will need an Office 365 tenant that has been set up for development, and you will need to configure teams to allow you to upload apps. You can work with your Office 365 administrator to confirm that your tenant is ready, or you can install a private evaluation version of Office 365 that you can manage. For more information see these topics:

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:

Note

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 2.19.0.windows.1

$ node -v
v8.9.3

$ npm -v
5.5.1

$ 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
1.28.2
929bacba01ef658b873545e26034d1a8067445e9

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 https://github.com/OfficeDev/msteams-samples-hello-world-nodejs.git

Tip

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.

Note

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.

Host on the web using Azure

You can host your sample app on any web service that you have access to, such as Azure where you can host this app for free. See Host your Node.js Teams app in Azure for detailed instructions to host this sample. Once your app is hosted, make a note of the URL of the hosted app. Notepad works fine for this purpose. You will need this URL later when you deploy your app to teams.

Host locally using ngrok

For quick 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 https://d0ac14a5.ngrok.io (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 https://d0ac14a5.ngrok.io/hello 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.

Note

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.

Tip

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.

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

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

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 helloworldapp.zip. 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.

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

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

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.

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 https://yourteamsapp.ngrok.io/configure where yourteamsapp.ngrok.io 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.

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

  • Change Content URL to https://yourteamsapp.ngrok.io/hello
  • Change Website URL to https://yourteamsapp.ngrok.io/hello

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

Bots

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.

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.

Add a bot name such as Contoso bot, and click both the 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 https://yourteamsapp.ngrok.io/api/messages, where yourteamsapp.ngrok.io 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.

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.

In the Messaging Extension dialog, choose the Existing tab, then under Bot ID choose Select from one of my existing bots.

Expand the drop down below Bot ID and choose the ID of the bot you created previously. Then choose the Save button. This returns you to the main page for Messaging Extensions.

In the Messaging endpoint section update the Bot endpoint address to https://yourteamsapp.ngrok.io/api/messages where yourteamsapp.ngrok.io should be replaced by the URL that you used above when hosting your app.

You now need to add a Command to your messaging extension. Do this by clicking the Add button in the Command section of Messaging Extensions. The New command dialog will appear.

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

You are now done with configuring your messaging extension.

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.

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

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.

Update your hosted app

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

MICROSOFT_APP_ID=<YOUR BOT'S APP ID>
MICROSOFT_APP_PASSWORD=<YOUR BOT'S PASSWORD>
WEBSITE_NODE_DEFAULT_VERSION=8.9.4

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.

Update your app in Azure

If you followed the instructions in Host your Node Teams app in Azure, you might remember the Configure environment variables step. Refer to that section and enter the values you saved to notepad earlier in this walkthrough. These environment variables will be hosted on the server.

Update your app in ngrok

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": "https://yourNgrokURL.ngrok.io",
        "MICROSOFT_APP_ID": "00000000-0000-0000-0000-000000000000",
        "MICROSOFT_APP_PASSWORD": "yourBotAppPassword",
        "NODE_DEBUG": "botbuilder",
        "SUPPRESS_NO_CONFIG_WARNING": "y",
        "NODE_CONFIG_DIR": "../config"
    }
}

Where:

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

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.