Build a bot-based message extension agent for Microsoft 365 Copilot

Start Microsoft Teams app development with your first Teams app. You can create a bot-based message extension agent using JavaScript.

In this tutorial, you'll learn:

• How to set up a new project with Teams Toolkit.
• How to build a bot-based message extension agent.
• How to deploy your app.
• Trigger your bot-based message extension agent in Microsoft 365 Copilot.

This step-by-step guide helps you to build bot-based message extension agent with Teams Toolkit. You'll see the following output after you've completed this guide:

Prerequisites

• 6 minutes remaining

Ensure you install the following tools for building and deploying your apps.

Prepare development environment

After you've installed the required tools, set up the development environment.

Install Teams Toolkit

Microsoft Teams Toolkit helps simplify the development process with tools to provision and deploy cloud resources for your app and publish to the Teams Store.

You can use Teams Toolkit with Visual Studio Code. To install Teams Toolkit, follow these steps:

1. Open Visual Studio Code and select Extensions (Ctrl+Shift+X / ⌘⇧-X or View > Extensions).

2. In the search box, enter Teams Toolkit.

3. On the Teams Toolkit page, select the dropdown arrow next to Install.

4. Select Install Pre-Release Version.

   The Teams Toolkit icon appears in the Visual Studio Code Activity Bar after it's installed.

Set up your Teams development tenant

A tenant is a space or a container for your organization in Teams, where you chat, share files, and run meetings. This space is also where you upload and test your app. Let's verify if you're ready to develop with the tenant.

Check for upload an app option

After creating the app, you must load your app in Teams without distributing it. This process is known as app uploading. Sign in to your Microsoft 365 account to view this option.

Custom app upload is enabled through a tenant and admin must give access to upload a custom app. Do you already have a tenant and an admin access? Let's check if you really do!

Verify if you can upload apps in Teams:

1. In the Teams client, select the Apps icon.

2. Select Manage your apps.

3. Select Upload an app.

4. Look for the option to Upload a custom app. If the option is visible, you've enabled custom app upload.

   

   Note

   Contact your Teams administrator, if you don't find the option to upload a custom app.

Create a free Teams developer tenant (optional)

If you don't have a Teams developer account, you can get it for free. Join the Microsoft 365 developer program!

1. Go to the Microsoft 365 developer program.

2. Select Join Now and follow the onscreen instructions.

3. In the welcome screen, select Set up E5 subscription.

4. Set up your administrator account. After you finish, the following screen appears.

   

5. Sign in to Teams using the administrator account you just set up. Verify that you've the Upload a custom app option in Teams.

Get a free Azure account

If you want 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

• 5 minutes remaining

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

In this tutorial, you'll learn:

1. How to set up a new message extension project with Teams Toolkit.
2. About the directory structure of your app project.

Create your message extension project workspace

If the prerequisites are in place, let's begin!

To create a bot-based message extension agent, follow these steps:

1. Open Visual Studio Code.

2. Select the Teams Toolkit icon in the Visual Studio Code Activity Bar.

3. Select Create a New App.

   

4. Select Message Extension to create an app using the Teams Toolkit.

   

5. Select Custom Search Results.

   

6. Select Start with a Bot.

   

7. Select JavaScript as the programming language.

   

8. Select Default folder to store your project root folder in default location.

   

   You can also change the default location by the following steps:

   1. Select Browse.

      

   2. Select the location for project workspace.

   3. Select the Select Folder.

      

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

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.

Build and run your first bot-based message extension agent

• 4 minutes remaining

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.

1. Open Visual Studio Code.

2. Select the Teams Toolkit icon in the sidebar.

3. Select Sign in to Microsoft 365 using your credentials.

   Your default web browser opens to let you sign in to the account.

4. Close the browser when prompted and return to Visual Studio Code.

5. 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 custom app upload 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

1. From the left pane, select Run and Debug (Ctrl+Shift+D).

2. Select Debug in Teams (Edge) or Debug in Teams (Chrome). Teams Toolkit launches your app in Teams using a web browser.

3. Select F5 to build and run your app locally.

   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:

   1. Checks all the following prerequisites:

   • You're logged in with a Microsoft 365 account.
   • Custom app upload is enabled for your Microsoft 365 account.
   • Supported Node.js version is installed.
   • Port required by bot app is available.

   2. Install npm packages
   3. Starts Dev Tunnel to create an HTTP tunnel.
   4. Registers the app in Microsoft Entra ID and configures the app.
   5. Registers the bot app in Bot Framework and configures the app.
   6. Registers the app in Teams Developer Portal and configures the app.
   7. Starts the message extension app hosted locally.
   8. Starts Teams in a web browser and uploads 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.

4. Select Add. The app is installed on Teams.

   

   As message extensions 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's 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

1. Go to a Teams chat and select Actions and apps.

2. From the message extension fly-out menu, enter the name of your message extension from the search box.

3. Select your message extension and enter your search query.

   

4. Select a product from the list. Teams unfurls the product into an Adaptive Card in the message Compose area.

5. Select Send. The Adaptive Card is sent.

   

Trigger your bot-based message extension agent in Microsoft 365 Copilot

• 3 minutes remaining

To trigger the message extension in Microsoft 365 Copilot, follow these steps:

1. From the left pane, select Teams Toolkit.

2. From the left pane, select Run and Debug (Ctrl+Shift+D).

3. Select Debug in Copilot (Edge) or Debug in Copilot (Chrome).

4. Select F5 to build and run your app in Microsoft 365 Copilot.

5. Go to Microsoft Teams > Apps.

6. Search for Copilot and open the app.

7. Select Panel from the top-right corner.

8. From the list of agents, select the required agent from the right pane.

   

9. From the message compose area, send a message to Microsoft 365 Copilot to search for the latest update from Teams and Microsoft 365 Copilot.

   

Deploy your first Teams app

• 2 minutes remaining

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.

1. Open Visual Studio Code.

2. Open the project folder in which you created the message extension app.

3. Select the Teams Toolkit icon in the sidebar.

4. 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're using in other extensions.

   Your default web browser opens to let you sign in to the account.

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

Select the Teams Toolkit icon in the Visual Studio Code sidebar.

1. Select Provision.

   

2. Select a subscription to use for the Azure resources.

   

   Your app is hosted using Azure resources. A dialog warns you that costs might be incurred when running resources in Azure.

3. Select Provision.

   

   The provisioning process creates resources in the Azure cloud. It might 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.

   

4. 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:

1. Open the debug panel (Ctrl+Shift+D / ⌘⇧-D or View > Run) from Visual Studio Code.

2. Select Launch Remote (Edge) from the launch configuration dropdown.

3. Select the Start debugging (F5) to launch your app from Azure.

   

4. Select Add.

   

Congratulations!

• 100% complete!

You've created a bot-based message extension and extended the message extension as an agent in Microsoft 365 Copilot.