Build and run your first messaging extension for Microsoft Teams

In this tutorial, you will learn how to create a search command to search for external data and insert the results into a message.

There are two types of Teams messaging extensions:

  • Search commands allow you to search external systems and insert the results of that search into a message in the form of a card.
  • Action commands allow you present your users with a modal popup to collect or display information, then process their interaction and send information back to Teams.

Before you begin

Make sure your development environment is set up by installing the Prerequisites.

Create your project

Use the Teams Toolkit to create your first project:

  1. Open Visual Studio Code.

  2. Select the Teams icon in the sidebar to open the Teams Toolkit.

    The Teams Icon in the Visual Studio Code sidebar.

  3. Select Create New Project.

    Location of the Create New Project link in the Teams Toolkit sidebar.

  4. Select Create a new Teams app.

    Wizard start for Create New Project

  5. In the Select capabilities section, select Message Extension, deselect Tab and select OK.

    Screenshot showing how to add capabilities to your new app.

  6. In the Bot registration section, select Create a new bot registration.

    Select create a new bot registration

    Note

    Messaging extensions rely on bots to provide a dialog between the user and your code.

  7. In the Programming Language section, select JavaScript.

    Screenshot showing how to select the programming language.

  8. Select a workspace folder. A folder will be created within your workspace folder for the project you are creating.

  9. Enter a suitable name for your app, like helloworld. The name of the app must consist only of alphanumeric characters. Press Enter to continue.

    Your Teams app will be created within a few seconds.

Take a tour of the source code

If you wish to skip this section for now, you can run your app locally.

A messaging extension uses the Bot Framework to allow the user to interact with your service via a conversation. After scaffolding, your project will look like this:

File layout of a bot project.

The bot code is stored in the bot directory. The bot/messageExtensionBot.js is the main entry point for the messaging extension.

Tip

Familiarize yourself with bots outside of Teams before you integrate your first bot within Teams. You can find more information about bots by reviewing the Azure Bot Service tutorials.

Run your app locally

Teams Toolkit allows you to host your app locally. To do this:

  • An Azure Active Directory Application is registered within the M365 tenant.
  • An app manifest is submitted to the Developer Portal for Teams.
  • An API is run locally using Azure Functions Core Tools to support your app.
  • ngrok is installed and used to provide a tunnel between Teams and your messaging extension.

To build and run your app locally:

  1. From Visual Studio Code, press the F5 key to run your application in debug mode.

    When you run the app for the first time, all dependencies are downloaded and the app is built. A browser window automatically opens when the build is complete. This can take 3-5 minutes to complete.

  2. Teams will be loaded in a web browser, and you will be prompted to sign in. If prompted to open Microsoft Teams, select Cancel to remain within the browser. Sign in with your M365 account.

  3. Select Add to add the app to your account.

    After the app is loaded, you can try to use the sample functionality: You can launch the message extension from three dots in the composing area and try search npm packages from the search bar.

    Your Search-based messaging extension in action

    You can also try to @ your message extension instance from search bar in the top row of Teams and search for npm package. Your Search-based messaging extension in action

    Type some text in the search box, then select one of the options, you can create and send adaptive cards of the search results. Your Search-based messaging extension in action

Learn what happens when you run your app locally in the debugger.

When you press the F5 key, the Teams Toolkit:

  1. Registers your application with Azure Active Directory.
  2. Registers your application for "side loading" in Microsoft Teams.
  3. Starts your application backend running locally using Azure Function Core Tools.
  4. Starts an ngrok tunnel so Teams can communicate with your app.
  5. Starts Microsoft Teams with a command to instruct Teams to sideload the application.
Learn how to troubleshoot common issues when running your app locally.

To successfully run your app in Teams, you must have a Microsoft 365 development account that allows app sideloading. For more information on account opening, see Prerequisites.

Tip

Check for issues before sideloading your app, using the app validation tool, which is included in the toolkit. Fix the errors to successfully sideload the app.

Deploy your app to Azure

Deployment consists of two steps. First, necessary cloud resources are created (also known as provisioning), then the code that makes up your app is copied into the created cloud resources.

  1. Open Visual Studio Code.

  2. Select the Teams Toolkit from the sidebar by selecting the Teams icon.

  3. Select Provision in the Cloud.

    Screenshot showing the provisioning commands

  4. If required, select a subscription to use for the Azure resources.

    Note

    There are always some Azure resources used for hosting your app.

  5. A dialog warns you that costs may be incurred when running resources in Azure. Press Provision.

    Screenshot of the provisioning dialog.

    The provisioning process creates resources in the Azure cloud. This takes 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:

    Screenshot showing the provisioning complete dialog.

  6. Once provisioning is complete, select Deploy to the Cloud. As with provisioning, this process 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.

Note

What's the difference between Provision and Deploy?

The Provision step creates resources in Azure and M365 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 is common to deploy multiple times without provisioning new resources. Since the provision step can take some time to complete, it is separate from the deployment step.

Once the provisioning and deployment steps are finished:

  1. From Visual Studio Code, open the debug panel (Ctrl+Shift+D / ⌘⇧-D or View > Run)
  2. Select Launch Remote (Edge) from the launch configuration drop-down.
  3. Press the Play button to launch your app - now running remotely from Azure!
Learn what happens when you deployed your app to Azure

Before deployment, the application has been running locally:

  1. The backend runs using Azure Functions Core Tools.
  2. The application HTTP endpoint, where Microsoft Teams loads the application, runs locally.

Deployment involves provisioning resources on an active Azure subscription and deploying (uploading) the backend and frontend code for the application to Azure. The backend uses a variety of Azure services, including Azure App Service and Azure Bot Service.

Add a configuration page to your messaging extension

Important

The code samples in this section are based on 4.6 and later versions of the Bot Framework SDK. If you're looking for documentation for earlier versions, see the Messaging Extensions - v3 SDK section in the Resources folder of the documentation.

Code sample

The Teams Search Auth Config for sample projects on GitHub, demonstrate how to create messaging extensions that include a configuration page and Bot Service authentication. The samples also demonstrate how to create message extensions that accept search requests and return the results after the user has signed in.

Sample name Description .NET Node.js Python
Bot builder To create messaging extensions. View View View

Additional code sample

See also