Build your first message extension app using JavaScript
Start Microsoft Teams app development with your first Teams app. You can create a message extension Teams app with Teams using Javascript.
In this tutorial, you'll learn:
- How to set up a new project with Teams Toolkit.
- How to build a message extension app.
- How to deploy your app.
This step-by-step guide helps you to build message extension Teams app with Teams Toolkit. You'll see the following output after you've completed this guide:
Prerequisites
Ensure you install the following tools for building and deploying your apps.
| Install | For using... | |
|---|---|---|
| Required | ||
| Visual Studio Code | JavaScript or TypeScript, build environments. Use the latest version. | |
| Teams Toolkit | Microsoft Visual Studio Code extension that creates a project scaffolding for your app. Use the latest version. | |
| Node.js | Back-end JavaScript runtime environment. For more information, see Node.js version compatibility table for project type. | |
| Microsoft Teams | Microsoft Teams to collaborate with everyone you work with through apps for chat, meetings, and call-all in one place. | |
| Microsoft Edge (recommended) or Google Chrome | A browser with developer tools. | |
| Microsoft 365 developer account | Access to Teams account with the appropriate permissions to install an app. | |
| Optional | ||
| 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. | |
| React Developer Tools for Chrome OR React Developer Tools for Microsoft Edge | A browser DevTools extension for the open-source React JavaScript library. | |
| 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 Microsoft Teams Store. |
Tip
If you work with Microsoft Graph data, you should learn about and bookmark the Microsoft Graph Explorer. This browser-based tool allows you to query Microsoft Graph outside of an app.
Prepare development environment
After you've installed the required tools, set up the development environment.
Install the Teams Toolkit
The Teams Toolkit helps simplify the development process with tools to provision and deploy cloud resources for your app, publish to the Teams Store, and more.
You can use the toolkit with Visual Studio Code, or CLI (command-line interface), called TeamsFx.
- Open Visual Studio Code and select the Extensions view (Ctrl+Shift+X / ⌘⇧-X or View > Extensions).
- In the search box, enter Teams Toolkit.
- Select Install next to the Teams Toolkit.
The Teams Toolkit 
icon appears in the Visual Studio Code Activity Bar after it's installed.
You can also find the Teams Toolkit on the Visual Studio Code Marketplace.
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 your sideload and test your app. Let's verify if you're ready to develop with the tenant.
Check for 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.
Note
Sideloading is necessary for previewing and testing apps in Teams local environment. If it isn't enabled, you will not be able to preview and test your app in Teams local environment.
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 the Store icon.
Select Manage your apps.
Select Upload an app.
Look for the option to Upload a custom app. If you see the option, sideloading apps is enabled.
Note
If you don't have the option to upload a custom app, talk to your Teams administrator.
Create a free Teams developer tenant (optional)
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 the tools to set up your account. Next, let's set up your development environment and start building! Select the app you want to create first.
Create project workspace for your message extension app
You've built your bot app. Now, let's create your first message extension app.
Message Extension capability lets you interact with a web service. Use the compose area, command box, or a messaging in Teams client to search and initiate actions in an external system.
There are two types of Teams message extensions:
- Search commands: You can search external systems. Then, you can insert its results into a message in the form of a card.
- Action commands: You can present your users with a modal pop-up to collect or display information. Then, you can process their interaction and send information back to Teams.
Let's create a message extension app with a search command. Use it to search for external data and insert the results into a message within Teams client.
As you've already prepared for creating these apps, you can set up a new Teams project for creating the message extension app.
Note
Message extensions rely on bots to provide a dialog between the user and your code.
In this tutorial, you learn:
- How to set up a new Message Extension project with Teams Toolkit.
- About the directory structure of your app project.
Create your message extension project workspace
If the prerequisites are in place, let's begin!
Note
The Visual Studio Code UI shown is from Mac. It may differ depending on your operating system, Toolkit version, and environment.
Open Visual Studio Code.
Select the Teams Toolkit
icon in the Visual Studio Code Activity Bar.Select Create a New App.
Select Message Extension to create an app using the Teams Toolkit.
Ensure that Custom Search Result is selected as the app feature that you want to build in your app.
Select JavaScript as the programming language.
Select Default folder to store your project root folder in default location.
You can also change the default location by the following steps:
Select Browse.
Select the location for project workspace.
Select the Select Folder.
Enter a suitable name for your app. Select Enter.
Teams Toolkit creates the app in a few seconds.
After your app is created, the Teams Toolkit displays the following message:
You can select Local debug to preview your project.
A quick recap of creating a Teams app.
Watch this short recap for creating a Teams app.
Take a tour of the message extension app source code
A message extension uses the Bot Framework. You use it to interact with your service via a conversation. After scaffolding is done, view the project directories and files in the Explorer area of Visual Studio Code.
| Folder / File | Contents |
|---|---|
teamsapp.yml |
Main project file describes your application configuration and defines the set of actions to run in each lifecycle stages. |
teamsapp.local.yml |
This overrides teamsapp.yml with actions that enable local execution and debugging. |
.vscode/ |
VSCode files for local debug. |
appPackage/ |
Templates for the Teams application manifest. |
infra/ |
Templates for provisioning Azure resources. |
index.js |
Application entry point and restify handler. |
teamsBot.js |
Teams activity handler. |
Tip
Familiarize yourself with bots and message extension outside of Teams before you integrate your app within Teams.
Build and run your first message extension app
After you set up your project workspace with Teams Toolkit, build your project. You need to sign in to your Microsoft 365 account.
Sign in to your Microsoft 365 account
Use this account to sign in to Teams. If you're using a Microsoft 365 developer program tenant, the admin account you set up while registering is your Microsoft 365 account.
Open Visual Studio Code.
Select the Teams Toolkit
icon in the sidebar.Select Sign in to M365 using your credentials..
Your default web browser opens to let you sign in to the account.
Close the browser when prompted and return to Visual Studio Code.
Return to Teams Toolkit within Visual Studio Code.
The ACCOUNTS section of the sidebar shows your Microsoft 365 account name. The Teams Toolkit displays Sideloading enabled if sideloading is enabled for your Microsoft 365 account.
Now you're ready to build the app and run it locally!
Build and run your app in the local environment
A message extension lets you interact with a web service. It takes advantage of the messaging feature and secure communication of a bot. The message extension app is added to a web service registered as a bot.
Build and run your app locally
Select F5 in Visual Studio Code to run your application in debug mode.
Note
If Teams Toolkit is unable to check a particular prerequisite, it prompts you to check.
Learn what happens when you run your app locally in the debugger.
When you select F5, the Teams Toolkit:
- Checks all the following prerequisites:
- You're logged in with a Microsoft 365 account.
- Sideloading is enabled for your Microsoft 365 account.
- Supported Node.js version is installed.
- Port required by bot app is available.
- Install npm packages
- Starts Dev Tunnel to create a HTTP tunnel.
- Registers the app in Azure AD and configures the app.
- Registers the bot app in Bot Framework and configures the app.
- Registers the app in Teams Developer Portal and configures the app.
- Starts the message extension app hosted locally.
- Starts Teams in a web browser and sideloads the Teams app.
Note
When you run the app for the first time, all dependencies are downloaded, and the app is built. A browser window opens when the build is complete. This process can take three to five minutes to complete.
Teams run your app in a web browser.
Sign in with your Microsoft 365 account, if prompted.
Select Add to add the app to your account.
The toolkit displays a message to indicate that the app is added to Teams.
- If you select Got it, you can try the app later from the list of Sideloaded apps.
- If you select Try it, Teams loads your app.
Select Try it.
The Message Extension app is loaded in a chat bot app.
As message extension apps rely on bots for enabling communication between the user and the web service,, your app loads in to a chat feature of a bot.
- If you've created a bot app before you created the message extension app, you can see that it is loaded in the same bot app you created. Previous chat messages are visible.
- If you created a message extension first, your app is loaded in any chat that is open on Teams.
Note
If you want to extend your app to Outlook and Microsoft 365, you can choose to debug your app with Outlook and Microsoft 365 from RUN AND DEBUG dropdown in Visual Studio Code.
Test your app
The first time your app loads, the message extension app is open for you to test. This sample app lets you search open-source npm packages from the software registry.
To run a search query
Let's enter a search string in the search box, such as "cli". You'll get a list of the matching items:
Select one from the search results. It will be displayed in the compose area so you can send the result to the channel.
Select the Send instructions.
Now, you've learned how to build and run a basic message extension app!
Optional scenarios
You've tested the search feature of a basic message extension app. Now, you can try out some other functionalities of this app. These are optional scenarios in this app.
To create a card
Select Create Card.
Enter the card details as shown, and select Submit.
Your card details appear in the compose area.
Select the Send icon from the compose area.
The app sends the card on the bot chat.
To open your app from compose area
Choose one of the following ways to open your app.
- Using
@mention:
Enter
@your-app-namein the command area of your app.The app opens the search box and you can use it to run a query.
Enter a search string, and select one from the search result.
It displays in the command area as a card.
Copy the card to paste it in the compose area.
Send the card using the compose area.
- Using three-dot icon:
Launch the message extension from three dots at the bottom of the composing area.
Select your message extension app.
The message extension app loads with the options to run a search and create adaptive cards.
Run the app from sideloaded apps
You can open a sideloaded Teams app from the list of sideloaded apps.
Select the Store icon from the Teams sidebar.
Select the Manage apps.
Select the three dots icon for your app, and then select View details. You can also copy link to the app and use it to open the app.
Select Open to load the app, and then select Try it.
The app loads in Teams.
Learn how to troubleshoot if your app doesn't run locally.
To run your app in Teams, you must have a Microsoft 365 development account that allows app sideloading. You can learn more about sideloading in the Prerequisites section.
Deploy your first Teams app
You've learned to create, build, and run Teams app with Message Extension capabilities. The final step is to deploy your app on Azure.
Let's deploy the first message extension app on Azure using Teams Toolkit.
Sign in to your Azure account
Use this account to access the Microsoft Azure portal and to provision new cloud resources to support your app.
Open Visual Studio Code.
Open the project folder in which you created the message extension app.
Select the Teams Toolkit
icon in the sidebar.Select Sign in to Azure using your credentials.
Tip
If you have the AZURE ACCOUNT extension installed and are using the same account, you can skip this step. Use the same account as you are using in other extensions.
Your default web browser opens to let you sign in to the account.
Close the browser when prompted and return to Visual Studio Code.
The ACCOUNTS section of the sidebar shows the two accounts separately. It also lists the number of usable Azure subscriptions available to you. Ensure you have at least one usable Azure subscription available. If not, sign out and use a different account.
Congratulations, you have signed in your Azure account! Now let's go ahead and learn how to deploy one of the apps to Azure using the Teams Toolkit.
Deploy your app to Azure
Deployment consists of two steps. First, necessary cloud resources are created (also known as provisioning). Then, your app's code is copied into the created cloud resources. For this tutorial, you'll deploy the message extension app.
What's the difference between Provision and Deploy?
The Provision step creates resources in Azure and Microsoft 365 for your app, but no code (HTML, CSS, JavaScript, etc.) is copied to the resources. The Deploy step copies the code for your app to the resources you created during the provision step. It's common to deploy multiple times without provisioning new resources. Since the provision step can take some time to complete, it's separate from the deployment step.
Select the Teams Toolkit
icon in the Visual Studio Code sidebar.
Select Provision.
Select a subscription to use for the Azure resources.
Your app is hosted using Azure resources.
A dialog warns you that costs may be incurred when running resources in Azure.
Select Provision.
The provisioning process creates resources in the Azure cloud. It may take some time. You can monitor the progress by watching the dialogs in the bottom-right corner. After a few minutes, you see the following notice:
If you want, you can view the provisioned resources. For this tutorial, you don't need to view resources.
The provisioned resource appears in the ENVIRONMENT section.
Select Deploy from the LIFECYCLE panel after provisioning is complete.
As with provisioning, deployment takes some time. You can monitor the process by watching the dialogs in the bottom-right corner. After a few minutes, you see a completion notice.
Now, you can use the same process to deploy your Bot and Message Extension apps to Azure.
Run the deployed app
Once the provisioning and deployment steps are complete:
Open the debug panel (Ctrl+Shift+D / ⌘⇧-D or View > Run) from Visual Studio Code.
Select Launch Remote (Edge) from the launch configuration drop-down.
Select the Start debugging (F5) to launch your app from Azure.
Select Add.
The toolkit displays a message to indicate that the app is added to Teams.
- If you select Got it, you can try the app later from the list of Sideloaded apps.
- If you select Try it, Teams loads your app.
Your app is loaded on the Azure site.
Select Try it.
The Message Extension app is loaded in a chat bot app.
Learn what happens when you deployed your app to Azure
Before deployment, the application has been running locally:
- The backend runs using Azure Functions Core Tools.
- The application HTTP endpoint, where Microsoft Teams loads the application, runs locally.
Deployment is a two-step process. You provision the resources on an active Azure subscription, and then deploy or upload the backend and frontend code for the application to Azure.
- The backend, if configured, uses various Azure services, including Azure App Service and Azure Storage.
- The frontend application is deployed to an Azure Storage account configured for static web hosting.
Congratulations!
You've done it!
You've created a message extension app.
Now that you've learned to create a basic app, you can move on to creating more complex apps. Follow the procedures to build and deploy the app, and your app has multiple capabilities.
You've completed the tutorial to build message extension app with JavaScript.
Have an issue with this section? If so, please give us some feedback so we can improve this section.
Feedback
Submit and view feedback for