From d91e09cf533fd7fb1186a9e138708682387fcb4c Mon Sep 17 00:00:00 2001 From: v-shgarcha Date: Fri, 7 Nov 2025 16:08:40 +0530 Subject: [PATCH 01/10] Update build-message-extension.md --- .../get-started/build-message-extension.md | 107 ++++-------------- 1 file changed, 25 insertions(+), 82 deletions(-) diff --git a/msteams-platform/get-started/build-message-extension.md b/msteams-platform/get-started/build-message-extension.md index 03394927ae9..a8b6f38690e 100644 --- a/msteams-platform/get-started/build-message-extension.md +++ b/msteams-platform/get-started/build-message-extension.md @@ -12,97 +12,40 @@ A message extension allows the users to interact with your web service through b :::image type="content" border="false" source="../assets/images/get-started/get-started-me.png" alt-text="Screenshot shows you the conceptual message extension in Teams client."::: -In this tutorial, you'll learn to build a search-based message extension app, and the app allows users to search npm packages from the Node Package Manager (npm) directory. +Start Microsoft Teams app development with your first Teams app using JavaScript. -Get familiarized with search based message extension app in one of the following ways: +In this tutorial, you'll learn: -* **GitHub Codespaces**: The codespace instance allows you to experience a Teams app instantaneously. It opens Visual Studio Code (VS Code), where the Microsoft 365 Agents Toolkit (previously known as Teams Toolkit) extension, the app source code, and all the dependencies are pre-packaged for you. -* **Step-by-step guide**: Allows you to set up your development environment and build a Teams app from start. +- How to set up a new project with Microsoft 365 Agents Toolkit (previously known as Teams Toolkit). +- How to build a message extension app. +- How to deploy your app. -# [GitHub Codespaces](#tab/agentstoolkitcodespaces) +You'll see the following output after you complete this guide: -Before you create your codespace, ensure that you have the following prerequisites: +:::image type="content" source="../assets/images/toolkit-v2/first-msgext/app-added-mex-local-debug.png" alt-text="Screenshot shows the final output of the message extension app in Teams." lightbox="../assets/images/toolkit-v2/first-msgext/app-added-mex-local-debug.png"::: -* A GitHub account to create your codespace instance -* A [Microsoft 365 account](https://developer.microsoft.com/microsoft-365/dev-program) with custom app upload permission -* A [Microsoft 365 tenant](../concepts/build-and-test/prepare-your-o365-tenant.md) +## Prerequisites -> [!TIP] -> [GitHub Codespaces](https://github.com/features/codespaces) offers free plan up to a fixed amount of usage per month. If you need to free up more space, go to [github.com/codespaces](https://github.com/codespaces) and delete the codespaces that you no longer need. +Ensure you install the following tools for building and deploying your apps. -To create a search-based message extension app with GitHub Codespaces, follow these steps: + |   | Install | For using... | + | --- | --- | --- | + | **Required** |   |   | + |   | [Visual Studio Code](https://code.visualstudio.com/download) | JavaScript or TypeScript build environments. Use the latest version. | + |   | [Microsoft 365 Agents Toolkit](#install-microsoft-365-agents-toolkit) | Microsoft Visual Studio Code extension that creates a project scaffolding for your app. Use the latest version.| + |   | [Node.js](https://nodejs.org/en/download/) | Backend JavaScript runtime environment. For more information, see [Node.js version compatibility table](~/toolkit/build-environments.md#nodejs-version-compatibility-table-for-project-type).| + |   | [Microsoft Teams](https://www.microsoft.com/microsoft-teams/download-app) | Collaborate with people you work with through apps for chats, meetings, and calls in one place.| + |   | [Microsoft Edge](https://www.microsoft.com/edge) (recommended) or [Google Chrome](https://www.google.com/chrome/) | A browser with developer tools essential for debugging and testing. | + |   | [Microsoft 365 developer account](/microsoftteams/platform/concepts/build-and-test/prepare-your-o365-tenant) | Access to Teams account with appropriate permissions to install a custom app. | + | **Optional** |   |   | + |   | [Azure Tools for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-vscode.vscode-node-azure-pack) and [Azure CLI](/cli/azure/install-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](https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi) or [React Developer Tools for Microsoft Edge](https://microsoftedge.microsoft.com/addons/detail/react-developer-tools/gpphkfbcpidddadnkolkpfckpihlkkil) | A browser DevTools extension for the open-source React JavaScript library. | -1. Select the following button to open GitHub Codespaces. - - Open message extension in GitHub Codespaces - - You might be asked to sign in to GitHub account if you haven't already. - -1. Select **Create new codespace**. - - :::image type="content" source="../assets/images/get-started/codespace.png" alt-text="Screenshot shows you the GitHub page to create a codespace for message extension."::: - - The **Setting up your codespace** page appears. - - :::image type="content" source="../assets/images/get-started/building-codespace.png" alt-text="Screenshot shows you the codespace building your message extension."::: - - Agents Toolkit prepares the message extension for you and opens it in VS Code in the browser. The Microsoft 365 Agents Toolkit icon appears in the activity bar of VS Code. - -1. Select **Sign in to your Microsoft 365** and **Sign in to Azure** to sign in with your Microsoft 365 account. - - :::image type="content" source="../assets/images/get-started/codespace/me-sign-in.png" alt-text="Screenshot shows you the Agents Toolkit window in browser to sign in."lightbox="../assets/images/get-started/add-tab-in-teams.png"::: - - > [!NOTE] - > - > When you build your app, GitHub Codespaces loads it to the Teams client in a new tab. If your browser blocks pop-up tabs or windows, you'll need to allow pop-ups for your app to open. - -1. Select **Preview your Teams App (F5)** to build your message extension. - - :::image type="content" source="../assets/images/get-started/codespace/me-preview-teams.png" alt-text="Screenshot shows you the Agents Toolkit window in browser with your message extension."lightbox="../assets/images/get-started/codespace/me-preview-teams.png"::: - - GitHub Codespaces builds your message extension app, loads it to Teams client, and opens in a separate browser tab. - -1. Select **Add** to install your message extension in Teams. - - :::image type="content" source="../assets/images/get-started/codespace/me-in-teams.png" alt-text="Screenshot of the app details dialog to add the message extension app in Teams."::: - -1. Select **Open** to open the app in personal scope. - - :::image type="content" source="../assets/images/get-started/codespace/me-in-teams-scope.png" alt-text="Screenshot of the scope selection dialog to open the app in personal scope."::: - - You've successfully created the search-based message extension and loaded in the Teams client. - - :::image type="content" source="../assets/images/get-started/codespace/me-teams-chat.png" alt-text="Screenshot shows your message extension loaded in the Teams client."::: - - > [!div class="nextstepaction"] - > [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Build+a+message+extension+app+using+GitHub+Codespaces&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fget-started%2Fbuild-message-extension%3Ftabs%3Dagentstoolkitcodespaces&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fget-started%2Fbuild-message-extension.md&documentVersionIndependentId=4f4e5027-7a0b-30e1-dc4b-d2bd8daee892&platformId=03898b42-3609-cc37-16a8-a24f488a9b12&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) - -# [Step-by-step guide](#tab/step-by-step-guide) - -If you want to learn how to start a project with Agents Toolkit from the beginning, you'll need to set up your development environment. Select the following button to start building your message extension app. - -> [!div class="nextstepaction"] -> [Build your first message extension app using JavaScript](../sbs-gs-msgext.yml) - ---- - -For more information on message extensions, see [message extensions](../messaging-extensions/what-are-messaging-extensions.md). - -If a bot is what you are interested in, select the following: - -> [!div class="nextstepaction"] -> [Start building a bot](build-notification-bot.md) - -If you want to build basic tab app, select the following: - -> [!div class="nextstepaction"] -> [Build your basic tab app](build-basic-tab-app.md) - -## Next step +[!INCLUDE [Set up prerequisites](includes/get-started/prepare-toolkit.md)] > [!div class="nextstepaction"] -> [Tool options and code samples](tool-options-and-code-samples.md) +> [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Prepare+development+environment&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fsbs-gs-msgext%3Ftabs%3Dvscode%252Cvsc1%252Cvsc2%252Cmsgext%252Cvsc3%252Cvsc4%26tutorial-step%3D1&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fsbs-gs-msgext.yml&documentVersionIndependentId=d0c82a43-2f4a-ad2e-251e-922e2e357806&platformId=e2feec5c-06f2-6065-f4a5-2e2947f00b97&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) -## See also +## Get a free Azure account -[npm directory](https://www.npmjs.com/) +If you want to host your app or access resources in Azure, you must have an Azure subscription. [Create a free account](https://azure.microsoft.com/free/) before you begin. From 6814c27323f5a14a5ccd04e599b6f218d7ce104e Mon Sep 17 00:00:00 2001 From: v-shgarcha Date: Fri, 7 Nov 2025 17:01:53 +0530 Subject: [PATCH 02/10] Update build-message-extension.md --- .../get-started/build-message-extension.md | 236 +++++++++++++++++- 1 file changed, 235 insertions(+), 1 deletion(-) diff --git a/msteams-platform/get-started/build-message-extension.md b/msteams-platform/get-started/build-message-extension.md index a8b6f38690e..97ded22cf52 100644 --- a/msteams-platform/get-started/build-message-extension.md +++ b/msteams-platform/get-started/build-message-extension.md @@ -41,7 +41,7 @@ Ensure you install the following tools for building and deploying your apps. |   | [Azure Tools for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-vscode.vscode-node-azure-pack) and [Azure CLI](/cli/azure/install-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](https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi) or [React Developer Tools for Microsoft Edge](https://microsoftedge.microsoft.com/addons/detail/react-developer-tools/gpphkfbcpidddadnkolkpfckpihlkkil) | A browser DevTools extension for the open-source React JavaScript library. | -[!INCLUDE [Set up prerequisites](includes/get-started/prepare-toolkit.md)] +[!INCLUDE [Set up prerequisites](../includes/get-started/prepare-toolkit.md)] > [!div class="nextstepaction"] > [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Prepare+development+environment&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fsbs-gs-msgext%3Ftabs%3Dvscode%252Cvsc1%252Cvsc2%252Cmsgext%252Cvsc3%252Cvsc4%26tutorial-step%3D1&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fsbs-gs-msgext.yml&documentVersionIndependentId=d0c82a43-2f4a-ad2e-251e-922e2e357806&platformId=e2feec5c-06f2-6065-f4a5-2e2947f00b97&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) @@ -49,3 +49,237 @@ Ensure you install the following tools for building and deploying your apps. ## 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](https://azure.microsoft.com/free/) before you begin. + +## Create project workspace for your message extension app + +Now, let's create your first message extension app. + +The message extension capability lets you interact with a web service through buttons and forms. Use the message compose area, command box, or a message directly in Teams client to search and initiate actions in an external system. Message extensions rely on bots to provide a dialog between the user and your code. + +:::image type="content" source="../assets/images/toolkit-v2/first-msgext/your-helloworld-app-msgext.png" alt-text="Diagram shows Screenshot shows the different types of app features with message extension highlighted."::: + +There are two types of Teams message extensions: + +- [Search commands](../msteams-platform/messaging-extensions/how-to/search-commands/define-search-command.md): You can search external systems and insert the results into a message in the form of a card. +- [Action commands](../msteams-platform/messaging-extensions/how-to/action-commands/define-action-command.md): You can present your users with a modal pop-up to collect or display information. Then, you can process their interaction and send the information back to Teams. + +Let's create a message extension app with a search command. First, 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 Agents Toolkit.](#create-your-message-extension-project-workspace) +1. [About the directory structure of your app project.](#take-a-tour-of-the-message-extension-app-source-code) + +## Create your message extension project workspace + +If the prerequisites are in place, let's begin! + +> [!NOTE] +> The Visual Studio Code UI shown may differ for you depending on your operating system, Toolkit version, theme, and environment. + +# [Visual Studio Code](#tab/vsc1) + +1. Open Visual Studio Code. + +1. Select the Microsoft 365 Agents Toolkit :::image type="icon" source="../assets/images/toolkit-v2/toolkit-sidebar-icon.png"::: icon in the Visual Studio Code activity bar. + +1. Select **Create a New Agent/App** > **Teams App**. + +:::image type="content" source="../assets/images/toolkit-v2/first-msgext/create-project.png" alt-text="Screenshot shows the option to create a new app from the Agents Toolkit sidebar."::: + +1. Select **Message Extension**. + +:::image type="content" source="../assets/images/toolkit-v2/first-msgext/create-new-app1.png" alt-text="Screenshot shows the option to create a new Teams app."::: + +1. Select **Custom Search Results**. + +:::image type="content" source="..assets/images/toolkit-v2/first-msgext/select-capabilities-mex1.png" alt-text="Screenshot shows the option to select the capabilities of a new app."::: + +1. Select **Start with a Bot**. + +:::image type="content" source="../assets/images/toolkit-v2/first-msgext/select-architecture-mex.png" alt-text="Screenshot shows the options for the architecture of the message extension."::: + +1. Select **JavaScript**. + +:::image type="content" source="../assets/images/toolkit-v2/first-msgext/select-language-tab.png" alt-text="Screenshot shows the option to select the programming language."::: + +1. Select **Default folder** to store your project root folder in default location. + +:::image type="content" source="../assets/images/toolkit-v2/first-msgext/select-default-location.png" alt-text="Screenshot shows the selection of default location."::: + +You can also change the default location by the following steps: + +1. Select **Browse**. + +:::image type="content" source="../assets/images/toolkit-v2/first-msgext/select-browse.png" alt-text="Screenshot shows the browse option."::: + +1. Select the location for project workspace. + +1. Select **Select Folder**. + +:::image type="content" source=".. /assets/images/toolkit-v2/select-folder.png" alt-text="Screenshot shows how to select the location for the project workspace folder."::: + +1. Enter a suitable name for your app. Select **Enter**. + +:::image type="content" source="..assets/images/toolkit-v2/first-msgext/enter-project-name.png" alt-text="Screenshot shows the option to enter the app name."::: + +Agents Toolkit creates the app in a few seconds. + +:::image type="content" source="../msteams-platform/assets/images/toolkit-v2/first-msgext/app-created-mex.png" alt-text="Screenshot shows the newly created message extension app." lightbox="../msteams-platform/assets/images/toolkit-v2/first-msgext/app-created-mex.png"::: + +After your app is created, Agents Toolkit displays the following message: + +:::image type="content" source="../msteams-platform/assets/images/toolkit-v2/preview-project-msg.png" alt-text="Screenshot shows a dialog saying that the message extension app is created."::: + +> [!div class="nextstepaction"] +> [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Create+your+message+extension+project+workspace+using+Visual+Studio+Code&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fsbs-gs-msgext%3Ftabs%3Dvscode%252Cvsc1%252Cvsc2%252Cmsgext%252Cvsc3%252Cvsc4%26tutorial-step%3D2&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fsbs-gs-msgext.yml&documentVersionIndependentId=d0c82a43-2f4a-ad2e-251e-922e2e357806&platformId=e2feec5c-06f2-6065-f4a5-2e2947f00b97&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) + +# [Command Line](#tab/cli1) + +Use the `atk' CLI to create your first project. + +1. Go to the folder where you want to create the project folder and open Command Prompt. + +1. Enter the following command to create a new Teams app: + +``` bash +atk new +``` + +1. CLI provides you with a series of options to choose from. Use arrow keys to select an option. After you make the choice, select Enter to confirm. + +1. Select **Message Extension** for **New Project**. +1. Select **Custom Search Results** for **App Features Using a Message Extension**. +1. Select **Start with a Bot** for **Architecture of Search Based Message Extension**. +1. Select **JavaScript** for **Programming Language**. +1. Select **Enter** to select the default workspace folder for your app. +1. Enter a suitable name for your app. The name of the app must consist only of alphanumeric characters. + +CLI creates the project after you answer all the questions. + +> [!div class="nextstepaction"] +> [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Create+your+message+extension+project+workspace+using+Command+Line&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fsbs-gs-msgext%3Ftabs%3Dvscode%252Ccli1%252Cvsc2%252Cmsgext%252Cvsc3%252Cvsc4%26tutorial-step%3D2&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fsbs-gs-msgext.yml&documentVersionIndependentId=d0c82a43-2f4a-ad2e-251e-922e2e357806&platformId=e2feec5c-06f2-6065-f4a5-2e2947f00b97&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) + + --- + +## Take a tour of the message extension app source code + +A message extension uses Bot Framework to interact with your service through a conversation. After scaffolding, view the project directories and files under **EXPLORER**. + +:::image type="content" source="../assets/images/toolkit-v2/first-msgext/folder-structure-mex-app.png" alt-text="Screenshot shows the files of the message extension app."::: + + | Folder / File | Contents | + | --- | --- | + | `m365agents.yml` | Main project file describes your application configuration and defines the set of actions to run in each lifecycle stage. | + | `m365agents.local.yml` | Overrides `m365agents.yml` with actions that enable local execution and debugging. | + | `.vscode/` | Visual Studio Code files for local debug. | + | `appPackage/` | Templates for the Teams application manifest. | + | `infra/` | Templates for provisioning Azure resources. | + | `index.js` | Application entry point and `express` 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 Agents Toolkit, it's time to build your project. You need to sign in to your Microsoft 365 account. + +### Sign in to your Microsoft 365 account + +Sign in with the admin account you created while joining the Microsoft 365 developer program. + +# [Visual Studio Code](#tab/vsc2) + +1. Open Visual Studio Code. + +1. Select the Microsoft 365 Agents Toolkit :::image type="icon" source="../assets/images/toolkit-v2/toolkit-sidebar-icon.png"::: icon in the activity bar. + +1. Select **Sign in to Microsoft 365** using your credentials. Your default web browser opens to let you sign in. + +:::image type="content" source="../assets/images/toolkit-v2/toolkit-sign-in-m365.png" alt-text="Screenshot shows where to sign in to Microsoft 365 and Azure."::: + +1. Close the browser after signing in using your credentials. + +1. Return to Agents Toolkit within Visual Studio Code. + +The **ACCOUNTS** section of the sidebar shows your Microsoft 365 account name. If custom app upload is enabled for your Microsoft 365 account, Agents Toolkit displays **Custom App Upload Enabled**. + +:::image type="content" source="../assets/images/toolkit-v2/first-tab/m365-uploading-enabled-msg.png" alt-text="Screenshot shows the user signed in to Microsoft 365 and the uploading enabled message."::: + +Now you're ready to build the app and run it locally! + +> [!div class="nextstepaction"] +> [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Sign+in+to+your+Microsoft+365+account+using+Visual+Studio+Code&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fsbs-gs-msgext%3Ftabs%3Dvscode%252Cvsc1%252Cvsc2%252Cmsgext%252Cvsc3%252Cvsc4%26tutorial-step%3D3&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fsbs-gs-msgext.yml&documentVersionIndependentId=d0c82a43-2f4a-ad2e-251e-922e2e357806&platformId=e2feec5c-06f2-6065-f4a5-2e2947f00b97&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) + +# [Command Line](#tab/cli2) + +1. Go to the project folder of your message extension app and open Command Prompt. + +1. Sign in to Microsoft 365 with Microsoft 365 Agents Toolkit CLI (previously known as TeamsFx CLI) command: + +``` bash + atk account login m365 +``` + +Your default web browser opens to let you sign in. Sign in to your Azure account using your credentials. Close the browser when you're prompted. + +> [!div class="nextstepaction"] +> [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Sign+in+to+your+Microsoft+365+account+using+Command+Line&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fsbs-gs-msgext%3Ftabs%3Dvscode%252Ccli1%252Cvsc2%252Cmsgext%252Cvsc3%252Cvsc4%26tutorial-step%3D3&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fsbs-gs-msgext.yml&documentVersionIndependentId=d0c82a43-2f4a-ad2e-251e-922e2e357806&platformId=e2feec5c-06f2-6065-f4a5-2e2947f00b97&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) + + --- + +## Build and run your app in the local environment + + Now you can build and debug your first Teams message extension app locally. + +### Build and run your app locally + + 1. Select the **F5** key in Visual Studio Code to run your application in debug mode. + +> [!NOTE] +> If Agents Toolkit is unable to verify a particular prerequisite, it prompts you to check. + +
+
+Learn what happens when you run your app locally in the debugger. + +When you select **F5**, Agents Toolkit performs the following functions: + +1. Checks the following prerequisites: + + 1. You're signed in with a Microsoft 365 account. + 1. Custom app upload is enabled for your Microsoft 365 account. + 1. Supported Node.js version is installed. + 1. Port required by bot app is available. + +2. Installs 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. + +
+ +:::image type="content" source="../assets/images/toolkit-v2/first-msgext/f5-build-and-run-mex.png" alt-text="Screenshot shows the debug process of the message extension app." lightbox="../assets/images/toolkit-v2/first-msgext/f5-build-and-run-mex.png"::: + +When you debug the app for the first time, Teams downloads the dependencies and builds the app. This process can take 3 to 5 minutes to complete. + +1. Teams opens in a browser window when the build is complete. Sign in with your Microsoft 365 account, if prompted. + +1. A dialog box opens to let you add the message extension app to Teams. Select **Add**. + +:::image type="content" source="../assets/images/toolkit-v2/first-msgext/add-mex-app-local-debug-latest.png" alt-text="Screenshot shows the option to add the custom app in Teams." lightbox="../msteams-platform/assets/images/toolkit-v2/first-msgext/add-mex-app-local-debug.png"::: + +Teams loads the message extension app. + +:::image type="content" source="../assets/images/toolkit-v2/first-msgext/app-added-mex-local-debug-2.png" alt-text="Screenshot shows the message extension app open in a Teams bot chat." lightbox="../msteams-platform/assets/images/toolkit-v2/first-msgext/app-added-mex-local-debug-2.png"::: + +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 created a bot app before you created the message extension app, Teams loads the message extension in the bot app you created. Previous chat messages of the bot app are visible. +- If you created a message extension first, Teams loads your app in the most recent chat that is open on Teams. + +> [!div class="nextstepaction"] +> [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Build+and+run+your+app+locally&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fsbs-gs-msgext%3Ftabs%3Dvscode%252Cvsc1%252Cvsc2%252Cmsgext%252Cvsc3%252Cvsc4%26tutorial-step%3D3&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fsbs-gs-msgext.yml&documentVersionIndependentId=d0c82a43-2f4a-ad2e-251e-922e2e357806&platformId=e2feec5c-06f2-6065-f4a5-2e2947f00b97&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) From 63474c724b6a39ce1da98d1c2d865415a1d6d323 Mon Sep 17 00:00:00 2001 From: v-shgarcha Date: Fri, 7 Nov 2025 17:25:03 +0530 Subject: [PATCH 03/10] Update build-message-extension.md --- .../get-started/build-message-extension.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/msteams-platform/get-started/build-message-extension.md b/msteams-platform/get-started/build-message-extension.md index 97ded22cf52..e6904dd2f1d 100644 --- a/msteams-platform/get-started/build-message-extension.md +++ b/msteams-platform/get-started/build-message-extension.md @@ -60,8 +60,8 @@ The message extension capability lets you interact with a web service through bu There are two types of Teams message extensions: -- [Search commands](../msteams-platform/messaging-extensions/how-to/search-commands/define-search-command.md): You can search external systems and insert the results into a message in the form of a card. -- [Action commands](../msteams-platform/messaging-extensions/how-to/action-commands/define-action-command.md): You can present your users with a modal pop-up to collect or display information. Then, you can process their interaction and send the information back to Teams. +- [Search commands](../messaging-extensions/how-to/search-commands/define-search-command.md): You can search external systems and insert the results into a message in the form of a card. +- [Action commands](../messaging-extensions/how-to/action-commands/define-action-command.md): You can present your users with a modal pop-up to collect or display information. Then, you can process their interaction and send the information back to Teams. Let's create a message extension app with a search command. First, set up a new Teams project for creating the message extension app. @@ -93,7 +93,7 @@ If the prerequisites are in place, let's begin! 1. Select **Custom Search Results**. -:::image type="content" source="..assets/images/toolkit-v2/first-msgext/select-capabilities-mex1.png" alt-text="Screenshot shows the option to select the capabilities of a new app."::: +:::image type="content" source="../assets/images/toolkit-v2/first-msgext/select-capabilities-mex1.png" alt-text="Screenshot shows the option to select the capabilities of a new app."::: 1. Select **Start with a Bot**. @@ -117,19 +117,19 @@ You can also change the default location by the following steps: 1. Select **Select Folder**. -:::image type="content" source=".. /assets/images/toolkit-v2/select-folder.png" alt-text="Screenshot shows how to select the location for the project workspace folder."::: +:::image type="content" source="../assets/images/toolkit-v2/select-folder.png" alt-text="Screenshot shows how to select the location for the project workspace folder."::: 1. Enter a suitable name for your app. Select **Enter**. -:::image type="content" source="..assets/images/toolkit-v2/first-msgext/enter-project-name.png" alt-text="Screenshot shows the option to enter the app name."::: +:::image type="content" source="../assets/images/toolkit-v2/first-msgext/enter-project-name.png" alt-text="Screenshot shows the option to enter the app name."::: Agents Toolkit creates the app in a few seconds. -:::image type="content" source="../msteams-platform/assets/images/toolkit-v2/first-msgext/app-created-mex.png" alt-text="Screenshot shows the newly created message extension app." lightbox="../msteams-platform/assets/images/toolkit-v2/first-msgext/app-created-mex.png"::: +:::image type="content" source="../assets/images/toolkit-v2/first-msgext/app-created-mex.png" alt-text="Screenshot shows the newly created message extension app." lightbox="../assets/images/toolkit-v2/first-msgext/app-created-mex.png"::: After your app is created, Agents Toolkit displays the following message: -:::image type="content" source="../msteams-platform/assets/images/toolkit-v2/preview-project-msg.png" alt-text="Screenshot shows a dialog saying that the message extension app is created."::: +:::image type="content" source="../assets/images/toolkit-v2/preview-project-msg.png" alt-text="Screenshot shows a dialog saying that the message extension app is created."::: > [!div class="nextstepaction"] > [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Create+your+message+extension+project+workspace+using+Visual+Studio+Code&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fsbs-gs-msgext%3Ftabs%3Dvscode%252Cvsc1%252Cvsc2%252Cmsgext%252Cvsc3%252Cvsc4%26tutorial-step%3D2&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fsbs-gs-msgext.yml&documentVersionIndependentId=d0c82a43-2f4a-ad2e-251e-922e2e357806&platformId=e2feec5c-06f2-6065-f4a5-2e2947f00b97&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) @@ -270,11 +270,11 @@ When you debug the app for the first time, Teams downloads the dependencies and 1. A dialog box opens to let you add the message extension app to Teams. Select **Add**. -:::image type="content" source="../assets/images/toolkit-v2/first-msgext/add-mex-app-local-debug-latest.png" alt-text="Screenshot shows the option to add the custom app in Teams." lightbox="../msteams-platform/assets/images/toolkit-v2/first-msgext/add-mex-app-local-debug.png"::: +:::image type="content" source="../assets/images/toolkit-v2/first-msgext/add-mex-app-local-debug-latest.png" alt-text="Screenshot shows the option to add the custom app in Teams." lightbox="../assets/images/toolkit-v2/first-msgext/add-mex-app-local-debug.png"::: Teams loads the message extension app. -:::image type="content" source="../assets/images/toolkit-v2/first-msgext/app-added-mex-local-debug-2.png" alt-text="Screenshot shows the message extension app open in a Teams bot chat." lightbox="../msteams-platform/assets/images/toolkit-v2/first-msgext/app-added-mex-local-debug-2.png"::: +:::image type="content" source="../assets/images/toolkit-v2/first-msgext/app-added-mex-local-debug-2.png" alt-text="Screenshot shows the message extension app open in a Teams bot chat." lightbox="../assets/images/toolkit-v2/first-msgext/app-added-mex-local-debug-2.png"::: 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. From 1005745318902bd639c7ba1abfd7f514fbfc78e1 Mon Sep 17 00:00:00 2001 From: v-shgarcha Date: Mon, 10 Nov 2025 09:24:25 +0530 Subject: [PATCH 04/10] Update build-message-extension.md --- .../get-started/build-message-extension.md | 51 +++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/msteams-platform/get-started/build-message-extension.md b/msteams-platform/get-started/build-message-extension.md index e6904dd2f1d..651af30d683 100644 --- a/msteams-platform/get-started/build-message-extension.md +++ b/msteams-platform/get-started/build-message-extension.md @@ -283,3 +283,54 @@ As message extension apps rely on bots for enabling communication between the us > [!div class="nextstepaction"] > [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Build+and+run+your+app+locally&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fsbs-gs-msgext%3Ftabs%3Dvscode%252Cvsc1%252Cvsc2%252Cmsgext%252Cvsc3%252Cvsc4%26tutorial-step%3D3&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fsbs-gs-msgext.yml&documentVersionIndependentId=d0c82a43-2f4a-ad2e-251e-922e2e357806&platformId=e2feec5c-06f2-6065-f4a5-2e2947f00b97&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) + +### 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. + +### How to run a search query + +# [Message Extension](#tab/msgext) + +1. Enter the name of an open-source npm package in the search box of the message extension, such as **cli**. The message extension displays a list of the matching items. + +:::image type="content" source="..assets/images/toolkit-v2/first-msgext/mex-search-string.png" alt-text="Screenshot shows a search string in the message extension app."::: + +1. Select one of the items from the list. The app creates an Adaptive Card with the item in the message compose area so you can send it in a chat or channel. + +:::image type="content" source="../assets/images/toolkit-v2/first-msgext/mex-search-result.png" alt-text="Screenshot shows the search result in the message compose area."::: + +1. Select **Enter**. The message extension app sends the Adaptive Card with the item in the chat or channel. + +:::image type="content" source="../assets/images/toolkit-v2/first-msgext/mex-search-sent.png" alt-text="Screenshot shows the search result sent in chat."::: + +> [!div class="nextstepaction"] +> [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+How+to+run+a+search+query+using+Message+Extension&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fsbs-gs-msgext%3Ftabs%3Dvscode%252Cvsc1%252Cvsc2%252Cmsgext%252Cvsc3%252Cvsc4%26tutorial-step%3D3&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fsbs-gs-msgext.yml&documentVersionIndependentId=d0c82a43-2f4a-ad2e-251e-922e2e357806&platformId=e2feec5c-06f2-6065-f4a5-2e2947f00b97&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) + +# [Command Box](#tab/cmdbox) + +1. Enter **/** followed by your message extension app's name in the command box. + +:::image type="content" source="../assets/images/toolkit-v2/first-msgext/mention-mex-app.png" alt-text="Screenshot shows how to invoke the message extension app."::: + +The message extension app opens in the command box. + +1. Enter a name of an open-source npm package and select one of the search results. + +:::image type="content" source=".. /assets/images/toolkit-v2/first-msgext/command-box-search.png" alt-text="Screenshot shows a search string in the command box."::: + + The message extension displays the search result as an Adaptive Card in the command box. +:::image type="content" source="../assets/images/toolkit-v2/first-msgext/command-search-card.png" alt-text="Screenshot shows the search result as a card in the command box."::: + +1. Copy the Adaptive Card to paste it in the message compose area. + +:::image type="content" source="../assets/images/toolkit-v2/first-msgext/command-search-card-send.png" alt-text="Screenshot shows search result in a card in the message compose area."::: + +1. Select **Enter**. The message extension app sends the Adaptive Card with the search result in the most recent chat. + +:::image type="content" source="../assets/images/toolkit-v2/first-msgext/command-search-card-sent.png" alt-text="Screenshot shows the search result sent in a chat."::: + +> [!div class="nextstepaction"] +> [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+How+to+run+a+search+query+using+Command+Box&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fsbs-gs-msgext%3Ftabs%3Dvscode%252Cvsc1%252Cvsc2%252Ccmdbox%252Cvsc3%252Cvsc4%26tutorial-step%3D3&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fsbs-gs-msgext.yml&documentVersionIndependentId=d0c82a43-2f4a-ad2e-251e-922e2e357806&platformId=e2feec5c-06f2-6065-f4a5-2e2947f00b97&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) + + --- From e93aff3501cfd6d7028eaa73c7045905627a5851 Mon Sep 17 00:00:00 2001 From: v-shgarcha Date: Mon, 10 Nov 2025 12:31:35 +0530 Subject: [PATCH 05/10] Update build-message-extension.md --- .../get-started/build-message-extension.md | 219 ++++++++++++++---- 1 file changed, 174 insertions(+), 45 deletions(-) diff --git a/msteams-platform/get-started/build-message-extension.md b/msteams-platform/get-started/build-message-extension.md index 651af30d683..fad4afec36f 100644 --- a/msteams-platform/get-started/build-message-extension.md +++ b/msteams-platform/get-started/build-message-extension.md @@ -46,7 +46,7 @@ Ensure you install the following tools for building and deploying your apps. > [!div class="nextstepaction"] > [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Prepare+development+environment&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fsbs-gs-msgext%3Ftabs%3Dvscode%252Cvsc1%252Cvsc2%252Cmsgext%252Cvsc3%252Cvsc4%26tutorial-step%3D1&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fsbs-gs-msgext.yml&documentVersionIndependentId=d0c82a43-2f4a-ad2e-251e-922e2e357806&platformId=e2feec5c-06f2-6065-f4a5-2e2947f00b97&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) -## Get a free Azure account +### 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](https://azure.microsoft.com/free/) before you begin. @@ -85,43 +85,43 @@ If the prerequisites are in place, let's begin! 1. Select **Create a New Agent/App** > **Teams App**. -:::image type="content" source="../assets/images/toolkit-v2/first-msgext/create-project.png" alt-text="Screenshot shows the option to create a new app from the Agents Toolkit sidebar."::: + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/create-project.png" alt-text="Screenshot shows the option to create a new app from the Agents Toolkit sidebar."::: -1. Select **Message Extension**. +4. Select **Message Extension**. -:::image type="content" source="../assets/images/toolkit-v2/first-msgext/create-new-app1.png" alt-text="Screenshot shows the option to create a new Teams app."::: + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/create-new-app1.png" alt-text="Screenshot shows the option to create a new Teams app."::: -1. Select **Custom Search Results**. +5. Select **Custom Search Results**. -:::image type="content" source="../assets/images/toolkit-v2/first-msgext/select-capabilities-mex1.png" alt-text="Screenshot shows the option to select the capabilities of a new app."::: + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/select-capabilities-mex1.png" alt-text="Screenshot shows the option to select the capabilities of a new app."::: -1. Select **Start with a Bot**. +6. Select **Start with a Bot**. -:::image type="content" source="../assets/images/toolkit-v2/first-msgext/select-architecture-mex.png" alt-text="Screenshot shows the options for the architecture of the message extension."::: + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/select-architecture-mex.png" alt-text="Screenshot shows the options for the architecture of the message extension."::: -1. Select **JavaScript**. +7. Select **JavaScript**. -:::image type="content" source="../assets/images/toolkit-v2/first-msgext/select-language-tab.png" alt-text="Screenshot shows the option to select the programming language."::: + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/select-language-tab.png" alt-text="Screenshot shows the option to select the programming language."::: -1. Select **Default folder** to store your project root folder in default location. +8. Select **Default folder** to store your project root folder in default location. -:::image type="content" source="../assets/images/toolkit-v2/first-msgext/select-default-location.png" alt-text="Screenshot shows the selection of default location."::: + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/select-default-location.png" alt-text="Screenshot shows the selection of default location."::: You can also change the default location by the following steps: 1. Select **Browse**. -:::image type="content" source="../assets/images/toolkit-v2/first-msgext/select-browse.png" alt-text="Screenshot shows the browse option."::: + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/select-browse.png" alt-text="Screenshot shows the browse option."::: -1. Select the location for project workspace. +2. Select the location for project workspace. -1. Select **Select Folder**. +3. Select **Select Folder**. -:::image type="content" source="../assets/images/toolkit-v2/select-folder.png" alt-text="Screenshot shows how to select the location for the project workspace folder."::: + :::image type="content" source="../assets/images/toolkit-v2/select-folder.png" alt-text="Screenshot shows how to select the location for the project workspace folder."::: -1. Enter a suitable name for your app. Select **Enter**. +4. Enter a suitable name for your app. Select **Enter**. -:::image type="content" source="../assets/images/toolkit-v2/first-msgext/enter-project-name.png" alt-text="Screenshot shows the option to enter the app name."::: + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/enter-project-name.png" alt-text="Screenshot shows the option to enter the app name."::: Agents Toolkit creates the app in a few seconds. @@ -146,14 +146,14 @@ Use the `atk' CLI to create your first project. atk new ``` -1. CLI provides you with a series of options to choose from. Use arrow keys to select an option. After you make the choice, select Enter to confirm. +3. CLI provides you with a series of options to choose from. Use arrow keys to select an option. After you make the choice, select Enter to confirm. -1. Select **Message Extension** for **New Project**. -1. Select **Custom Search Results** for **App Features Using a Message Extension**. -1. Select **Start with a Bot** for **Architecture of Search Based Message Extension**. -1. Select **JavaScript** for **Programming Language**. -1. Select **Enter** to select the default workspace folder for your app. -1. Enter a suitable name for your app. The name of the app must consist only of alphanumeric characters. +4. Select **Message Extension** for **New Project**. +5. Select **Custom Search Results** for **App Features Using a Message Extension**. +6. Select **Start with a Bot** for **Architecture of Search Based Message Extension**. +7. Select **JavaScript** for **Programming Language**. +8. Select **Enter** to select the default workspace folder for your app. +9. Enter a suitable name for your app. The name of the app must consist only of alphanumeric characters. CLI creates the project after you answer all the questions. @@ -196,15 +196,15 @@ Sign in with the admin account you created while joining the Microsoft 365 devel 1. Select **Sign in to Microsoft 365** using your credentials. Your default web browser opens to let you sign in. -:::image type="content" source="../assets/images/toolkit-v2/toolkit-sign-in-m365.png" alt-text="Screenshot shows where to sign in to Microsoft 365 and Azure."::: + :::image type="content" source="../assets/images/toolkit-v2/toolkit-sign-in-m365.png" alt-text="Screenshot shows where to sign in to Microsoft 365 and Azure."::: -1. Close the browser after signing in using your credentials. +4. Close the browser after signing in using your credentials. -1. Return to Agents Toolkit within Visual Studio Code. +5. Return to Agents Toolkit within Visual Studio Code. The **ACCOUNTS** section of the sidebar shows your Microsoft 365 account name. If custom app upload is enabled for your Microsoft 365 account, Agents Toolkit displays **Custom App Upload Enabled**. -:::image type="content" source="../assets/images/toolkit-v2/first-tab/m365-uploading-enabled-msg.png" alt-text="Screenshot shows the user signed in to Microsoft 365 and the uploading enabled message."::: + :::image type="content" source="../assets/images/toolkit-v2/first-tab/m365-uploading-enabled-msg.png" alt-text="Screenshot shows the user signed in to Microsoft 365 and the uploading enabled message."::: Now you're ready to build the app and run it locally! @@ -230,11 +230,11 @@ Your default web browser opens to let you sign in. Sign in to your Azure account ## Build and run your app in the local environment - Now you can build and debug your first Teams message extension app locally. +Now you can build and debug your first Teams message extension app locally. ### Build and run your app locally - 1. Select the **F5** key in Visual Studio Code to run your application in debug mode. +1. Select the **F5** key in Visual Studio Code to run your application in debug mode. > [!NOTE] > If Agents Toolkit is unable to verify a particular prerequisite, it prompts you to check. @@ -270,7 +270,7 @@ When you debug the app for the first time, Teams downloads the dependencies and 1. A dialog box opens to let you add the message extension app to Teams. Select **Add**. -:::image type="content" source="../assets/images/toolkit-v2/first-msgext/add-mex-app-local-debug-latest.png" alt-text="Screenshot shows the option to add the custom app in Teams." lightbox="../assets/images/toolkit-v2/first-msgext/add-mex-app-local-debug.png"::: + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/add-mex-app-local-debug-latest.png" alt-text="Screenshot shows the option to add the custom app in Teams." lightbox="../assets/images/toolkit-v2/first-msgext/add-mex-app-local-debug.png"::: Teams loads the message extension app. @@ -294,15 +294,15 @@ The first time your app loads, the message extension app is open for you to test 1. Enter the name of an open-source npm package in the search box of the message extension, such as **cli**. The message extension displays a list of the matching items. -:::image type="content" source="..assets/images/toolkit-v2/first-msgext/mex-search-string.png" alt-text="Screenshot shows a search string in the message extension app."::: + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/mex-search-string.png" alt-text="Screenshot shows a search string in the message extension app."::: -1. Select one of the items from the list. The app creates an Adaptive Card with the item in the message compose area so you can send it in a chat or channel. +2. Select one of the items from the list. The app creates an Adaptive Card with the item in the message compose area so you can send it in a chat or channel. -:::image type="content" source="../assets/images/toolkit-v2/first-msgext/mex-search-result.png" alt-text="Screenshot shows the search result in the message compose area."::: + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/mex-search-result.png" alt-text="Screenshot shows the search result in the message compose area."::: -1. Select **Enter**. The message extension app sends the Adaptive Card with the item in the chat or channel. +3. Select **Enter**. The message extension app sends the Adaptive Card with the item in the chat or channel. -:::image type="content" source="../assets/images/toolkit-v2/first-msgext/mex-search-sent.png" alt-text="Screenshot shows the search result sent in chat."::: + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/mex-search-sent.png" alt-text="Screenshot shows the search result sent in chat."::: > [!div class="nextstepaction"] > [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+How+to+run+a+search+query+using+Message+Extension&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fsbs-gs-msgext%3Ftabs%3Dvscode%252Cvsc1%252Cvsc2%252Cmsgext%252Cvsc3%252Cvsc4%26tutorial-step%3D3&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fsbs-gs-msgext.yml&documentVersionIndependentId=d0c82a43-2f4a-ad2e-251e-922e2e357806&platformId=e2feec5c-06f2-6065-f4a5-2e2947f00b97&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) @@ -311,26 +311,155 @@ The first time your app loads, the message extension app is open for you to test 1. Enter **/** followed by your message extension app's name in the command box. -:::image type="content" source="../assets/images/toolkit-v2/first-msgext/mention-mex-app.png" alt-text="Screenshot shows how to invoke the message extension app."::: + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/mention-mex-app.png" alt-text="Screenshot shows how to invoke the message extension app."::: The message extension app opens in the command box. -1. Enter a name of an open-source npm package and select one of the search results. +2. Enter a name of an open-source npm package and select one of the search results. -:::image type="content" source=".. /assets/images/toolkit-v2/first-msgext/command-box-search.png" alt-text="Screenshot shows a search string in the command box."::: + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/command-box-search.png" alt-text="Screenshot shows a search string in the command box."::: - The message extension displays the search result as an Adaptive Card in the command box. +The message extension displays the search result as an Adaptive Card in the command box. :::image type="content" source="../assets/images/toolkit-v2/first-msgext/command-search-card.png" alt-text="Screenshot shows the search result as a card in the command box."::: -1. Copy the Adaptive Card to paste it in the message compose area. +3. Copy the Adaptive Card to paste it in the message compose area. -:::image type="content" source="../assets/images/toolkit-v2/first-msgext/command-search-card-send.png" alt-text="Screenshot shows search result in a card in the message compose area."::: + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/command-search-card-send.png" alt-text="Screenshot shows search result in a card in the message compose area."::: -1. Select **Enter**. The message extension app sends the Adaptive Card with the search result in the most recent chat. +4. Select **Enter**. The message extension app sends the Adaptive Card with the search result in the most recent chat. -:::image type="content" source="../assets/images/toolkit-v2/first-msgext/command-search-card-sent.png" alt-text="Screenshot shows the search result sent in a chat."::: + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/command-search-card-sent.png" alt-text="Screenshot shows the search result sent in a chat."::: > [!div class="nextstepaction"] > [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+How+to+run+a+search+query+using+Command+Box&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fsbs-gs-msgext%3Ftabs%3Dvscode%252Cvsc1%252Cvsc2%252Ccmdbox%252Cvsc3%252Cvsc4%26tutorial-step%3D3&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fsbs-gs-msgext.yml&documentVersionIndependentId=d0c82a43-2f4a-ad2e-251e-922e2e357806&platformId=e2feec5c-06f2-6065-f4a5-2e2947f00b97&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) --- + +### How to open your message extension app + +You tested the search feature of the message extension app in the previous step. Now, learn the different ways to open the message extension app. +
+
+
+ Open your app from command box + +1. Enter **/** followed by your message extension app's name in the command box. + + :::image type="content" source="../msteams-platform/assets/images/toolkit-v2/first-msgext/mention-mex-app.png" alt-text="Screenshot shows how to invoke the message extension app."::: + +The app opens in the command box and you can use it to run a query. + +> [!NOTE] +> +> - Using **/** to open your message extension app from the command box only works in the new Teams client. +> - Use **@** to open your message extension app from the command box in the classic Teams client. + +
+ +
+
+ Open your app from message compose area + +2. Select the three dots at the bottom of the message compose area. + +3. Select your message extension app. + + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/three-dot-mex.png" alt-text="Screenshot shows how to open the message extension app from message compose area."::: + +The message extension app loads with the options to run a search. + +
+ +
+
+Open your app from uploaded custom apps + +1. Select **Apps** > **Manage your apps**. + +1. Select the dropdown for your app from the list of apps and select **Personal app**. + + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/uploaded-apps.png" alt-text="Screenshot shows the uploaded apps in Teams."::: + +3. A dialog box appears suggesting you to try out your app. If you select **Got it**, the dialog box disappears. Select **Try it**. + + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/mex-try-it.png" alt-text="Screenshot shows the message to try the message extension app now or later."::: + +4. A list of your message extension apps appears in your most recent Teams chat. Select your message extension app from the list. + +
+ +### 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 custom app upload. You can learn more about custom app upload in the Prerequisites section. + +## Deploy your first Teams app + +Let's deploy your first message extension app on Azure using Agents Toolkit. + +### Sign in to your Azure account + +Sign in to your Azure account to access the Microsoft Azure portal and provision new cloud resources to support your app. + +# [Visual Studio Code](#tab/vsc3) + +1. Open Visual Studio Code. + +1. Open the project folder in which you created the message extension app. + +1. Select the Microsoft 365 Agents Toolkit :::image type="icon" source="../assets/images/toolkit-v2/toolkit-sidebar-icon.png"::: icon in the activity bar. + +1. Select **Sign in to Azure** using your credentials. Your default web browser opens to let you sign in. + +> [!TIP] +> If you have the AZURE ACCOUNT extension installed and are using the same account, you can skip this step. + +5. Close the browser when prompted and return to Visual Studio Code. + +The **ACCOUNTS** section of the sidebar lists the number of usable Azure subscriptions available to you. Ensure that you have at least one usable Azure subscription available. If not, sign out and use a different account. + +> [!div class="nextstepaction"] +> [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Sign+in+to+your+Azure+account+using+Visual+Studio+Code&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fsbs-gs-msgext%3Ftabs%3Dvscode%252Cvsc1%252Cvsc2%252Cmsgext%252Cvsc3%252Cvsc4%26tutorial-step%3D4&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fsbs-gs-msgext.yml&documentVersionIndependentId=d0c82a43-2f4a-ad2e-251e-922e2e357806&platformId=e2feec5c-06f2-6065-f4a5-2e2947f00b97&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) + +# [Command Line](#tab/cli3) + +1. Go to the project folder of your message extension app and open Command Prompt. + +1. Sign in to Azure with Agents Toolkit CLI command: + +``` bash +atk account login azure +``` + +3. Your default web browser opens to let you sign in. Sign in to your Azure account using your credentials. Close the browser when you're prompted. + +Now, let's learn how to deploy the app to Azure using Agents Toolkit. + +> [!div class="nextstepaction"] +> [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Sign+in+to+your+Azure+account+using+Command+Line&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fsbs-gs-msgext%3Ftabs%3Dvscode%252Cvsc1%252Ccli2%252Cmsgext%252Cvsc3%252Cvsc4%26tutorial-step%3D4&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fsbs-gs-msgext.yml&documentVersionIndependentId=d0c82a43-2f4a-ad2e-251e-922e2e357806&platformId=e2feec5c-06f2-6065-f4a5-2e2947f00b97&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) + +--- + +[!INCLUDE [Provision and Deploy your app on Azure](../includes/get-started/azure-provisioning-instructions.md)] + +> [!div class="nextstepaction"] +> [I ran into an issue](https://github.com/MicrosoftDocs/msteams-docs/issues/new?template=Doc-Feedback.yaml&title=%5BI+ran+into+an+issue%5D+Deploy+your+app+to+Azure&&author=%40surbhigupta&pageUrl=https%3A%2F%2Flearn.microsoft.com%2Fen-us%2Fmicrosoftteams%2Fplatform%2Fsbs-gs-msgext%3Ftabs%3Dvscode%252Cvsc1%252Ccli2%252Cmsgext%252Cvsc3%252Cvsc4%26tutorial-step%3D4&contentSourceUrl=https%3A%2F%2Fgithub.com%2FMicrosoftDocs%2Fmsteams-docs%2Fblob%2Fmain%2Fmsteams-platform%2Fsbs-gs-msgext.yml&documentVersionIndependentId=d0c82a43-2f4a-ad2e-251e-922e2e357806&platformId=e2feec5c-06f2-6065-f4a5-2e2947f00b97&metadata=*%2BID%253A%2Be473e1f3-69f5-bcfa-bcab-54b098b59c80%2B%250A*%2BService%253A%2B%2A%2Amsteams%2A%2A) + +### Learn what happens when you deployed your app to Azure + +Before deployment, the app runs 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 of the app to Azure. + +- The backend, if configured, uses various Azure services including Azure App Service and Azure Storage. +- The frontend app is deployed to an Azure Storage account configured for static web hosting. + +### Congratulations + +You completed the tutorial to build a message extension app with JavaScript! + +Did you come up with something like this? + + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/app-added-mex-local-debug.png" alt-text="Screenshot shows the final output of the message extension app in Teams." lightbox="../assets/images/toolkit-v2/first-msgext/app-added-mex-local-debug.png"::: From 757c9ca834b9af5a08726c3c58f622a62ed7fd9e Mon Sep 17 00:00:00 2001 From: v-shgarcha Date: Mon, 10 Nov 2025 14:04:23 +0530 Subject: [PATCH 06/10] Update build-message-extension.md --- msteams-platform/get-started/build-message-extension.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/msteams-platform/get-started/build-message-extension.md b/msteams-platform/get-started/build-message-extension.md index fad4afec36f..3155665c769 100644 --- a/msteams-platform/get-started/build-message-extension.md +++ b/msteams-platform/get-started/build-message-extension.md @@ -345,7 +345,7 @@ You tested the search feature of the message extension app in the previous step. 1. Enter **/** followed by your message extension app's name in the command box. - :::image type="content" source="../msteams-platform/assets/images/toolkit-v2/first-msgext/mention-mex-app.png" alt-text="Screenshot shows how to invoke the message extension app."::: + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/mention-mex-app.png" alt-text="Screenshot shows how to invoke the message extension app in the command box."::: The app opens in the command box and you can use it to run a query. From 2eaeda7df3669e3b3dde187e11478809a7b3ba2d Mon Sep 17 00:00:00 2001 From: v-shgarcha Date: Mon, 10 Nov 2025 14:16:43 +0530 Subject: [PATCH 07/10] Update build-message-extension.md --- .../get-started/build-message-extension.md | 21 +++++++------------ 1 file changed, 8 insertions(+), 13 deletions(-) diff --git a/msteams-platform/get-started/build-message-extension.md b/msteams-platform/get-started/build-message-extension.md index 3155665c769..dae72f4a9c9 100644 --- a/msteams-platform/get-started/build-message-extension.md +++ b/msteams-platform/get-started/build-message-extension.md @@ -16,9 +16,9 @@ Start Microsoft Teams app development with your first Teams app using JavaScript In this tutorial, you'll learn: -- How to set up a new project with Microsoft 365 Agents Toolkit (previously known as Teams Toolkit). -- How to build a message extension app. -- How to deploy your app. +- [How to set up a new project with Microsoft 365 Agents Toolkit (previously known as Teams Toolkit)](#create-your-message-extension-project-workspace) +- [How to build a message extension app](#build-and-run-your-first-message-extension-app) +- [How to deploy your app](#deploy-your-first-teams-app) You'll see the following output after you complete this guide: @@ -65,11 +65,6 @@ There are two types of Teams message extensions: Let's create a message extension app with a search command. First, 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 Agents Toolkit.](#create-your-message-extension-project-workspace) -1. [About the directory structure of your app project.](#take-a-tour-of-the-message-extension-app-source-code) - ## Create your message extension project workspace If the prerequisites are in place, let's begin! @@ -272,9 +267,9 @@ When you debug the app for the first time, Teams downloads the dependencies and :::image type="content" source="../assets/images/toolkit-v2/first-msgext/add-mex-app-local-debug-latest.png" alt-text="Screenshot shows the option to add the custom app in Teams." lightbox="../assets/images/toolkit-v2/first-msgext/add-mex-app-local-debug.png"::: -Teams loads the message extension app. + Teams loads the message extension app. -:::image type="content" source="../assets/images/toolkit-v2/first-msgext/app-added-mex-local-debug-2.png" alt-text="Screenshot shows the message extension app open in a Teams bot chat." lightbox="../assets/images/toolkit-v2/first-msgext/app-added-mex-local-debug-2.png"::: + :::image type="content" source="../assets/images/toolkit-v2/first-msgext/app-added-mex-local-debug-2.png" alt-text="Screenshot shows the message extension app open in a Teams bot chat." lightbox="../assets/images/toolkit-v2/first-msgext/app-added-mex-local-debug-2.png"::: 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. @@ -313,7 +308,7 @@ The first time your app loads, the message extension app is open for you to test :::image type="content" source="../assets/images/toolkit-v2/first-msgext/mention-mex-app.png" alt-text="Screenshot shows how to invoke the message extension app."::: -The message extension app opens in the command box. + The message extension app opens in the command box. 2. Enter a name of an open-source npm package and select one of the search results. @@ -360,9 +355,9 @@ The app opens in the command box and you can use it to run a query.
Open your app from message compose area -2. Select the three dots at the bottom of the message compose area. +1. Select the three dots at the bottom of the message compose area. -3. Select your message extension app. +2. Select your message extension app. :::image type="content" source="../assets/images/toolkit-v2/first-msgext/three-dot-mex.png" alt-text="Screenshot shows how to open the message extension app from message compose area."::: From 5fc14e3c9f7774a522f8bea0aa1ac0fb91b6d7c1 Mon Sep 17 00:00:00 2001 From: v-shgarcha Date: Wed, 19 Nov 2025 12:21:11 +0530 Subject: [PATCH 08/10] Update prepare-toolkit.md --- msteams-platform/includes/get-started/prepare-toolkit.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/msteams-platform/includes/get-started/prepare-toolkit.md b/msteams-platform/includes/get-started/prepare-toolkit.md index ae31ee532b0..880d4975425 100644 --- a/msteams-platform/includes/get-started/prepare-toolkit.md +++ b/msteams-platform/includes/get-started/prepare-toolkit.md @@ -38,7 +38,7 @@ This condition is more common on Linux and macOS systems. Ensure you add the npm global cache to your PATH. This step is normally done as part of the Node.js installer. -You can use the CLI with the `atk' command. Verify that the command is working by running `atk -h`. +You can use the CLI with the `atk` command. Verify that the command is working by running `atk -h`. > [!CAUTION] > Before you can run TeamsFx in PowerShell terminals, you must enable the **remote signed** execution policy for PowerShell. From c0882bc7b43f7b675aed7304ac05584fcd7e95bc Mon Sep 17 00:00:00 2001 From: v-shgarcha Date: Thu, 20 Nov 2025 12:52:18 +0530 Subject: [PATCH 09/10] Update build-message-extension.md --- msteams-platform/get-started/build-message-extension.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/msteams-platform/get-started/build-message-extension.md b/msteams-platform/get-started/build-message-extension.md index dae72f4a9c9..8793e505e9a 100644 --- a/msteams-platform/get-started/build-message-extension.md +++ b/msteams-platform/get-started/build-message-extension.md @@ -165,12 +165,12 @@ A message extension uses Bot Framework to interact with your service through a c | Folder / File | Contents | | --- | --- | - | `m365agents.yml` | Main project file describes your application configuration and defines the set of actions to run in each lifecycle stage. | - | `m365agents.local.yml` | Overrides `m365agents.yml` with actions that enable local execution and debugging. | | `.vscode/` | Visual Studio Code files for local debug. | | `appPackage/` | Templates for the Teams application manifest. | | `infra/` | Templates for provisioning Azure resources. | - | `index.js` | Application entry point and `express` handler. | + | `env` | Name / value pairs are stored in environment files and used by m365agents.yml to customize the provisioning and deployment rules. | + | `m365agents.yml` | Main project file describes your application configuration and defines the set of actions to run in each lifecycle stage. | + | `m365agents.local.yml` | Overrides `m365agents.yml` with actions that enable local execution and debugging. | > [!Tip] > Familiarize yourself with bots and message extension outside of Teams before you integrate your app within Teams. From d0634dbe845de44688971a2c82cd18e76bf88a0d Mon Sep 17 00:00:00 2001 From: v-shgarcha Date: Thu, 20 Nov 2025 15:15:32 +0530 Subject: [PATCH 10/10] Update prepare-toolkit.md --- msteams-platform/includes/get-started/prepare-toolkit.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/msteams-platform/includes/get-started/prepare-toolkit.md b/msteams-platform/includes/get-started/prepare-toolkit.md index 880d4975425..24167d2ace9 100644 --- a/msteams-platform/includes/get-started/prepare-toolkit.md +++ b/msteams-platform/includes/get-started/prepare-toolkit.md @@ -38,7 +38,7 @@ This condition is more common on Linux and macOS systems. Ensure you add the npm global cache to your PATH. This step is normally done as part of the Node.js installer. -You can use the CLI with the `atk` command. Verify that the command is working by running `atk -h`. +You can use the CLI with the `atk' command. Verify that the command is working by running`atk -h`. > [!CAUTION] > Before you can run TeamsFx in PowerShell terminals, you must enable the **remote signed** execution policy for PowerShell.