Build your first app using Node.js
Start Microsoft Teams app development by building your first app with a tab, a bot, and a message extension capability.
This app will have all capabilities and each has its own UI and UX:
In this tutorial, you'll learn:
- How to set up a new project using command-line tools.
- How to build three apps with a different capability each—tab, bot, and message extension.
- How to deploy your app from Developer Portal
Here's a list of tools you'll need to install for building and deploying a Teams app.
|ngrok||Teams app features (conversational bots, messaging extensions, and incoming webhooks) require inbound connections. A tunnel connects your development system to Teams. It isn't required for apps that only include tabs. This package is installed within the project directory (using npm
|Microsoft Edge (recommended) or Google Chrome||A browser with developer tools.|
|Install Git||Sample Node.js app repo from GitHub|
|Azure Tools for Visual Studio Code and Azure CLI||Azure tools to access stored data or to deploy a cloud-based backend for your Teams app in Azure.|
|Microsoft Graph Explorer||Microsoft Graph Explorer, a browser-based tool that lets you run a query from Microsoft Graph data.|
|Developer Portal for Teams||Web-based portal to configure, manage, and distribute your Teams app including to your organization or the Teams store.|
|Visual Studio Code Extensions|
|Azure Functions Core Tools||Backend components locally during a local debug run, including the authentication helpers required when running your services in Azure. It's installed within the project directory (using the npm
|.NET SDK||Customized bindings for local debugging and Azure Functions app deployments. If you have not installed the .NET 3.1 (or later) SDK globally, the portable version can be installed.|
Verify version numbers for installed tools
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 Git Bash (which is included in Git installation), 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 can use a different version of these applications without any problem.
If you have installed Visual Studio Code, you can verify the installation by running:
code --version 1.28.2 929bacba01ef658b873545e26034d1a8067445e9
Set up your Teams development tenant
A tenant is like a space, or a container for your organization in Teams, where you chat, share files, and run meetings. This space is also where you sideload and test your app.
Let's verify if you're ready to develop with the tenant.
Enable sideloading option
After creating the app, you must load your app in Teams without distributing it. This process is known as sideloading. Sign in to your Microsoft 365 account to view this option.
Do you already have a tenant, and do you have the admin access? Let's check if you really do!
Verify if you can sideload apps in Teams:
In the Teams client, select Store icon.
Select Manage your apps.
Look for the option to Upload a custom app. If you see the option, sideloading apps is enabled.
If Teams doesn't show the option to upload a custom app, talk to your Teams administrator.
Create a free Teams developer tenant
If you don't have a Teams developer account, you can get it free. Join the Microsoft 365 developer program!
Go to the Microsoft 365 developer program.
Select Join Now and follow the onscreen instructions.
In the welcome screen, select Set up E5 subscription.
Set up your administrator account. After you finish, the following screen appears.
Sign in to Teams using the administrator account you just set up. Verify that you have the Upload a custom app option in Teams.
Get a free Azure account
If you wish to host your app or access resources in Azure, you must have an Azure subscription. Create a free account before you begin.
Now you’ve got all tools and set up your accounts. Next, let's set up your development environment and start building!
You can continue to use this terminal window to run the commands that follow in this tutorial.
Download the sample
You can use the Hello, World! sample to get 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
Build your first Node.js app
After you have cloned the repo for Node.js sample app, you can build and test the app in your local environment.
In this page, you'll learn to:
Build and run the sample
After the repository is cloned, you can build the sample app.
Open a terminal window.
Run the change directory command in the terminal to change to the sample app directory:
Install all dependencies using the following command:
You should see a bunch of dependencies getting installed.
Run the app using the following command after installation is complete:
When the Hello World app starts, it displays
App started listening on port 3333in 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.
Open a browser window and use the following URLs to verify that all the Hello World app URLs are loading:
Test your sample app in local environment
Remember that apps in Microsoft Teams are web applications exposing one or more capabilities. Make your app available on the internet so that the Teams platform can load it. 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 the
Create ngrok tunnel
After you install ngrok, you can create a tunnel to deploy your app locally.
Open a new terminal window.
Run the following command to create a tunnel. The sample app uses port 3333:
ngrok http 3333 -host-header=localhost:3333
The ngrok tunnel is created. Here's an example of ngrok tunnel.
Ngrok listens to requests from the internet and will route them to your app running on port 3333.
To verify the app's local deployment:
Open the browser.
Load your app using the following URL:
https://<forwarding address in ngrok console session>/hello
Here's an example of the URL:
Make a note of the forwarding address in ngrok console. You need this URL to deploy your app in Teams.
If you used a different port during build and run, make sure you use the same port number to setup the ngrok tunnel.
It's 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. The paid version of ngrok allows persistent names.
If you use the free version of ngrok, your app will be available only during the current session on your development machine. It isn't available if the machine is shut down or goes to sleep. When you restart the service, it returns a new address. Then, you must update every location that uses the outdated address. Remember this step when sharing the app for testing.
Build Node.js app package
You can use
gulp CLI to build the app package for Node.js.
Open a terminal window.
Ensure that you are in the directory where the
node.jsis cloned. This is the folder where
Run the following command to build the Node.js app package.
Here's an example of the command output:
[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 app package helloworldapp.zip is created. You can find the package file at the following path.
<path to the cloned repo>/Microsoft-Teams-Samples/samples/app-hello-world/nodejs/manifest
Search for the app package file, helloworldapp.zip, if the location is not clear in the tool you are using.
Deploy your first Node.js app using Dev Portal
You can use Developer Portal to upload the app package to Teams. Developer Portal is a Teams app that simplifies the creation and registration of an app. Install from the Teams store!
Updating the app package includes:
Import the app package to Developer Portal
To import the app package:
Open Microsoft Teams.
Select the Store icon from the left-hand bar.
Search for Developer Portal in the search bar, and select Developer Portal*.
The Developer Portal opens.
Select the Apps tab.
Select Import an existing app.
Open the app package helloworldapp.zip from the following path in your C# sample repo directory structure:
<path to cloned node.js sample repo>\\Source\Repos\Microsoft-Teams-Samples\samples\app-hello-world\nodejs\manifest
The Hello World app is imported in Developer Portal.
After you've imported your app to Developer Portal, you can view its details in Developer Portal.
Take a tour of your app in Developer Portal
After you've imported your app to Developer Portal, you can view its details, including the manifest file.
View app information
Select Basic Information from the left pane of Developer Portal.
Note the following information from the basic information:
- App ID
- Developer Information
- App URLs
Select Branding from the left pane to view the branding information.
These details are important if you are writing a new app for distribution.
View app features
Select App features from the left pane of Developer Portal.
The App features appear in the right pane. You can view cards for Personal app, Bot, and Message Extension.
View the app manifest
You use the manifest file to configure capabilities, required resources, and other important attributes for your app.
Select Publish from the left panel to open the dropdown list, and then select App package.
The App manifest appears in the right pane.
The manifest file appears in the right pane.
Configure your app's capabilities
After you've imported your app into Developer Portal, the next step is to configure app capabilities. Developer Portal contains all the app information in different sections. It makes configuring the app capabilities easy.
Using Developer Portal, you can:
Configure personal tab app
To configure personal tab app:
Select the icon on the Personal app card on the App features pane, and select Edit.
The details for Hello tab appear.
Select the icon for Hello tab, and select Edit to open the app details for updating.
Enter the app details for the Hello tab in Add a tab to your personal app.
Enter the following details:
- Name: Hello tab
- Content URL and Website URL: the forwarding address in ngrok console session
The details of the Hello tab appear on the Personal app pane.
The Personal app pane now shows the new tab and an About tab created automatically.
It's 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 Teams.
The bot that was imported from the sample doesn't have an associated app ID. You'll need to delete it, and create a new bot. Developer Portal creates a new app ID, and registers it with Teams.
Adding and configuring a bot involves:
To add a new bot
Select the icon on the Bot card on the App features pane, and select Delete.
Select Bot on the App features pane.
Select Create a new bot on the Bot pane.
The Bot management section opens.
Select + New Bot on the Bot management pane.
Enter a suitable name for your bot, and select Add.
The Configure pane appears showing details of the new bot in the left pane.
Enter the forwarding URL from the
ngrokconsole, and select Save.
Select Client secrets and then select Add a client secret to your bot to generate a password for the bot.
Developer Portal generates a password for the bot.
Select the icon to copy the password, and save it in a text file.
Select < Bots to return to Bot management pane.
The Bot management pane shows the new Bot added with an app ID.
Ensure that you save the Bot ID along with the password from the Client secret section.
To add bot to app
Open the App features pane, and select the Bot card.
The Bot pane appears.
Select your bot app from Select an existing bot, and select Save.
The new bot is added to your app with its own app ID.
To configure bot scope
Select the icon on the new Bot card, and select Edit.
Move through the Bot pane to view the Commands section, and select + Add a Command.
Enter a suitable name and description for the Command.
Select all the three scopes for the command, and select Add.
- Group Chat
The new command is added to the Commands section of the Bot pane.
The command details are saved.
Open App features pane, and select Personal app card to view your app's tab details.
You'll see that a tab for your new chat bot is added to your app.
Configure message extension
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.
To add a new message extension:
Select the icon on the Message Extension card on the App features pane, and select Delete.
Select Message Extension from the App features pane.
Select the name of your bot app from the Select an existing bot dropdown list on the Message extension pane.
The message extension is saved, and the Commands section appears on the Message extension pane.
Select + Add a command to define the scope of what your message extension app can do.
The Add a command dialog.
Ensure that Search is selected as the type of command you want to add in the Add a command dialog.
Enter suitable information for the following details:
- Command ID
- Command title
- Command description
Move through the dialog to view the remaining details.
Ensure Make default is selected.
Select the following contexts for the message extension command:
- Command box
- Compose box
Enter suitable information for the following details:
- Parameter name
- Parameter title
- Parameter description
Select Text as the type of input.
The message extension command is saved, and shows on the list of commands in the Message extension pane.
Open App features pane.
You'll see all three capabilities - personal tab app, bot, and message extension - configured for the Hello World app.
Preview and test your Node.js app
After you've imported your app and configured the capabilities in Developer Portal, you can preview and test the sample app.
Preview your app in Teams
After configuring the capabilities of your app, you can preview and test your app in Teams in the local environment.
To preview your app:
Select Preview in Teams from the Developer Portal toolbar.
The Developer Portal informs you that your app is sideloaded successfully.
Select Publish from the left pane, and select Download app package to download the configured app package from Developer Portal.
Save the app package zip file. The file name is Hello World.zip.
Select the Store icon.
Select Manage your apps.
Select Upload a custom app.
Select Hello World.zip to upload it to Teams in the local environment.
The Add page appears for your app.
Select Add to install the app on Teams.
Your app is now available in Teams. You can view all the tabs and test the capabilities:
You can send a message using the chat.
You can try a search using the message extension.
Have an issue with this section? If so, please give us some feedback so we can improve this section.