Build your first Microsoft Teams app using Node.js

In this tutorial, you will learn how to build your very first Microsoft Teams app using Node.js. It also walks you through the steps to:

  1. Prepare your environment
  2. Get prerequisites
  3. Download the sample
  4. Build and run the sample
  5. Host the sample app
  6. Update the credentials for your hosted app
  7. Configure the app tab

Prepare your development environment

Before you begin, you must prepare your development environment. Custom app uploading must be enabled for the Office 365 organization where you want to build your app. If you need a dedicated development tenant, you can sign up for the Office 365 developer program. For more 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, select the options.

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 2.3.0
Local 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/Microsoft-Teams-Samples.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

After the repository is cloned, run the change directory command in terminal to change the directory to the sample:

cd Microsoft-Teams-Samples/samples/app-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. After installation you can run the app with the following command:

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:

  • http://localhost:3333
  • http://localhost:3333/hello
  • http://localhost:3333/first
  • http://localhost:3333/second

Deploy your 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 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.

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

Make a note of the URL of your app. You will need this later when you register the app with Teams using App studio or Developer Portal.

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 or Developer Portal, tools that run in Teams, that will simplify the process of registering the app. App Studio and Developer Portal are the recommended ways 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.

Update the app package

Use App Studio to update the app package

Tip

Try the Developer Portal: App Studio has evolved. Configure, distribute, and manage your Teams apps with the new Developer Portal.

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

Complete the following steps to update the app package:

  1. To install App Studio in Teams, select the Apps icon at the bottom of the left-hand bar, and search for App Studio:

    Finding App Studio in the Store View
  2. Select the App Studio tile and choose Install. The App Studio is installed:

    Installing App Studio
  3. To create the app package for your Teams app, select the Manifest editor tab in App Studio:

    App Studio

    The sample comes with its own manifest and is designed to build an app package when the project is built. On .NET, the manifest.json file can be located in Visual Studio in Manifest under Microsoft.Teams.Samples.HelloWorld.Web. On Node.js, this is done by typing gulp at the command line in the root directory of the project.

    In Visual Studio, the manifest.json file is located in under Manifest in Microsoft.Teams.Samples.HelloWorld.Web. This step is described by the following image:

    Build the app package on .NET with Visual Studio

    You can build the app package on Node.js 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.

  4. Now to modify this app package, select Import an existing app in the Manifest editor:

    Importing an existing app
  5. Select the Hello World tile for your newly imported app:

    Newly imported app view

    The following image shows the imported app package in App Studio:

    Importing the app package

    On the left-hand side of the Manifest editor there is a list of steps. On the right-hand side there is a list of properties that need to be filled in for each step. As you started with a sample app, much of the information is already completed. The next steps enable you to update the properties of the Hello World app.

App details

Select App details under Details. Select the Generate button to create a new App ID.

Your new App ID is similar to 2322041b-72bf-459d-b107-f4f335bc35bd.

Go through the app details in the right-hand pane including Developer information and Branding details. These details are important if you are writing a new app for distribution.

Tabs

It is simple to add tabs to a Teams app. The sample app already supports several tabs, and you can enable them.

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 is displayed. Select the ... symbol of the Tab configuration url and choose Edit from the drop-down menu. Change the URL to https://yourteamsapp.ngrok.io/configure where yourteamsapp.ngrok.io must be replaced with the URL that you used when hosting your app.

Personal tabs

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

Personal tabs are different from the Team tab. Hello Tab is already listed in the personal tabs list with a placeholder value com.contoso.helloworld.hellotab. Select the ... symbol of the Tab configuration url and choose Edit from the drop-down menu. The following dialog box appears:

Adding a personal tab dialog

Update the following boxes with your app URL:

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

Replace yourteamsapp.ngrok.io by the URL that you used when hosting your app.

Bots

It is easy to add the bots functionality to your app. The Hello World sample app already has a bot as part of the sample, but you must register it with Microsoft:

Adding a bot

The bot that was imported from the sample does not have an associated App ID. You must create a new bot so that App Studio can create a new App ID and register it with Microsoft.

Note

The App ID created by App Studio for the bot is different from the App ID created for the app. Each bot in an app requires its own App ID.

Complete the following steps to setup your bot:

  1. Select Delete next to the imported bot in the bot list. Now there are no bots left to show.

  2. Select Setup to display the Set up a bot dialog box.

    Adding a bot dialog
  3. Add a bot name Contoso bot and select all three check boxes under Scope.

  4. Choose Save to exit the dialog box. App Studio registers your bot with Microsoft and displays your new bot in the bot list.

  5. Now open a text file in notepad and copy and paste your new bot ID into it.

  6. Click Generate New Password, and note the password in the same text file you noted your bot App ID.

  7. Update the Bot endpoint address to https://yourteamsapp.ngrok.io/api/messages, and replace yourteamsapp.ngrok.io with the URL that you used when hosting your app.

  8. Now save your text file as you must add the information from the file to your hosted app to allow secure communication with your bot.

Messaging extensions

Messaging extensions let users ask for information from your service and post that information. The information is posted in the form of cards into the channel conversation. Messaging extensions appear at the bottom of the compose box.

Complete the following steps to setup your messaging extension:

  1. Select Messaging extensions under Capabilities in the left-hand pane of App Studio to configure the messaging extension:

    Adding a messaging extension

    The sample messaging extension is listed in the Messaging Extensions pane.

  2. Select Delete to remove the messaging extension, select Set up, and follow the same steps used for bots. The Messaging Extension dialog box is displayed.

  3. Select the Use existing bot tab and Select from one of my existing bots.

  4. Select the bot you created from the drop-down menu. Add a Bot name and select Save to close the dialog box.

  5. Under the Command section, select Add. To add a search-based command, select the Allow users to query your service for information and insert that into a message option.

  6. In the New command dialog box, enter the following values:

    Under New command:

    • Command ID: Enter random text
    • Title: Enter random title
    • Description: Enter random description

    Under Parameter:

    • Name: Enter the parameter name
    • Title: Enter the card title
    • Description: Enter card description
  7. After you enter the information, select Save to close the dialog box.

Register your app in Teams

After entering the details of your app, complete the following steps to register your app in Teams:

  1. Use Test and distribute of App Studio to install your app in Teams.

  2. Update your hosted application with the App ID and password for your bot. For the sample app, use the same App ID and password for both bot and messaging extension.

  3. Select Test and distribute under Finish in the left-hand pane of App Studio:

    Testing your app
  4. To upload your app to Teams, select the Install button under Test and Distribute:

    Adding a messaging extension dialog

    Note

    If you are unable to sideload the app, verify whether you have enabled custom app uploading.

  5. Select the Search box in the Add to a team section and select a team to add the sample app. You can set up a special team for testing.

  6. Select the Install button at the bottom of the dialog box.

    Your app is now available in Teams. However, the bot and the messaging extension will not work until you update the hosted applications environment with the App IDs and passwords.

    The finished app

Update the credentials for 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.

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

Note

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

After 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. After you select the tab and click Save you can see the Hello World tab loaded with the tab you chose:

Screenshot of configure

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:

Bot responses

Test your messaging extension

To test your messaging extension

  1. Select the three dots below the input box in your conversation view. A menu with the 'Hello World' app is displayed.

  2. Select the menu. A set of random texts is displayed. You can select one of the random text and that is inserted into your conversation.

    Messaging extension menu Messaging extension result
  3. Select one of the random texts, and you will see a card formatted and ready to send with your own message at the bottom:

    Messaging extension send

See also