title	Teams Developer Documentation Tutorials
description	Learn about the tutorials available for Teams developer documentation.
ms.localizationpriority	high
ms.topic	reference
ms.date	12/02/2025

Tutorials

In this article, learn more about building Teams app capabilities. Here's a list of the step-by-step guides available for Teams platform capabilities.

#	Capability	Step-by-step guide
1.	Bot	- Debug your AI chat bot using Microsoft 365 Agents Playground - Send proactive messages
2.	Message extension	- Build API-based message extension - Build action-based message extension - Build your first message extension app using JavaScript
3.	Tab	Build your first tab app using C sharp
4.	SSO	- Build a bot with SSO authentication - Add SSO to tab and message extension app

Build your first bot app

Start Microsoft Teams app development with your first Teams app. You can create a bot app with Teams using Javascript.

Build your first bot

Your app has a capability, which comes with its own UI and UX:

:::image type="content" source="../assets/images/toolkit-v2/prerequisites/your-helloworld-app.png" alt-text="Diagram shows that this app has three features.":::

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 bot app.
How to deploy your app.

Prerequisites

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

	Install	For using...
Required
	Microsoft 365 Agents Toolkit	A Microsoft Visual Studio Code extension that creates a project scaffolding for your app. Use the latest version.
	Microsoft Teams	Microsoft Teams to collaborate with everyone you work with through apps for chat, meetings, and call all in one place.
	Node.js	Back-end JavaScript runtime environment. For more information, see Node.js version compatibility table for project type.
	Microsoft Edge (recommended) or Google Chrome	A browser with developer tools.
	Visual Studio Code	JavaScript, TypeScript, or SharePoint Framework (SPFx) build environments. Use the latest version.
Optional
	Azure Tools for Visual Studio Code and Azure CLI	Azure tools to access stored data or to deploy a cloud-based backend for your Teams app in Azure.
	React Developer Tools for Chrome OR React Developer Tools for Microsoft Edge	A browser DevTools extension for the open-source React JavaScript library.
	Microsoft Graph Explorer	Microsoft Graph Explorer, a browser-based tool that lets you run a query from Microsoft Graph data.
	Developer Portal for Teams	Web-based portal to configure, manage, and publish your Teams app including to your organization or the Microsoft Teams Store.

[!TIP] If you work with Microsoft Graph data, you should learn about and bookmark the Microsoft Graph Explorer. This browser-based tool allows you to query Microsoft Graph outside of an app.

Set up prerequisites

After you install the required tools, set up the development environment.

Install Microsoft 365 Agents Toolkit

Microsoft 365 Agents Toolkit (previously known as 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 Agents Toolkit with Visual Studio Code or a command-line interface called Microsoft 365 Agents Toolkit CLI (previously known as TeamsFx CLI).

Visual Studio Code

Open Visual Studio Code and select Extensions (Ctrl+Shift+X or View > Extensions).
In the search box, enter Microsoft 365 Agents Toolkit.
Select Install.

:::image type="content" source="../assets/images/include-files/install-toolkit-vs.png" alt-text="Screenshot shows the Agents Toolkit extension installation.":::

The Microsoft 365 Agents Toolkit :::image type="icon" source="../assets/images/include-files/toolkit-sidebar-icon.PNG"::: icon appears in the Visual Studio Code Activity Bar.

You can also install Agents Toolkit from the Visual Studio Code Marketplace.

Command Line

To install Agents Toolkit CLI, use the npm package manager and enter the following command in Command prompt:

npm install -g @microsoft/m365agentstoolkit-cli

Depending on your configuration, you might need to use sudo to install the CLI:

sudo npm install -g --unsafe-perm @microsoft/m365agentstoolkit-cli

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

[!CAUTION] Before you can run TeamsFx in PowerShell terminals, you must enable the remote signed execution policy for PowerShell.

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 your custom app, you must upload your app to Teams with the Upload a custom app option. Sign in to your Microsoft 365 account to check if this option is enabled.

The following steps help you verify if you can upload apps in Teams:

In the Teams client, select the Apps icon.
Select Manage your apps.
Select Upload an app.
Look for the option to Upload a custom app. If the option is visible, you can upload custom apps.

:::image type="content" source="../assets/images/toolkit-v2/prerequisites/upload-custom-app.png" alt-text="Screenshot shows the option to upload a custom app in Teams." :::

[!NOTE] If you don't find the option to upload a custom app, contact your Teams administrator.

Create a free Teams developer tenant

If you don't have a Teams developer account, join the Microsoft 365 developer program. This is an optional step.

Go to the Microsoft 365 developer program.
Select Join Now and follow the onscreen instructions.
In the welcome screen, select Set up E5 subscription.
Set up your administrator account. After you finish, the following screen appears:

:::image type="content" source="../assets/images/include-files/microsoft-365.png" alt-text="The screenshot shows the Microsoft 365 Developer Program.":::
Sign in to Teams using the administrator account you just set up. Verify that you have the Upload a custom app option in Teams.

Get a free Azure account

If you 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 bot app

Let's create your first bot app.

The bot capability of a Teams app creates a chatbot or a conversational bot. You use it to run simple and automated tasks, like providing customer service. A bot talks with a web service and helps you use its offerings. You can get weather forecast, make reservations, or any other service offered using a conversational bot.

:::image type="content" source="../assets/images/toolkit-v2/first-bot/your-helloworld-app-bot.png" alt-text="Diagram showing this app has three features. Bot is highlighted.":::

As you've already prepared for creating these apps, you can set up a new Teams project for creating the bot app.

In this tutorial, you learn:

How to set up a new bot project with Agents Toolkit.
About the directory structure of your app project.

[!IMPORTANT] Bots are available in Government Community Cloud (GCC), GCC High, Department of Defense (DoD), and Teams operated by 21Vianet environments.

Create your bot project workspace

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

[!NOTE] The Visual Studio Code UI shown is from Mac. It may differ depending on your operating system, Agents Toolkit version, and environment.

Visual Studio Code

Open Visual Studio Code.
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.
Select Create a New Agent/App > Teams App.

:::image type="content" source="../assets/images/toolkit-v2/first-bot/create-project.png" alt-text="This screenshot shows the location of the Create New Project link in the Agents Toolkit sidebar.":::
Select Bot to create a new bot project.

:::image type="content" source="../assets/images/toolkit-v2/first-bot/create-new-app1.png" alt-text="Screenshot shows the wizard to Create New Project.":::
Ensure that Basic Bot is selected as the app feature that you want to build in your app.

:::image type="content" source="../assets/images/toolkit-v2/first-bot/select-bot.png" alt-text="The screenshot shows the app feature to add to your new app.":::
Select JavaScript as the programming language.

:::image type="content" source="../assets/images/toolkit-v2/first-bot/select-language-tab.png" alt-text="The screenshot shows the option to select the programming language.":::
Select Default folder to store your project root folder in default location.

:::image type="content" source="../assets/images/toolkit-v2/first-bot/select-default-location.png" alt-text="The 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-bot/select-browse.png" alt-text="Screenshot shows the selection of browse location option.":::
2. Select the location for project workspace.
3. Select the Select Folder.
  
  :::image type="content" source="../assets/images/toolkit-v2/select-folder.png" alt-text="Screenshot shows the folder to select.":::
Enter a suitable name for your app and then select Enter.

:::image type="content" source="../assets/images/toolkit-v2/first-bot/hello-bot.png" alt-text="Screenshot shows where to enter the app name.":::

A dialog appears, where you would be required to choose yes or no to trust the authors of the files in this folder.

:::image type="content" source="../toolkit/toolkit-v4/sbs-v4/images-sbs/teams-toolkit-v4/first-bot/vsc-trust-authors.png" alt-text="Screenshot shows the dialog to trust or not the authors of the files in this folder.":::

Your Teams app with a bot capability is created in few seconds.

:::image type="content" source="../assets/images/toolkit-v2/first-bot/app-created-bot.png" alt-text="Screenshot shows the app created.":::

After your app is created, Agents Toolkit displays the following message:

:::image type="content" source="../assets/images/toolkit-v2/preview-project.png" alt-text="Screenshot shows the message that the feature is successfully created.":::

Select Local debug to preview your project.

A quick recap of creating a Teams app.

Watch this short recap for creating a Teams app.

Command line

Use the `atk' CLI to create your first project. Start from the folder where you want to create the project folder.

atk new

You can use the CLI to create a new Teams app. The CLI leads you through a series of questions. Every question includes an instruction on answering it.

For example, use arrow keys to select an option. After you make the choice, select Enter to confirm it.

Select Create a new Teams app.
Select Bot and deselect Tab.
Select JavaScript as the programming language.
Select Enter to select the default workspace folder.
Enter a suitable name for your app, like HelloBot. The name of the app must consist only of alphanumeric characters.

After you've answered all questions, your project is created.

Take a tour of the bot app source code

After scaffolding is completed, view the project directories and files in the Explorer in the Visual Studio Code.

:::image type="content" source="../assets/images/toolkit-v2/first-bot/folder-structure-bot-app.png" alt-text="Screenshot shows the folder structure.":::

Folder / File	Contents
`m365agents.yml`	Main project file
`m365agents.local.yml`	This overrides `m365agents.yml` with actions that enable local execution and debugging.
`.vscode/`	VSCode files for local debug.
`appPackage/`	Templates for the Teams application manifest.
`adaptiveCards/`	Adaptive Cards sent back by the bot.
`infra/`	Templates for provisioning Azure resources.
`index.js`	Application entry point and `express` handler.
`teamsBot.js`	Teams activity handler.

[!Tip] Familiarize yourself with bots outside of Teams before you integrate your first bot within Teams.

Build and run your first bot app

After you set up your project workspace with Agents Toolkit, build your bot 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.

Visual Studio Code

Open Visual Studio Code.
Select the Microsoft 365 Agents Toolkit :::image type="icon" source="../assets/images/toolkit-v2/toolkit-sidebar-icon.png"::: icon in the sidebar.
Select Sign in to M365 using your credentials.

Your default web browser opens to let you sign in to the account.
Close the browser when prompted and return to Visual Studio Code.
Return to Agents Toolkit within Visual Studio Code.

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.

:::image type="content" source="../assets/images/toolkit-v2/first-tab/m365-uploading-enabled.png" alt-text="Screenshot shows where to sign in to Microsoft 365 and Azure.":::

Now you're ready to build the app and run it locally!

Command line

atk account login m365

Your default web browser opens to let you sign in to the account. Sign in to your Azure account using your credentials. Close the browser when you're prompted.

The account logins are shared between Visual Studio Code and Agents Toolkit CLI.

Now that the development environment is configured, you can create, build, and deploy your first Teams app.

Build and run your first bot app locally

To build and run your app in the local environment:

Select F5 in Visual Studio Code to run your app in debug mode.

[!NOTE] If Agents 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.

In case you're wondering, when you press the F5 key, Agents 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.
1. Install npm packages.
2. Starts Dev Tunnel to create a HTTP tunnel.
3. Registers the app in Microsoft Entra ID and configures the app.
4. Registers the bot app in Bot Framework and configures the bot app.
5. Registers the app in Teams Developer Portal and configures the app.
6. Starts the bot app.
7. Starts Teams in a web browser and uploads the custom bot app.
:::image type="content" source="../assets/images/toolkit-v2/first-bot/f5-build-and-run.png" alt-text="Screenshot showing when F5 key is pressed for debugging.":::

[!NOTE] 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 process can take three to five minutes to complete.

Teams runs your app in a web browser.
Sign in with your Microsoft 365 account, if prompted.
Select Add to upload the custom bot app to Teams.

:::image type="content" source="../assets/images/toolkit-v2/first-bot/add-bot-app-local-debug.png" alt-text="Screenshot of the app details dialog to add the bot app to Teams.":::
Select Open to open the app in personal scope.

Alternatively, you can either search and select the required scope or select a channel, chat, or meeting from the list, and move through the dialog to select Go.

:::image type="content" source="../assets/images/toolkit-v2/first-bot/add-bot-scope.png" alt-text="Screenshot of the scope selection dialog with a list of shared scopes.":::

Now the bot is successfully running on Teams! After the app is loaded, a chat session with the bot opens.

:::image type="content" source="../assets/images/toolkit-v2/first-bot/app-added-bot-local-debug.png" alt-text="Screenshot shows the bot is running on Teams client.":::

You can type welcome to show an introduction card, and type learn to go to Adaptive Card and bot command documentation.

:::image type="content" source="../assets/images/toolkit-v2/first-bot/bot-app-learn-local-debug.png" alt-text="Screenshot shows the learn card in the bot on Teams client.":::

You can do normal debugging activities, such as setting breakpoints, as with any other web application. Open the bot/teamsBot.js file and locate the onMessage() method. Set a breakpoint on any case. Then, type some text.

Learn how to troubleshoot if your app doesn't run locally.

To successfully run your app in Teams, ensure that you've enabled custom app upload in your Teams account. You can learn more about custom app upload in the prerequisites section.

[!IMPORTANT] Custom app upload is available in Government Community Cloud (GCC) and isn't supported in GCC High, DoD, and Teams operated by 21Vianet.

[!TIP] Check for issues before you upload a custom app, using the app validation tool. This tool is included in the toolkit. Fix the errors to upload the app.

Deploy your first Teams app

You've learned to create, build, and run Teams app with Bot capability. The final step is to deploy your app on Azure.

Let's deploy the first app with Bot capability on Azure using Agents 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.

Visual Studio Code

Open Visual Studio Code.
Open the project folder in which you created the bot app.
Select the Microsoft 365 Agents Toolkit :::image type="icon" source="../assets/images/toolkit-v2/toolkit-sidebar-icon.png"::: icon in the sidebar.
Select Sign in to Azure using your credentials.

[!TIP] If you have the AZURE ACCOUNT extension installed and are using the same account, you can skip this step. Use the same account as you are using in other extensions.

Your default web browser opens to let you sign in to the account.
Close the browser when prompted and return to Visual Studio Code.

The ACCOUNTS section of the sidebar shows the two accounts separately. It also lists the number of usable Azure subscriptions available to you. Ensure you have at least one usable Azure subscription available. If not, sign out and use a different account.

Congratulations, you have created a Teams app! Now let's go ahead and learn how to deploy one of the apps to Azure using Agents Toolkit.

Command line

atk account login m365

Your default web browser opens to let you sign in to the account. Sign in to your Azure account using your credentials. Close the browser when you're prompted.

atk account login azure

Your default web browser opens to let you sign in to the account. Sign in to your Azure account using your credentials. Close the browser when you're prompted.

The account logins are shared between Visual Studio Code and Agents Toolkit CLI.

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

Provision and Deploy your app on Azure

Deployment consists of two steps. First, Azure creates necessary cloud resources (also known as provisioning). Then, Azure copies your app's code into the created cloud resources. For this tutorial, you'll deploy the bot app.

What's the difference between Provision and Deploy?

The Provision step creates resources in Azure and Microsoft 365 for your app, but doesn't copy code (HTML, CSS, or JavaScript) to the resources. The Deploy step copies the code for your app to the resources you created during the provision step. It's common to deploy multiple times without provisioning new resources. Since the provision step can take some time to complete, it's separate from the deployment step.

Visual Studio Code

Select the Microsoft 365 Agents Toolkit :::image type="icon" source="../assets/images/toolkit-v2/toolkit-sidebar-icon.png"::: icon in the Visual Studio Code sidebar.

Select Provision.

:::image type="content" source="../assets/images/toolkit-v2/provisioning-commands.png" alt-text="Screenshot shows the selection of provision in the cloud under Agents toolkit.":::
Select a subscription to use for the Azure resources.

:::image type="content" source="../assets/images/toolkit-v2/deploy-azure/select-resource.png" alt-text="Screenshot shows the subscription to use for the Azure resources.":::

Your app is hosted using Azure resources.

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

:::image type="content" source="../assets/images/toolkit-v2/deploy-azure/provision-warning.png" alt-text="Screenshot shows a dialog box that costs may be incurred when running resources in Azure.":::

The provisioning process creates resources in the Azure cloud. It may take some time. You can monitor the progress by watching the dialogs in the bottom-right corner. After a few minutes, you see the following notice:

:::image type="content" source="../assets/images/toolkit-v2/deploy-azure/deploy-provision-successmsgext.png" alt-text="Screenshot shows a notice, which displays hellomsg successfully provisioned in the cloud.":::

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.

:::image type="content" source="../assets/images/toolkit-v2/deploy-azure/provisioned-resources-env.png" alt-text="Screenshot shows the resource being provisioned in the environment section.":::
Select Deploy from the LIFECYCLE panel after provisioning is complete.

:::image type="content" source="../assets/images/toolkit-v2/deploy-azure/deploy-cloud.png" alt-text="Screenshot shows deploy to cloud highlighted in red.":::

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.

Command Line

In your terminal window:

Run atk provision.
```
atk provision
```
When prompted, select an Azure subscription to use Azure resources.

Your app is hosted using Azure resources.
Run atk deploy.
```
atk deploy
```

Run the deployed app

Once the provisioning and deployment steps are complete:

Open the debug panel (Ctrl+Shift+D / ⌘⇧-D or View > Run) from Visual Studio Code.
Select Launch Remote (Edge) from the launch configuration dropdown.
Select the Start debugging (F5). You're prompted to upload the custom bot app to Teams.

:::image type="content" source="../assets/images/toolkit-v2/deploy-azure/launch-remote.png" alt-text="Screenshot shows the debug and launch app remotely.":::
Select Add.

:::image type="content" source="../assets/images/toolkit-v2/deploy-azure/add-mex-app.png" alt-text="Screenshot of the app details dialog to add the app to Teams.":::
Select Open to open the app in personal scope.

Alternatively, you can either search and select the required scope or select a channel, chat, or meeting from the list, and move through the dialog to select Go.

:::image type="content" source="../assets/images/toolkit-v2/deploy-azure/add-scope.png" alt-text="The screenshot of the scope selection dialog with the list of shared scopes.":::

You successfully added your bot app to the Teams client.

:::image type="content" source="../assets/images/toolkit-v2/first-bot/bot-app-learn-local-debug.png" alt-text="Screenshot shows the learn card in the bot on Teams client.":::

Learn what happens when you deployed your app to Azure

Before deployment, the application has been running locally:

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

Deployment is a two-step process. You provision the resources on an active Azure subscription, and then deploy or upload the backend and frontend code for the application to Azure.

The backend, if configured, uses various Azure services, including Azure App Service and Azure Storage.
The frontend application is deployed to an Azure Storage account configured for static web hosting.

Congratulations!

You've done it!

You've created a bot app.

Now that you've learned to create a basic app, you can move on to creating more complex apps. You've completed the tutorial to build bot with JavaScript.

Tutorials

Debug your AI chat bot using Microsoft 365 Agents Playground

Start Microsoft Teams app development with your Teams AI chat bot app and debug with Microsoft 365 Agents Playground (previously known as Teams App Test Tool). Agents Playground makes debugging bot-based apps effortless. You don't need a Microsoft 365 developer account, tunneling, or Teams app and bot registration to use Agents Playground.

Tutorial: Debug your AI chat bot

Prerequisites

You can chat with your bot and view the messages and Adaptive Cards as they appear in Teams. You can also mock an activity in Agents Playground using activity triggers.

[!NOTE]

Agents Playground is available only in v5.4.0 of Microsoft 365 Agents Toolkit (previously known as Teams Toolkit).

Agents Playground is supported only for desktop and web clients.

This step-by-step guide helps you to build an AI chat bot using Agents Toolkit and debug with the Test Tool. You'll see the following output after you've completed this guide, where the user can access and use the AI chat bot:

:::image type="content" source="../assets/images/toolkit-v2/debug/test-tool.png" alt-text="Screenshot shows the bot open in Test Tool." lightbox="../assets/images/toolkit-v2/debug/test-tool.png":::

Install	For using...
Visual Studio Code or Visual Studio	JavaScript, TypeScript, or C# build environments. Use the latest version.
Microsoft 365 Agents Toolkit	Microsoft Visual Studio Code extension that creates a project scaffolding for your app. Use Agents Toolkit v5.4.0. For more information, see install Agents Toolkit.
Node.js	Back-end JavaScript runtime environment. For more information, see Node.js version compatibility table for project type.
OpenAI or Azure OpenAI	First create your OpenAI API key to use OpenAI's GPT. If you want to host your app or access resources in Azure, you must create an Azure OpenAI service.
Microsoft Edge (recommended) or Google Chrome	A browser with developer tools.

Create project workspace for your AI chat bot app

The bot capability of a Teams app creates a chatbot or a conversational bot. It communicates with a web service, facilitating the use of its services. The bot can execute simple, automated tasks such as delivering customer service. You can get weather forecast, make reservations, or any other service offered using a conversational bot.

:::image type="content" source="../assets/images/toolkit-v2/first-bot/your-helloworld-app-bot.png" alt-text="The screenshot shows you the app with three features. Bot is highlighted.":::

As you've already prepared for creating these apps, you can set up a new Teams project for creating the AI chat bot app.

Create your bot project workspace

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

Open Visual Studio Code.
Select the Microsoft 365 Agents Toolkit :::image type="icon" source="../assets/images/toolkit-v2/toolkit-sidebar-icon.PNG" border="false"::: icon in the Visual Studio Code Activity Bar.
Select Create a New Agent/App.

:::image type="content" source="../assets/images/toolkit-v2/create-project.png" alt-text="The screenshot shows the location of the Create New Project link in the Agents Toolkit sidebar.":::
Select Agents for Teams > Azure OpenAI > enter an input in Input Azure API service key now

:::image type="content" source="../assets/images/toolkit-v2/first-bot/create-newapp.png" alt-text="Screenshot shows the Agents Toolkit app templates.":::
Select Basic Agents for Teams. If you need a different functionality for your bot, select the required option.

:::image type="content" source="../assets/images/toolkit-v2/debug/ai-chat-bot.png" alt-text="Screenshot shows the app feature to add to your new app.":::
Select the programming language as JavaScript.

:::image type="content" source="../assets/images/agents-playground/select-language-bot.png" alt-text="Screenshot displays the option to select the programming language.":::
Select Default folder.

:::image type="content" source="../assets/images/toolkit-v2/first-bot/select-default-location.png" alt-text="Screenshot displays the selection of default location.":::

To change the default location, follow these steps:
1. Select Browse.
  
  :::image type="content" source="../assets/images/toolkit-v2/first-bot/select-browse.png" alt-text="Screenshot shows the selection of browse location option.":::
2. Select the location for the project workspace.
3. Select Select Folder.
  
  :::image type="content" source="~/assets/images/toolkit-v2/select-folder.png" alt-text="Screenshot shows the folder to select.":::
Enter a suitable name for your app and then select the Enter key.

:::image type="content" source="../assets/images/toolkit-v2/first-bot/hello-bot.png" alt-text="Screenshot shows where to enter the app name.":::

A dialog appears, where you need to choose yes or no to trust the authors of the files in this folder.

:::image type="content" source="../toolkit/toolkit-v4/sbs-v4/images-sbs/teams-toolkit-v4/first-bot/vsc-trust-authors.png" alt-text="Screenshot shows the dialog to trust or not the authors of the files in this folder.":::

Now, you've successfully created your AI chat bot project workspace.

Take a tour of the bot app source code

After you finish scaffolding, explore the project directories and files in the EXPLORER section of the Visual Studio Code.

:::image type="content" source="../assets/images/agents-playground/source-code.png" alt-text="Screenshot shows the Teams Toolkit sample bot folder Structure.":::

Folder or file name	Contents
`env/.env.playground`	The configuration file with environment variables that can be committed to Git.
`env/.env.playground.user`	The configuration file with environment variables, including credentials, which aren't committed to Git by default.
`appPackage`	App manifest template files and app icons (color.png and outline.png).
`appPackage/manifest.json`	App manifest for running the app in local and remote environment.
`src/app.js`	Handles business logics for the AI chat bot.
`m365agents.yml`	This is the main Agents Toolkit project file. The project file defines two primary things: Properties and configuration and stage definitions.
`m365agents.local.yml`	This overrides `m365agents.yml` with actions that enable local execution and debugging.
`m365agents.playground.yml`	This overrides `m365agents.yml` with actions that enable local execution and debugging in Test Tool.

Build and run your AI chat bot app

Create OpenAI key and endpoint for your AI chat bot

Go to Azure portal.
Select Create a resource and search for Azure OpenAI.
Select Azure OpenAI and select Create.

:::image type="content" source="../assets/images/agents-playground/azure-open-ai.png" alt-text="Screenshot shows the Azure OpenAI in Azure portal.":::
Fill the required details and select Next.

:::image type="content" source="../assets/images/agents-playground/azure-open-ai-resource.png" alt-text="Screenshot shows you the Azure OpenAI subscription and resource group.":::
Select All networks, including the internet, can access this resource and then select Next.

:::image type="content" source="../assets/images/agents-playground/azure-open-ai-network.png" alt-text="Screenshot shows the Azure OpenAI network details.":::
Fill the required details and select Next.

:::image type="content" source="../assets/images/agents-playground/azure-open-ai-tags.png" alt-text="Screenshot shows the Azure OpenAI tags details.":::
Select Create.

:::image type="content" source="../assets/images/agents-playground/review-create.png" alt-text="Screenshot shows you to preview and create Azure OpenAI.":::

You've successfully created key and endpoint for your AI chat bot.

:::image type="content" source="~/assets/images/agents-playground/deployment.png" alt-text="Screenshot shows the deployment of the Azure OpenAI.":::

[!NOTE] You can also get OpenAI API key to debug your AI chat bot.

Get Azure OpenAI keys and endpoint

Select Go to resources.

:::image type="content" source="../assets/images/agents-playground/deployment-azure.png" alt-text="Screenshot shows you the deployment of the Azure OpenAI.":::
Select Keys and Endpoint from the left pane and copy the KEY and Endpoint. You can copy either KEY 1 or KEY 2.

:::image type="content" source="../assets/images/agents-playground/key-endpoints.png" lightbox="~/assets/images/agents-playground/key-endpoints.png" alt-text="Screenshot shows the keys and endpoints.":::

Save the KEY and Endpoint for further use.
Select Model deployments from the left pane and select Manage Deployments.

:::image type="content" source="../assets/images/agents-playground/model-deployments.png" lightbox="~/assets/images/agents-playground/model-deployments.png" alt-text="Screenshot shows the model deployment for Azure OpenAI.":::

The Azure OpenAI Studio window appears.
Select Deployments from the left pane and select + Create new deployment.

:::image type="content" source="../assets/images/agents-playground/ai-studio.png" lightbox="~/assets/images/agents-playground/ai-studio.png" alt-text="Screenshot shows the model deployments for Azure OpenAI.":::
Select the following details:
1. Select gpt-35-turbo from the Select a model dropdown list.
  
  [!NOTE] Only gpt-35-turbo model is supported for the AI chat bot.
2. Select 0301 (Default) from the Model version dropdown list.
3. Enter Deployment name and select Create.
  
  :::image type="content" source="../assets/images/agents-playground/model-version.png" lightbox="~/assets/images/agents-playground/model-version.png" alt-text="Screenshot shows the model and version for Azure OpenAI deployment.":::
4. Copy and save the Deployment name for further use.
  
  :::image type="content" source="../assets/images/agents-playground/copy-deployment.png" lightbox="~/assets/images/agents-playground/copy-deployment.png" alt-text="Screenshot shows the deployment name for Azure OpenAI deployment.":::

Update Azure OpenAI key and endpoints

Open your project in Visual Studio Code.
Under EXPLORER, go to env > .env.playground.user file.

Enter your SECRET_AZURE_OPENAI_API_KEY and SECRET_AZURE_OPENAI_ENDPOINT.

...
SECRET_AZURE_OPENAI_API_KEY=<azure-openai-api-key>
SECRET_AZURE_OPENAI_ENDPOINT=<azure-openai-endpoint>

Go to src > app.js file.
Comment the OpenAI code and uncomment the Azure OpenAI code.

Enter your Azure OpenAI deployment name in azureDefaultDeployment.

// Use OpenAI
// apiKey: config.openAIKey,
// defaultModel: "gpt-3.5-turbo",

azureApiKey: config.azureOpenAIKey,
azureDefaultDeployment: "gpt-35-turbo",
azureEndpoint: config.azureOpenAIEndpoint,

Debug and run your AI chat bot app

From the left pane, select RUN and DEBUG (Ctrl+Shift+D), and then select Debug in Agents Playground from the dropdown list.

:::image type="content" source="~~/assets/images/toolkit-v2/debug/select-debug-in-test-tool.png" lightbox="~~/assets/images/toolkit-v2/debug/select-debug-in-test-tool.png" alt-text="Screenshot shows the option to select debug in Agents Playground.":::
Agents Playground opens your AI chat bot in a webpage.

:::image type="content" source="~~/assets/images/toolkit-v2/debug/test-tool.png" lightbox="~~/assets/images/toolkit-v2/debug/test-tool.png" alt-text="Screenshot shows the bot open in Test Tool.":::

Activity triggers

There are two types of activity triggers:

Predefined activity triggers

Agents Playground provides predefined activity triggers to test the functionalities of your bot.

Category	Activity	Handler
Trigger Installation Update Activity	Install bot Uninstall bot	`onInstallationUpdate` `onInstallationUpdateAdded` `onInstallationUpdate` `onInstallationUpdateRemove`
Trigger Conversation Update Activity	Add user Add bot Add channel	`onMembersAdded` `onTeamsMembersAddedEvent` `onMembersAdded` `onTeamsMembersAddedEvent` `onTeamsChannelCreatedEvent`
	Remove user Remove bot Remove channel Remove team	`onMembersRemoved` `onTeamsMembersRemovedEvent` `onMembersRemoved` `onTeamsMembersRemovedEvent` `onTeamsChannelDeletedEvent` `onTeamsTeamDeletedEvent`
	Rename channel Rename team	`onTeamsChannelRenamedEvent` `onTeamsTeamRenamedEvent`

[!NOTE] All types of activities aren't available in all scopes. For example, you can't add or remove a channel in a personal chat or a group chat.

Predefined activity triggers are available in the Mock an Activity menu in Agents Playground.

To mock an Add user activity, follow these steps:

In Agents Playground, go to Mock an Activity > Add user.

:::image type="content" source="../assets/images/toolkit-v2/debug/add-user.png" alt-text="Screenshot shows the Add user option under mock an activity.":::

A dialog appears to preview the activity handler.
Select Send activity.

:::image type="content" source="../assets/images/toolkit-v2/debug/add-a-user-request.png" alt-text="Screenshot shows the option to send activity for predefined mock activity add user.":::

Bot sends the following response:

:::image type="content" source="~/assets/images/toolkit-v2/debug/add-a-user-response.png" alt-text="Screenshot shows the response of predefined mock activity add user.":::

Custom activity triggers

You can use Custom activity to customize activity triggers, for example, reactionsAdded to meet the requirements of your bot app. Agents Playground automatically populates the required properties of the activity. You can also modify the activity type and add more properties.

Select Mock an Activity > Custom activity.

:::image type="content" source="../assets/images/toolkit-v2/debug/mock-activity.png" alt-text="Screenshot shows the list of option under mock an activity.":::

Add messageReaction to customize the activity under the type property:

{
    "type": "messageReaction",
    "reactionsAdded": [
    {
        "type": "like"
    }
    ],
    "replyToId": "d60fd1cb-3e8f-44ef-849c-404806ba1b47"
}

Select Send activity.

:::image type="content" source="~/assets/images/toolkit-v2/debug/custom-activity-request.png" alt-text="Screenshot shows the option to send activity after customization on mock activity.":::

Bot sends an onReactionsAdded handler in response.

:::image type="content" source="../assets/images/toolkit-v2/debug/custom-activity-response.png" alt-text="Screenshot shows the response of custom mock activity.":::

Complete challenge

Did you come up with output like this?

:::image type="content" source="~~/assets/images/toolkit-v2/debug/test-tool.png" lightbox="~~/assets/images/toolkit-v2/debug/test-tool.png" alt-text="Screenshot shows the bot open in Test Tool.":::

Congratulations! You've successfully created an AI chat bot app. Now, you've learned to debug your AI chat bot app in Agents Playground.

[!div class="nextstepaction"] Microsoft 365 Agents Playground

Send proactive messages

A proactive message is a message sent by a bot in response to simple commands sent in the chat from a user.

Tutorial: Send proactive messages

The message response can be in one of the following formats:

Welcome messages
Scheduled messages
Notifications

This step-by-step guide helps you to send a proactive message from a bot. You'll see the following output:

:::image type="content" source="~/assets/images/proactive-scenario/proactive-msg-result.png" alt-text="Screenshot shows the proactive hello message in Teams chat.":::

Prerequisites

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

	Install	For using
	Microsoft Visual Studio Code	JavaScript or TypeScript, build environments. Use the latest version.
	Microsoft 365 Agents Toolkit (previously known as Teams Toolkit)	Visual Studio Code extension that creates a project scaffolding for your app. Use the latest version.
	Node.js	Back-end JavaScript runtime environment. For more information, see Node.js version compatibility table for project type.
	Microsoft Teams	Teams to collaborate with everyone you work with through apps for chat, meetings, call and all in one place.
	Microsoft Edge (recommended) or Google Chrome	A browser with developer tools.
	Microsoft 365 developer account	Access to Teams account with the appropriate permissions to install an app.

Prepare development environment

After you install the required tools, set up the development environment.

Install Microsoft 365 Agents Toolkit

Microsoft 365 Agents Toolkit (previously known as 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 Agents Toolkit with Visual Studio Code or a command-line interface called Microsoft 365 Agents Toolkit CLI (previously known as TeamsFx CLI).

Visual Studio Code

Open Visual Studio Code and select Extensions (Ctrl+Shift+X or View > Extensions).
In the search box, enter Microsoft 365 Agents Toolkit.
Select Install.

:::image type="content" source="../assets/images/include-files/install-toolkit-vs.png" alt-text="Screenshot shows the Agents Toolkit extension installation.":::

The Microsoft 365 Agents Toolkit :::image type="icon" source="../assets/images/include-files/toolkit-sidebar-icon.PNG"::: icon appears in the Visual Studio Code Activity Bar.

You can also install Agents Toolkit from the Visual Studio Code Marketplace.

Command Line

To install Agents Toolkit CLI, use the npm package manager and enter the following command in Command prompt:

npm install -g @microsoft/m365agentstoolkit-cli

Depending on your configuration, you might need to use sudo to install the CLI:

sudo npm install -g --unsafe-perm @microsoft/m365agentstoolkit-cli

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

[!CAUTION] Before you can run TeamsFx in PowerShell terminals, you must enable the remote signed execution policy for PowerShell.

Set up your Teams development tenant

Check for upload an app option

After creating your custom app, you must upload your app to Teams with the Upload a custom app option. Sign in to your Microsoft 365 account to check if this option is enabled.

The following steps help you verify if you can upload apps in Teams:

In the Teams client, select the Apps icon.
Select Manage your apps.
Select Upload an app.
Look for the option to Upload a custom app. If the option is visible, you can upload custom apps.

:::image type="content" source="../assets/images/toolkit-v2/prerequisites/upload-custom-app.png" alt-text="Screenshot shows the option to upload a custom app in Teams." :::

[!NOTE] If you don't find the option to upload a custom app, contact your Teams administrator.

Create a free Teams developer tenant (optional)

If you don't have a Teams developer account, join the Microsoft 365 developer program.

Go to the Microsoft 365 developer program.
Select Join Now and follow the onscreen instructions.
In the welcome screen, select Set up E5 subscription.
Set up your administrator account. After you finish, the following screen appears:

:::image type="content" source="../assets/images/include-files/microsoft-365.png" alt-text="This screenshot displays the Microsoft 365 Developer Program.":::
Sign in to Teams using the administrator account you just set up. Verify that you have the Upload a custom app option in Teams.

Build Proactive Message bot

To build proactive message bot using Visual Studio Code, follow these steps:

Open Visual Studio Code.
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.
In the left pane, select View Samples.

:::image type="content" source="../assets/images/proactive-scenario/view-samples.png" alt-text="Screenshot shows the View Samples option in Visual Studio Activity Bar.":::
From the list of samples, select Proactive Messaging. A prebuilt sample that's ready for debugging opens.

:::image type="content" source="../assets/images/proactive-scenario/select-proactive-msg.png" alt-text="Screenshot shows the prebuilt Proactive Messaging bot sample in the list of samples.":::
Select Create.

:::image type="content" source="../assets/images/proactive-scenario/create-proactive-bot.png" alt-text="Screenshot shows the Create option to create a proactive messaging bot.":::
Select Default folder to store your project root folder in the default location.

:::image type="content" source="../assets/images/sbs-notification-bot/select-default-location.png" alt-text="Screenshot shows the option to select the default location.":::

If you want to change the default location, perform the following steps:
1. Select Browse.
  
  :::image type="content" source="../assets/images/sbs-notification-bot/select-browse.png" alt-text="Screenshot shows the option to browse the location.":::
2. Select the location for project workspace.
3. Select Select Folder.
  
  :::image type="content" source="../assets/images/sbs-notification-bot/select-folder.png" alt-text="Screenshot shows the option to select the folder.":::
The proactive message bot is created in a few seconds and displays the proactive message bot successful dialog in the lower-right corner with the option to debug:

:::image type="content" source="../assets/images/proactive-scenario/proactive-bot-created.png" alt-text="Screenshot shows the proactive message bot created."lightbox="../assets/images/proactive-scenario/proact-bot-created-1.png"::::::
Select Run and Debug :::image type="icon" source="../assets/images/proactive-scenario/run-debug-icon.png"::: icon from the top-left corner.
Select Debug (Edge) or Debug (Chrome) from the dropdown list.

:::image type="content" source="../assets/images/proactive-scenario/debug-option-edge.png" alt-text="Screenshot shows the debugging options to choose from.":::

When debugging is successful, you are prompted to upload the proactive message bot to Teams on your local machine.
Select Add.

:::image type="content" source="../assets/images/proactive-scenario/add.png" alt-text="Screenshot of message extension details dialog with the Add option highlighted.":::
Search and select the required scope or select a channel, chat, or meeting from the list, and move through the dialog to select Go.

:::image type="content" source="../assets/images/proactive-scenario/add-to-teams.png" alt-text="Screenshot of the scope selection dialog showing the list of shared scopes.":::

The proactive message bot app is uploaded to Teams client and the following message appears in response to the message sent.

:::image type="content" source="../assets/images/proactive-scenario/proactive-msg-sent.png" alt-text="Screenshot shows the proactive message bot response in the chat.":::
Copy and paste the URL or navigate to the URL in browser. A proactive hello message is triggered and shared in the chat.

:::image type="content" source="../assets/images/proactive-scenario/pro-msg-browser.png" alt-text="Screenshot shows the browser that triggers bot to respond with a proactive message in Teams.":::
Go to Teams. You'll receive a proactive hello message from the bot.

:::image type="content" source="../assets/images/proactive-scenario/pro-msg-response.png" alt-text="Screenshot shows the bot response on the chat.":::

Take a tour of the source code

Agents Toolkit provides components for building an app. After creating the project, you can view the project folders and files in the EXPLORER area of Visual Studio Code.

:::image type="content" source="../assets/images/proactive-scenario/file-structure.png" alt-text="Screenshot shows the structure tab.":::

The new project folder contains the following content:

Folder / File	Contents
`.vscode/`	Visual Studio Code files for debugging.
`appManifest/`	Templates for the app manifest (previously called Teams app manifest).
`env/`	Name / value pairs are stored in environment files and used by `m365agents.yml` to customize the provisioning and deployment rules.
`manifest.json`	App manifest for publishing through the Developer Portal for Teams is stored in `Properties/manifest.json`.
`m365agents.yml`	Main project file describes your app configuration and defines the set of actions to run in each lifecycle stage.
`m365agents.local.yml`	This overrides `m365agents.yml` with actions that enable local execution and debugging.

Deploy your Proactive message bot

You've learnt to build and run Teams app with proactive message bot capability. Let's deploy the first app with proactive message bot capability on Azure using Agents Toolkit.

Sign in to your Azure account

Use your account to access the Microsoft Azure portal and provision new cloud resources to support your app.

Open Visual Studio Code.
Open the project folder where you created the proactive message bot app.
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.
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.

Your default web browser opens to let you sign in to the account.
Close the browser when prompted and return to Visual Studio Code.

The ACCOUNTS section of the sidebar shows the two accounts separately. It also lists the number of usable Azure subscriptions available to you. Ensure that you have at least one usable Azure subscription available. If not, sign out and use a different account.

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

What's the difference between Provision and Deploy?

Provision creates resources in Azure and Microsoft 365 for your app, but no code (HTML, CSS, and JavaScript) is copied to the resources.
Deploy copies the code for your app to the resources you created during provisioning. It's common to deploy multiple times without provisioning new resources. Since provisioning can take some time to complete, it's separate from deployment.

Visual Studio Code

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.
Select Provision under LIFECYCLE.

:::image type="content" source="../assets/images/sbs-command-bot/provision-cloud.png" alt-text="Screenshot shows the provisioning commands.":::
Select one of the existing subscriptions.

:::image type="content" source="../assets/images/proactive-scenario/select-subscription.png" alt-text="Screenshot shows the subscription option for provisioning.":::
Select an existing resource group or create new resource group. For more information, see create resource group.

:::image type="content" source="../assets/images/proactive-scenario/select-resource-group.png" alt-text="Screenshot show the resource group option for provisioning.":::

[!NOTE] A dialog appears mentioning that costs might be incurred when running resources in Azure.
Select Provision.

:::image type="content" source="../assets/images/sbs-command-bot/provision-confirm1.png" alt-text="Screenshot of the provisioning dialog.":::

The provisioning process creates resources in the Azure cloud. You can monitor the progress in the dialogs that appear in lower-right corner. After few minutes, the following dialog appears:

:::image type="content" source="../assets/images/proactive-scenario/deploy-provision-proactive.png" alt-text="Screenshot shows the provisioning complete dialog.":::
Select Deploy under LIFECYCLE.

:::image type="content" source="../assets/images/sbs-command-bot/deploy-cloud.png" alt-text="Screenshot shows the Deploy option under LIFECYCLE.":::
Select Deploy.

:::image type="content" source="../assets/images/sbs-command-bot/Deploy-confirm.png" alt-text="Screenshot shows the confirmation dialog to deploy.":::

Deployment takes some time. You can monitor the progress in the dialogs that appear in lower-right corner. After a few minutes, the following dialog appears.

:::image type="content" source="../assets/images/proactive-scenario/deploy-confirmation-proactive.png" alt-text="Screenshot shows the deployment confirmation dialog.":::
Open the debug panel (Ctrl+Shift+D / ⌘⇧-D or View > Run) from Visual Studio Code.
Select Launch Remote (Edge) from the launch configuration dropdown list.

:::image type="content" source="../assets/images/proactive-scenario/debug-option-remote.png" alt-text="Screenshot shows the remote debug option highlighted.":::

When debugging is successful, you are prompted to upload the proactive message bot app to Teams.
Select Add.

:::image type="content" source="../assets/images/proactive-scenario/add.png" alt-text="Screenshot of message extension app dialog with the Add option highlighted.":::
Search and select the required scope or select a channel, chat, or meeting from the list, and move through the dialog to select Go.

:::image type="content" source="../assets/images/proactive-scenario/add-to-teams.png" alt-text="Screenshot shows the scope selection dialog with the list of shared scopes.":::

The proactive message bot app is uploaded to Teams client and the following message appears in response to the message sent.

:::image type="content" source="../assets/images/proactive-scenario/proactive-msg-sent.png" alt-text="Screenshot shows the proactive message bot response in the chat.":::
Copy and paste the URL or navigate to the URL in browser. A proactive hello message is triggered and shared in the chat.

:::image type="content" source="../assets/images/proactive-scenario/pro-msg-browser.png" alt-text="Screenshot shows the browser that triggers bot to respond with a proactive message in Teams.":::
Go to Teams. You'll receive a proactive hello message from the bot.

:::image type="content" source="../assets/images/proactive-scenario/pro-msg-response.png" alt-text="Screenshot shows the bot response on the chat.":::

Command Line

In your terminal window:

Run atk new to create new project.

atk new

Run atk provision to create azure resource.

atk provision

Run atk deploy to deploy the app.

atk deploy

Run atk preview to run the app.

atk preview

Complete challenge

Did you come up with something like this?

:::image type="content" source="../assets/images/proactive-scenario/proactive-msg-result.png" alt-text="Screenshot shows the proactive hello message.":::

You've completed the scenario.

You can send notifications on a daily basis or request for feedback from users on a periodic basis.
You can handle throttling limits to avoid multiple notifications.

[!div class="nextstepaction"] Send proactive messages

Build API-based message extension

Message extensions built using API (API-based) significantly enhance the functionality of your Teams apps by allowing them to interact with external services. API-based message extensions can help streamline workflows by reducing the need to switch between different applications.

Tutorial: Build API-based message extension

[!NOTE] API-based message extensions only support search commands.

You can use API-based message extensions to integrate external services that are commonly used in the business workflow. For example, a business that frequently uses a CRM system for customer management could use a message extension to fetch and display customer data directly from Teams. This app helps save time and improves efficiency by reducing the need to switch between different applications. This feature is supported on all platforms where Teams is available, including desktop, web, and mobile.

Prerequisites for building a message extension

Here's a list of tools you need for building and deploying your apps.

Install	For using...
Microsoft Teams	Microsoft Teams to collaborate with everyone you work with through apps for chat, meetings, or call - all in one place.
Microsoft Edge (recommended) or Google Chrome	A browser with developer tools.
Visual Studio Code	JavaScript, TypeScript, or SharePoint Framework (SPFx) build environments. Use version 1.55 or later.
Microsoft 365 developer account	Access to Teams account with the appropriate permissions to install an app.
Azure account	Access to Azure resources.
OpenAPI Description (OAD) document	A document that describes the capabilities of your API. For more information, see OpenAPI Description.

Set up your Teams development tenant

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

Check for custom app upload option

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

[!NOTE] Custom app upload is necessary for previewing and testing apps in Teams local environment. If it isn't enabled, you can't preview and test your app in Teams local environment.

Do you already have a tenant, and do you have the admin access? Let's check if you really do!

Verify if you can upload a custom app in Teams:

In the Teams client, select the Apps icon.
Select Manage your apps.
Select Upload an app.
Look for the option to Upload a custom app. If you see the option, custom app upload is enabled.

:::image type="content" source="~/assets/images/toolkit-v2/spfx-custom-new1.png" alt-text="Screenshot shows the bot home.":::

[!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 free. Join the Microsoft 365 developer program!

Go to the Microsoft 365 developer program.
Select Join Now and follow the onscreen instructions.
In the welcome screen, select Set up E5 subscription.
Set up your administrator account. After you finish, the following screen appears.

:::image type="content" source="../assets/images/toolkit-v2/prerequisites/microsoft-365.png" alt-text="The screenshot displays the Microsoft 365 Developer Program.":::
Sign in to Teams using the administrator account you just set up. Verify that you have the Upload a custom app option in Teams.

Get a free Azure account

If you want to host your app or access resources in Azure, you must have an Azure subscription. Create a free account before you begin.

You have 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 build first.

Create OpenAPI Description document

OpenAPI Description (OAD) is the industry-standard specification that outlines how OpenAPI files are structured and outlined. It's a language-agnostic, human-readable format for describing APIs. It's easy for both humans and machines to read and write. The schema is machine-readable and represented in either YAML or JSON.

To interact with the APIs, an OpenAPI Description document is necessary. The OpenAPI Description document must meet the following criteria:

The auth property must not be specified.
JSON and YAML are the supported formats.
OpenAPI Versions 2.0 and 3.0.x are supported.
Teams doesn't support the oneOf, anyOf, allOf, and not (swagger.io) constructs.
Constructing arrays for the request isn't supported, however, nested objects within a JSON request body are supported.
The request body, if present, must be application/Json to ensure compatibility with a wide range of APIs.
Define an HTTPS protocol server URL for the servers.url property.
Only single parameter search is supported.
Only one required parameter without a default value is allowed.
Only POST and GET HTTP methods are supported.
The OpenAPI Description document must have an operationId.
The operation mustn't require Header or Cookie parameters without default values.
A command must have exactly one parameter.
Ensure that there are no remote references in the OpenAPI Description document.

A required parameter with a default value is considered optional.

We used the following OpenAPI Description as an example for this tutorial:

OpenAPI Description

    openapi: 3.0.1
    info:
    title: OpenTools Plugin
    description: A plugin that allows the user to find the most appropriate AI tools for their use cases, with their pricing information.
    version: 'v1'
    servers:
        - url: https://gptplugin.opentools.ai
    paths:
    /tools:
    get:
    operationId: searchTools
    summary: Search for AI Tools
        parameters:
        - in: query
          name: search
          required: true
          schema:
          type: string
          description: Used to search for AI tools by their category based on the keywords. For example, a search for "tool to create music" provides a list of tools that can create music.
        responses:
        "200":
          description: OK
          content:
          application/json:
            schema:
            $ref: '#/components/schemas/searchToolsResponse'
        "400":
          description: Search Error
          content:
          application/json:
            schema:
            ref: '#/components/schemas/searchToolsError'
        components:
        schemas:
        searchToolsResponse:
        required:
        - search
        type: object
        properties:
        tools:
        type: array
        items:
        type: object
        properties:
        name:
        type: string
        description: The name of the tool.
        opentools_url:
        type: string
        description: The URL to access the tool.
        main_summary:
        type: string
        description: A summary of what the tool is.
        pricing_summary:
        type: string
        description: A summary of the pricing of the tool.
        categories:
        type: array
        items:
        type: string
        description: The categories assigned to the tool.
        platforms:
        type: array
        items:
        type: string
        description: The platforms that this tool is available on.
        description: The list of AI tools.
        searchToolsError:
        type: object
        properties:
        message:
        type: string
        description: Message of the error.

[!NOTE] Ensure that the required: true property is available for only one parameter. If there are more than one required parameters, you can update the required property to required: false for the other parameters.

You can validate if the OpenAPI Description document is valid. To verify, follow these steps:

Go to Swagger or OpenAPI validator and validate the OpenAPI Description document.
Save the OpenAPI Description document.
Go to Swagger Editor.
In the left pane, paste the OpenAPI Description in the editor.
In the right pane, select GET.
Select Try it out.
Enter the values for the search parameter as Tool to create music.
Select Execute. The swagger editor displays a response with a list of products.

:::image type="content" source="../assets/images/Copilot/api-me-sbs-execute-get-response.png" alt-text="Screenshots shows the parameters, its values, and the EXECUTE option in the swagger editor.":::
Go to Server response > Response Body.
Under products, copy the first product from the list and save it for future reference.

:::image type="content" source="../assets/images/Copilot/api-me-sbs-product-response.png" alt-text="Screenshots shows the highlighted product that is selected from the response body.":::

Create response rendering template

An OpenAPI Description document requires a response rendering template for the app to respond to the GET or POST requests. The response rendering template consists of an Adaptive Card template, Preview card template, and metadata.

Adaptive Card template

To create an Adaptive Card template, follow these steps:

Go to ChatGPT and ask the following query in the message compose area:

Create an Adaptive Card Template that binds to the following response:
    "categories": [
        "Music Generation",
        "AI Detection"
    ],
    "chatbot_short_url": "https://goto.opentools.ai/c/ai-music-generator",
    "main_summary": "AI Music Generator is an AI-powered music composing tool that allows users to create original and personalized music for various purposes. It can generate melodies, harmonies, and rhythms tailored to specific needs and preferences, with customization options such as genre, mood, length, and instrumentation. The tool is designed for creative individuals, from beginners to professionals, and can produce high-quality music in seconds. Every generated piece of music is royalty-free and can be used instantly, with no limitations on beat creation. With advanced AI technology, AI Music Generator makes music production accessible to everyone.",
    "name": "AI Music Generator",
    "opentools_url": "https://goto.opentools.ai/ai-music-generator",
    "platforms": [
        "Web",
        "App",
        "API"
    ]

Select Send message.

ChatGPT generates a response with an Adaptive Card template that binds to the sample data. Save the Adaptive Card template for future reference.

Following is an example of the Adaptive Card template:

Adaptive Card template

{
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"type": "AdaptiveCard",
"version": "1.4",
"body": [
    {
    "type": "TextBlock",
    "text": "AI Music Generator",
    "weight": "Bolder",
    "size": "Large"
    },
    {
    "type": "TextBlock",
    "text": "Categories",
    "size": "Medium"
    },
    {
    "type": "TextBlock",
     "text": "Music Generation, AI Detection",
     "wrap": true
    },
    {
    "type": "TextBlock",
    "text": "Description",
    "size": "Medium"
    },
    {
    "type": "TextBlock",
    "text": "AI Music Generator is an AI-powered music composing tool that allows users to create original and personalized music for various purposes. It can generate melodies, harmonies, and rhythms tailored to specific needs and preferences, with customization options such as genre, mood, length, and instrumentation. The tool is designed for creative individuals, from beginners to professionals, and can produce high-quality music in seconds. Every generated piece of music is royalty-free and can be used instantly, with no limitations on beat creation. AI Music Generator is powered by advanced AI technology, and it makes music production accessible to everyone.",
    "wrap": true
    },
    {
    "type": "TextBlock",
    "text": "Platform",
    "size": "Medium"
    },
    {
    "type": "TextBlock",
    "text": "Web, App, API",
    "wrap": true
    }
],
"actions": [
    {
    "type": "Action.OpenUrl",
    "title": "Learn More",
    "url": "https://goto.opentools.ai/ai-music-generator"
    },
    {
    "type": "Action.OpenUrl",
    "title": "Try It",
    "url": "https://goto.opentools.ai/c/ai-music-generator"
    }
]
}

To verify if the Adaptive Card generated binds to the sample data, follow these steps:
1. Go to Adaptive Card Designer.
2. Go to Select host app, and then select Microsoft Teams from the dropdown.
3. Go to CARD PAYLOAD EDITOR and paste the Adaptive Card template code.
4. Go to SAMPLE DATA EDITOR and paste the GET API response that you saved earlier.
  
  :::image type="content" source="../assets/images/Copilot/api-me-sbs-adaptive-card-designer.png" alt-text="Screenshots shows the Adaptive Card designer with the Adaptive Card template and the sample data.":::
5. Select Preview mode. The Adaptive Card designer displays an Adaptive Card with the data that binds the response to the template.
  
  :::image type="content" source="../assets/images/Copilot/api-me-sbs-adaptive-card-preview.png" alt-text="Screenshot shows the Adaptive Card designer with the Adaptive Card template and the sample data.":::

Create a preview card template

The preview card template can contain a title, subtitle, and image properties. If the API response doesn't have an image, you can remove the image property.

Following is an example of a preview card template:

Preview card template

   "previewCardTemplate": {
        "title": "${if(name, name, 'N/A')}",
        "subtitle": "$${if(price, price, 'N/A')}"
    }

Create an if condition for the title and subtitle, where:

If name exists, the bot uses the name.
If name doesn't exist, the bot uses NA.

For example, "title": "Name: ${if(name, name, 'N/A')}". Save the preview card template for future reference.

Response rendering template

The response rendering template must conform to the schema hosted at https://developer.microsoft.com/json-schemas/teams/v1.20/MicrosoftTeams.ResponseRenderingTemplate.schema.json.

To create a response rendering template, follow these steps:

Create a JSON file and add the following code to the file:

{ 
  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.20/MicrosoftTeams.ResponseRenderingTemplate.schema.json", 
  "version": "1.0", 
  "jsonPath": "", 
  "responseLayout": "", 
  "responseCardTemplate": { 
 },
 "previewCardTemplate": {
     }
 }

Update the properties in the response rendering template as follows:

#	Property name	Value
1.	`"$schema"`	`"https://developer.microsoft.com/json-schemas/teams/v1.20/MicrosoftTeams.ResponseRenderingTemplate.schema.json"`
2.	`"version"`	`"1.0"` `version` is the version of the rendering template to use.
3.	`"jsonPath"`	`"tools"` `jsonPath` is the path to one or more results in the response JSON response. Add the `jsonPath` to the relevant data/array from the product list in the API response. In this case, the `jsonPath` is tools. For more information on how to determiner the JSON path, see Querying JSON with JSON path.
4.	`"responseLayout"`	`"list"` `responseLayout` specifies the layout of the attachments. Used for responses of type result. Supported types are list and grid. If the response body contains an object with multiple elements like text, title, and image, then the response layout must be set to `list`. If the API response contains only images or thumbnails, then the response layout must be set to `grid`.
5.	`"responseCardTemplate"`	Paste the Adaptive Card template code that you saved earlier. `responseCardTemplate` is an Adaptive Card template to map the JSON response to an Adaptive Card.
6.	`"previewCardTemplate"`	Paste the preview card template code that you saved earlier. `previewCardTemplate` is a preview card template is used to show a preview of results in the message extension flyout.

Save the response rendering template in the same folder you saved the OpenAPI Description document.

The following code is an example of a Response rendering template:

Response rendering template

{
    "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.20/MicrosoftTeams.ResponseRenderingTemplate.schema.json",
    "version": "1.0",
    "jsonPath": "tools",
    "responseLayout": "list",
    "responseCardTemplate": {
        "type": "AdaptiveCard",
        "version": "1.4",
        "body": [
            {
            "type": "TextBlock",
            "text": "AI Music Generator",
            "weight": "Bolder",
            "size": "Large"
            },
            {
            "type": "TextBlock",
            "text": "Categories",
            "size": "Medium"
            },
            {
            "type": "TextBlock",
            "text": "Music Generation, AI Detection",
            "wrap": true
            },
            {
            "type": "TextBlock",
            "text": "Description",
            "size": "Medium"
            },
            {
            "type": "TextBlock",
            "text": "AI Music Generator is an AI-powered music composing tool that allows users to create original and personalized music for various purposes. It can generate melodies, harmonies, and rhythms tailored to specific needs and preferences, with customization options such as genre, mood, length, and instrumentation. The tool is designed for creative individuals, from beginners to professionals, and can produce high-quality music in seconds. Every generated piece of music is royalty-free and can be used instantly, with no limitations on beat creation. With advanced AI technology, AI Music Generator makes music production accessible to everyone.",
            "wrap": true
            },
            {
            "type": "TextBlock",
            "text": "Platform",
            "size": "Medium"
            },
            {
            "type": "TextBlock",
            "text": "Web, App, API",
            "wrap": true
            }
        ],
        "actions": [
            {
            "type": "Action.OpenUrl",
            "title": "Learn More",
            "url": "https://goto.opentools.ai/ai-music-generator"
            },
            {
            "type": "Action.OpenUrl",
            "title": "Try It",
            "url": "https://goto.opentools.ai/c/ai-music-generator"
            }
        ]
    },
    "previewCardTemplate": {
        "title": "${if(name, name, 'N/A')}",
        "subtitle": "$${if(price, price, 'N/A')}"
    } 
}

Create app manifest

Now, you need to create an app manifest (previously called Teams app manifest). The app manifest describes how your app integrates into the Microsoft Teams product.

Create a Teams app manifest

To create the manifest, follow these steps:

Create a new JSON file. Your app manifest must conform to the 1.20 version of the schema defined in App manifest schema.

Add the following code to the JSON file:

App manifest

{
 "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.20/MicrosoftTeams.schema.json",
 "manifestVersion": "1.20",
 "version": "1.0.3",
 "id": "<<YOUR-MICROSOFT-APP-ID>>",
 "packageName": "com.microsoft.teams.extension",
 "developer": {
     "name": "Teams App, Inc.",
     "websiteUrl": "https://www.example.com",
     "privacyUrl": "https://www.example.com/termofuse",
     "termsOfUseUrl": "https://www.example.com/privacy"
 },
 "icons": {
     "color": "color.png",
     "outline": "outline.png"
 },
 "name": {
     "short": "Search ME API",
     "full": "Search ME API full"
 },
 "description": {
     "short": "product app for testing API Message Extensions",
     "full": "product app for testing API Message Extensions"
 },
 "accentColor": "#FFFFFF",
 "composeExtensions": [
     {
         "composeExtensionType": "",
         "apiSpecificationFile": "",
         "commands": [
             {
                 "context": [
                     "compose"
                 ],
                 "type": "query",
                 "title": "API for fetching Klarna.",
                 "id": "",
                 "parameters": [
                     {
                         "name": "",
                         "title": "",
                         "description": ""
                     }
                 ],
                 "description": "",
                 "apiResponseRenderingTemplateFile": ""
             }
         ]
     }
 ],
 "permissions": [
     "identity",
     "messageTeamMembers"
 ],
 "validDomains": []
}

Update the app manifest properties as follows:
- Replace <<YOUR-MICROSOFT-APP-ID>> with bot's Microsoft App ID.
- Update the value for composeExtensionType to apiBased.
- Update the value for apiSpecificationFile to the path of your OpenAPI Description file.
- Update the value for commands.id to searchTools.
- Update the value for commands.title to Search for AI Tools.
- Update the value for commands.description to Search for AI Tools.
- Update the value for parameters.name to search. If there are no parameters, then the values must be query parameters or properties.name if referencing a property in the request body schema.
- Update the apiResponseRenderingTemplateFile to the path of your response rendering template file.
- Update the value for validDomains to the service URL endpoint defined in the OpenAPI Description file.
Save the Teams app manifest in the same folder you saved the OpenAPI Description document and the response rendering template.
- You need a color image and outline image. These images should be included in the folder and referenced in your Teams app manifest.
- Zip up the contents of the folder. The zip file must include the following files:
  - OpenAPI Description document
  - Response rendering template
  - App manifest
  - Color icon
  - Outline icon

Upload a custom app to Teams

Sign into Teams test environment to test your app in Teams. To upload a custom app in Teams, follow these steps:

Go to Microsoft Teams and sign in using your test tenant credentials.
Go to Apps > Manage your app > Upload an app.
Select Upload a customized app.
Select the zip file created and select Open.
Select Add.

:::image type="content" source="../assets/images/Copilot/api-me-sbs-add-app-teams.png" alt-text="Screenshot of message extension app with the Add option highlighted.":::
Select Open.

:::image type="content" source="../assets/images/Copilot/api-me-open.png" alt-text="Screenshot of message extension app with the Open option highlighted.":::
Go to a chat, then select + from the message compose area, and search for your app.
Select the app and make a search query.

:::image type="content" source="../assets/images/Copilot/api-based-me-ttk-invoke-teams.png" alt-text="Screenshot shows that from the plus icon in the chat menu, users can invoke the message extension app that is displayed in the flyout menu.":::
The app responds with an Adaptive Card in the chat window.
Select Send.

:::image type="content" source="../assets/images/Copilot/api-based-me-ttk-sbs-result.png" alt-text="Screenshot shows the Adaptive Card with the search results in the chat message in Teams.":::

Congratulations! You did it! You learned to create an API-based message extension using OpenAPI Description document.

[!div class="nextstepaction"] Create an API-based message extension

Build action-based message extension

Teams action based message extension allow users to interact with web services in the Microsoft Teams client. Message extensions help to initiate actions in an external system from the compose message area, the command box, or directly from a message.

Tutorial: Build action-based message extension

Key features of action based message extension:

Presents the user with a modal pop-up to collect or display information.
Triggers the action commands from the compose message area, the command box, or from a message.

This step-by-step guide helps you to build Teams action-based message extension to initiate actions from compose message and message area. By the end of this tutorial, you can achieve the following output:

:::image type="content" source="../assets/images/sbs-messagingextension-action/sharemessageoutput1.png" alt-text="Screenshot of the message extension output after you successfully complete the step-by-step guide.":::

Prerequisites

Ensure that you install the following tools and set up your development environment:

	Install	For using...
	Microsoft Teams	Microsoft Teams to collaborate with everyone you work with through apps for chat, meetings, and call all in one place.
	Visual Studio 2022	You can install the enterprise version in Visual Studio 2022, and install the ASP.NET and web development workloads. Use the latest version.
	.NET Core SDK	Customized bindings for local debugging and Azure Functions app deployments. If you haven't installed the latest version, install the portable version.
	Dev tunnel	Teams app features (conversational bots, message extensions, and incoming webhooks) need inbound connections. A tunnel connects your development system to Teams. Dev tunnel is a powerful tool to securely open your localhost to the internet and control who has access. Dev tunnel is available in Visual Studio 2022 version 17.7.0 or later. or You can also use ngrok as a tunnel to connect your development system to Teams. It isn't required for apps that only include tabs. This package is installed within the project directory (using npm `devDependencies`).

[!NOTE] After downloading ngrok, sign up and install authtoken.

Set up local environment

Open Microsoft-Teams-Samples.
Select Code.
From the dropdown menu, select Open with GitHub Desktop.

:::image type="content" source="../assets/images/include-files/clone-repository.png" alt-text="Screenshot show the option to clone repository in local.":::
Select Clone.

Register Microsoft Entra app

The following steps help you to create and register your bot in Azure portal:

Create and register your Azure app.
Create client secret to enable SSO authentication of the bot.
Add Teams channel to deploy the bot.
Create a tunnel to your web server's endpoints using dev tunnel (recommended) or ngrok.
Add messaging endpoint to the dev tunnel that you created.

Add App registration

Go to Azure portal.
Select App registrations.

:::image type="content" source="../assets/images/include-files/azure-app-registration.png" alt-text="Screenshot shows the Azure services to select App registrations.":::
Select + New registration.

:::image type="content" source="../assets/images/include-files/new-registration.png" alt-text="Screenshot shows the New registration page on Microsoft Entra admin center.":::
Enter the name of your app.
Select Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant).
Select Register.

:::image type="content" source="../assets/images/include-files/app-register.png" alt-text="Screenshot shows the option to register the bot in Microsoft Entra admin center.":::

Your app is registered in Microsoft Entra ID. The app overview page appears.

:::image type="content" source="../assets/images/include-files/app-registration-overview.png" alt-text="Screenshot shows the app registration overview page.":::

[!NOTE] Save the app ID from Application (client) ID and Directory (tenant) ID for further use.

Create a tunnel

Follow one of the following two methods to create a tunnel.

dev tunnel

Open Visual Studio.
Select Create a new project.

:::image type="content" source="../assets/images/include-files/create-new-project.png" alt-text="Screenshot shows the selection to create a new project.":::
In the search box, enter ASP.NET. From the search results, select ASP.NET Core Web App.
Select Next.

:::image type="content" source="../assets/images/include-files/template-search.png" alt-text="Screenshot shows the search and selection of the template.":::
Enter Project name and select Next.

:::image type="content" source="../assets/images/include-files/project-name.png" alt-text="Screenshot shows the project name to enter.":::
Select Create.

:::image type="content" source="../assets/images/include-files/additional-information.png" alt-text="Screenshot shows the project additional information." lightbox="../assets/images/include-files/additional-information.png":::

An overview window appears.

:::image type="content" source="../assets/images/include-files/asp-net-output.png" alt-text="Screenshot shows the overview window.":::
In the debug dropdown list, select Dev Tunnels (no active tunnel) > Create a Tunnel....

:::image type="content" source="../assets/images/include-files/create-tunnel.png" alt-text="Screenshot shows the dropdown to select the dev tunnels.":::

A pop-up window appears.
Update the following details in the pop-up window:
1. Account: Enter a Microsoft or GitHub account.
2. Name: Enter a name for your tunnel.
3. Tunnel Type: From the dropdown list, select Temporary.
4. Access: From the dropdown list, select Public.
Select OK.

:::image type="content" source="../assets/images/include-files/create-tunnel-details.png" alt-text="Screenshot shows the details to update for creation of tunnel.":::

A pop-up window appears showing that dev tunnel is successfully created.
Select OK.

:::image type="content" source="../assets/images/include-files/tunnel-created.png" alt-text="Screenshot shows the pop-up message that the tunnel is created.":::

You can find the tunnel you created in the debug dropdown list as follows:

:::image type="content" source="../assets/images/include-files/tunnel-active.png" alt-text="Screenshot shows the tunnel is active and selected.":::
Select F5 to run the application in the debug mode.
If a Security Warning dialog appears, select Yes.

:::image type="content" source="../assets/images/include-files/security-warning.png" alt-text="Screenshot shows the dialog box to accept the security warning.":::

A pop-up window appears.
Select Continue.

:::image type="content" source="../assets/images/include-files/developer-tunnel.png" alt-text="Screenshot shows the url for the tunnel.":::

The dev tunnel home page opens in a new browser window and the dev tunnel is now active.

:::image type="content" source="../assets/images/include-files/developer-tunnel-web.png" alt-text="Screenshot shows the dev tunnel welcome page in browser.":::
Go to Visual Studio, select View > Output.
From the Output console dropdown menu, select Dev Tunnels.

The Output console shows the dev tunnel URL.

:::image type="content" source="../assets/images/include-files/output-console-url.png" alt-text="Screenshot shows the url in the Visual Studio output console.":::

ngrok

Use ngrok or Command Prompt to create a tunnel to your locally running web server's publicly available HTTPS endpoints. Run the following command in ngrok:

ngrok http --host-header=localhost 3978

[!TIP] If you encounter ERR_NGROK_4018, follow the steps provided in the Command Prompt to sign up and authenticate ngrok. Then run the ngrok http --host-header=localhost 3978 command.

The window shows the HTTPS URL.

:::image type="content" source="../assets/images/include-files/ngrok-url.png" alt-text="Screenshot shows the ngrok HTTPS URL.":::

Add web authentication

In the left pane, under Manage, select Authentication.
Select Add a platform > Web.

:::image type="content" source="../assets/images/include-files/platform-web.png" alt-text="Screenshot shows the selection of web authentication.":::
Enter the redirect URI for your app by appending auth-end to the fully qualified domain name. For example, https://your-devtunnel-domain/auth-end or https://your-ngrok-domain/auth-end.
Under Implicit grant and hybrid flows, select the Access tokens and ID tokens checkboxes.
Select Configure.

:::image type="content" source="../assets/images/include-files/configure-web.png" alt-text="Screenshot shows the option to add redirect URI and select implicit grant and hybrid flows.":::
Under Web, select Add URI.
Enter https://token.botframework.com/.auth/web/redirect.
Select Save.

:::image type="content" source="../assets/images/include-files/web-add-uri.png" alt-text="Screenshot shows the option to add the redirect URI and select implicit grant and hybrid flows.":::

Create a client secret

[!NOTE] If you encounter the error Client secrets are blocked by tenant-wide policy. Contact your tenant administrator for more information., you can create a certificate instead. For step-by-step instructions, refer to create a certificate for app registration.

In the left pane, under Manage, select Certificates & secrets.
Under Client secrets, select + New client secret.

:::image type="content" source="../assets/images/include-files/new-client-secret.png" alt-text="Screenshot show the selection of new client secret.":::

The Add a client secret window appears.
Enter Description.
Select Add.

:::image type="content" source="../assets/images/include-files/add-client-secret.png" alt-text="Screenshot show the client secret description option to add.":::
Under Value, select Copy to clipboard to save the client secret value for further use.

:::image type="content" source="../assets/images/include-files/client-secret-value.png" alt-text="Screenshot show the option to copy the client secret ID value to copy value to clipboard.":::

Add API permissions

In the left pane, select API permissions.
Select + Add a permission.

:::image type="content" source="../assets/images/teams-file-upload-bot/add-api-permission.png" alt-text="Screenshot shows the option to select Add permission.":::
Select Microsoft Graph.
Select Delegated permissions.
Select User > User.Read.
Select Add permissions.

:::image type="content" source="../assets/images/teams-file-upload-bot/select-api-permission.png" alt-text="Screenshot shows the option to select permissions.":::
[!NOTE]
- If an app isn't granted IT admin consent, users must provide consent the first time they use an app.
- Users need to consent to the API permissions only if the Microsoft Entra app is registered in a different tenant.

Add application ID URI

In the left pane, under Manage, select Expose an API.
Next to Application ID URI, select Add.

:::image type="content" source="../assets/images/bots/expose-api-add-uri.png" alt-text="Screenshot shows the option to add Application ID URI for your app.":::
Update the Application ID URI in the api://botid-{AppID} format and select Save.

:::image type="content" source="../assets/images/bots/app-id-uri1.png" alt-text="Screenshot shows the option to add the app ID URI and save.":::

Add a scope

In the left pane, under Manage, select Expose an API.
Select + Add a scope.

:::image type="content" source="../assets/images/include-files/select-add-scope.png" alt-text="Screenshot shows the selection to Add a Scope.":::
Enter access_as_user as the Scope name.
Under Who can consent?, select Admins and users.
Update the values for the rest of the fields as follows:
- Enter Teams can access the user’s profile as Admin consent display name.
- Enter Allows Teams to call the app’s web APIs as the current user as Admin consent description.
- Enter Teams can access the user profile and make requests on the user’s behalf as User consent display name.
- Enter Enable Teams to call this app’s APIs with the same rights as the user as User consent description.
Ensure that State is set to Enabled.
Select Add scope.

The following image shows the fields and the values:

:::image type="content" source="../assets/images/include-files/set-add-scope.png" alt-text="Screenshot shows the values filled in the field to Add a scope.":::

[!NOTE] The Scope name must match with the Application ID URI with /access_as_user appended at the end.

:::image type="content" source="../assets/images/include-files/add-scope.png" alt-text="Screenshot shows the details in Scopes.":::

Add client application

In the left pane, under Manage, select Expose an API.

Under Authorized client applications, identify the applications that you want to authorize for your app’s web application.
Select + Add a client application.

:::image type="content" source="../assets/images/include-files/add-client-application.png" alt-text="Screenshot shows the option to Select client application.":::
Add Teams mobile or desktop and Teams web application.
1. For Teams mobile or desktop: Enter the Client ID as 1fec8e78-bce4-4aaf-ab1b-5451cc387264.
  
  :::image type="content" source="../assets/images/include-files/client-id-mobile-desktop.png" alt-text="Screenshot shows the mobile or desktop Client ID application.":::
2. For Teams web: Enter the Client ID as 5e3ce6c0-2b1f-4285-8d4b-75ee78787346.
  
  :::image type="content" source="../assets/images/include-files/client-id-web.png" alt-text="Screenshot shows the web Client ID application.":::
Select the Authorized scopes checkbox.
Select Add application.

:::image type="content" source="../assets/images/include-files/authorized-scope-add.png" alt-text="Screenshot shows the option to select authorized scopes and add application.":::

The following image displays the Client Id:

:::image type="content" source="../assets/images/include-files/add-client-application-output.png" alt-text="Screenshot shows the output of Client applications.":::

Create your bot

Create an Azure bot resource

[!NOTE] If you're already testing your bot in Teams, sign out of this app and Teams. To see this change, sign in again.

Go to Home.
Select + Create a resource.
In the search box, enter Azure Bot.
Select Enter.
Select Azure Bot.
Select Create.

:::image type="content" source="../assets/images/include-files/azure-bot.png" alt-text="Screenshot shows the creation of Azure bot.":::
Enter the bot name in Bot handle.
Select your Subscription from the dropdown list.
Select your Resource group from the dropdown list.

:::image type="content" source="../assets/images/include-files/create-azure-bot.png" alt-text="Screenshot shows the option resource group and subscription in the Azure portal.":::

If you don't have an existing resource group, you can create a new resource group. To create a new resource group, follow these steps:
1. Select Create new.
2. Enter the resource name and select OK.
3. Select a location from New resource group location dropdown list.
:::image type="content" source="../assets/images/include-files/new-resource-location.png" alt-text="Screenshot shows the new resource group option in Azure portal.":::
Under Pricing, select Change plan.

:::image type="content" source="../assets/images/include-files/pricing-tier.png" alt-text="Screenshot shows the pricing option in Azure portal.":::
Select FO Free > Select.

:::image type="content" source="../assets/images/include-files/pricing-free.png" alt-text="Screenshot shows the option to select free.":::
Under Microsoft App ID, select Type of App as Multi Tenant.
In the Creation type, select Use existing app registration.
Enter the App ID.

[!NOTE] You can't create more than one bot with the same Microsoft App ID.
Select Review + create.

:::image type="content" source="../assets/images/include-files/review-create-app-id.png" alt-text="Screenshot shows the creation of new bot.":::
After the validation passes, select Create.

The bot takes a few minutes to provision.
Select Go to resource.

:::image type="content" source="../assets/images/include-files/resource-deployment.png" alt-text="Screenshot shows the Go to resource option in the Azure portal.":::

You've successfully created your Azure bot.

:::image type="content" source="../assets/images/include-files/azure-bot-created-output.png" alt-text="Screenshot shows the output of a bot.":::

Add a Teams channel

In the left pane, select Channels.
Under Available Channels, select Microsoft Teams.

:::image type="content" source="../assets/images/include-files/channels-teams.png" alt-text="Screenshot shows the selection of Teams in channels.":::
Select the checkbox to accept the Terms of Service.
Select Agree.

:::image type="content" source="../assets/images/include-files/terms-service.png" alt-text="Screenshot shows the acceptance of terms of service.":::
Select Apply.

:::image type="content" source="../assets/images/include-files/teams-apply.png" alt-text="Screenshot shows the Microsoft Teams as messaging to apply.":::

Add a messaging endpoint

Use one of the following ways to add a messaging endpoint:

dev tunnel

Use the dev tunnel URL in the Output console as the messaging endpoint.

:::image type="content" source="../assets/images/include-files/output-console-url.png" alt-text="Screenshot shows the url in the Visual studio output console.":::
In the left pane, under Settings, select Configuration.
Update the Messaging endpoint in the format https://your-devtunnel-domain/api/messages.

:::image type="content" source="../assets/images/include-files/devtunnels-messaging-endpoint.png" alt-text="Screenshot shows the messaging endpoint adding api.":::
Select Apply.

You've successfully set up a bot in Azure Bot service.

[!NOTE] If the Application Insights Instrumentation key shows an error, update with App ID.

ngrok

From ngrok, copy the HTTPS URL.

:::image type="content" source="../assets/images/include-files/ngrok-url.png" alt-text="Screenshot shows the ngrok HTTPS URL.":::

[!NOTE] The HTTPS URL in your ngrok is a fully qualified domain name. The WebAppDomain is a fully qualified domain name that doesn't include https:// in it.
In the left pane, under Settings, select Configuration.
Update the Messaging endpoint in the format https://your-ngrok-domain/api/messages.

:::image type="content" source="../assets/images/include-files/ngrok-messaging-endpoint.png" alt-text="Screenshot shows the messaging endpoint adding api.":::
Select Apply.

You have successfully set up a bot in Azure Bot service.

[!NOTE] If the Application Insights Instrumentation key shows an error update with App ID.

Set up app settings and manifest files

Go to the appsettings.json file in the cloned repository.

:::image type="content" source="~/assets/images/teams-file-upload-bot/appsettings-file-location-bot-sso.png" alt-text="Screenshot shows the location of appsettings json file.":::
Open the appsettings.json file and update the following information:
- Set "MicrosoftAppId" to your bot's Microsoft App ID.
- Set "MicrosoftAppPassword" to your bot's client secret ID value.
- Set ConnectionName as OAuth connection name.
- Set "MicrosoftAppType" to MultiTenant.
- Set "MicrosoftAppTenantId" to common.
:::image type="content" source="~/assets/images/teams-file-upload-bot/appsettings-json-bot-sso.png" alt-text="Screenshot shows the appsettings json.":::
Go to the manifest.json file in the cloned repository.

:::image type="content" source="../assets/images/teams-file-upload-bot/manifest-file-location.png" alt-text="Screenshot shows the selection of manifest json file.":::
Open the manifest.json file and update the following changes:
- Replace all occurrences of "{TODO: MicrosoftAppId}" with your Microsoft App ID.
- Set "<<domain-name>>" to your ngrok or dev tunnel domain.
:::image type="content" source="../assets/images/teams-file-upload-bot/manifest-bot-id-botsso.png" alt-text="Screenshot shows the details filled in the manifest file in visual studio.":::

Build and run the service

To build and run the service, use Visual Studio or Command line.

Visual Studio

Open Visual Studio.
Go to File > Open > Project/Solution.....

:::image type="content" source="../assets/images/sbs-messagingextension-action/VSopenfile.png" alt-text="Screenshot of Visual Studio with the Project/Solution highlighted in red.":::
From csharp folder, select the TeamsMessagingExtensionsAction.csproj file.

:::image type="content" source="../assets/images/sbs-messagingextension-action/openproject.png" alt-text="Screenshot of cloned repository with the TeamsMessagingExtensionsAction.csproj highlighted in red.":::
Press F5 to run the project.
Select Yes if the following dialog appears:

:::image type="content" source="../assets/images/sbs-messagingextension-action/certificate.png" alt-text="Screenshot shows Security Warning with the Yes option highlighted in red.":::

A webpage appears with a message Your bot is ready!.

:::image type="content" source="../assets/images/sbs-messagingextension-action/appisready.png" alt-text="Screenshot of the webpage that displays Your bot is ready!.":::

Command line

Go to samples > msgext-action > csharp in Command Prompt window and enter the following command:

    dotnet run

:::image type="content" source="../assets/images/sbs-messagingextension-action/dotnetruncmd.png" alt-text="Screenshot of Command Prompt - dotnet run with the dotnet run command.":::

Add Action Message Extension app to Teams

In your cloned repository, go to samples > msgext-action > csharp > TeamsAppManifest.
Create a .zip with the following files that are present in the Manifest folder:
- manifest.json
- icon-outline.png
- icon-color.png
:::image type="content" source="../assets/images/sbs-messagingextension-action/zipfile.png" alt-text="Screenshot of cloned repository with the Messaging extension zip file highlighted in red.":::
In the Teams client, select the Apps icon.
Select Manage your apps.
Select Upload an app.
Look for the option to Upload a custom app. If you see the option, custom app upload is enabled.

:::image type="content" source="../assets/images/tab-device-permission/custom-upload.png" alt-text="Screenshot shows the upload a custom app.":::

[!NOTE] Contact your Teams administrator, if you don't find the option to upload a custom app.
Select Open to upload the messaging.zip file that you created in the TeamsAppManifest folder.

:::image type="content" source="../assets/images/sbs-messagingextension-action/openzipfile.png" alt-text="Screenshot of the cloned repository displaying the messaging zip file.":::
Select Add.

:::image type="content" source="../assets/images/sbs-messagingextension-action/add-app.png" alt-text="Screenshot of the app details dialog to add the message extension app.":::
Select Open to open the app in personal scope.

Alternatively, you can either search and select the required scope or select a channel, chat, or meeting from the list, and move through the dialog to select Go.

:::image type="content" source="../assets/images/sbs-messagingextension-action/add-scope.png" alt-text="Screenshot of the scope selection dialog to select the required scope.":::

Interact with the app in Teams

Select Create Card command from the compose box command list.

:::image type="content" source="../assets/images/sbs-messagingextension-action/create-card.png" alt-text="Screenshot of message compose box overflow menu with Create Card highlighted in red.":::
Enter your information in the modal pop-up window.

:::image type="content" source="../assets/images/sbs-messagingextension-action/output-card.png" alt-text="The Screenshot shows the Create Card model pop-up of the Action Messaging Extension.":::
Select Submit.

:::image type="content" source="../assets/images/sbs-messagingextension-action/submit.png" alt-text="Screenshot of Create Card model pop-up with the Submit option highlighted in red.":::
Select More options (...) from the overflow menu.
Select More actions > Share Message.

:::image type="content" source="../assets/images/sbs-messagingextension-action/sharemessage.png" alt-text="Screenshot shows the message overflow menu. The Share Message and More actions are highlighted in red.":::
If you want to include an image, select the Include image in Hero Card checkbox and then select Submit.

:::image type="content" source="../assets/images/sbs-messagingextension-action/sharemessageoutput.png" alt-text="Screenshot of Action Messaging Extension with the include image in Hero Card checkbox and Submit option highlighted in red.":::

Complete challenge

Did you come up with something like this?

You've completed the tutorial to get started with a Action Message Extension app!

[!div class="nextstepaction"] Action commands

Build a bot with SSO authentication

Conversational bots in Microsoft Teams perform repetitive automated tasks initiated by users, such as customer service. The user needs to sign in multiple times without single sign-on (SSO) authentication. With SSO authentication methods, the users don't need to sign in to the bot multiple times.

Tutorial: Build a bot with SSO authentication

A bot behaves differently depending on the conversation it's involved in:

Bots in channel and group chat conversations require the users to @mention the bot.
Bots in a one-to-one conversation don't require an @mention. All messages sent by the user routes to the bot.

This step-by-step guide helps you to build a bot with SSO authentication. You'll see the following output:

:::image type="content" source="~/assets/images/bots/sbs-desktop-mobile.png" alt-text=" Screenshot of the bot with SSO authentication output after you’ve successfully completed the step-by-step guide.":::

Prerequisites for building a bot

Ensure that you install the following tools and set up your development environment:

Install	For using...
Microsoft Teams	Microsoft Teams to collaborate with everyone you work with through apps for chat, meetings, and calls all in one place.
Visual Studio 2022	You can install the enterprise version in Visual Studio 2022, and install the ASP.NET and web development workloads. Use the latest version.
Microsoft 365 developer account	Access to Teams account with the appropriate permissions to install an app.
Dev tunnel	Teams app features (conversational bots, message extensions, and incoming webhooks) need inbound connections. A tunnel connects your development system to Teams. Dev tunnel is a powerful tool to securely open your localhost to the internet and control who has access. Dev tunnel is available in Visual Studio 2022 version 17.7.0 or later. or You can also use ngrok as a tunnel to connect your development system to Teams. It isn't required for apps that only include tabs. This package is installed within the project directory (using npm `devDependencies`).

[!NOTE] After downloading ngrok, sign up, and install authtoken.

Set up the Teams development tenant

A tenant is like a space or a container where you chat, share files, and run meetings for your organization in Teams. You can also upload and test the custom app.

Check for a custom app upload option

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

[!NOTE] Custom app upload is necessary for previewing and testing apps in Teams local environment. Enable app upload to preview and test your app in Teams locally.

Do you already have a tenant, and do you have the admin access? Let's check if you really do!

To verify custom upload apps in Teams:

In the Teams client, select the Apps icon.
Select Manage your apps.
Select Upload an app
Look for the option Upload a custom app. If you see the option, custom app upload is enabled.

:::image type="content" source="../assets/images/bots/upload-a-custom-app-sso-bot-authentication.png" alt-text="Screenshot showing the Teams apps, Manage your apps, Upload an app, and Upload a custom app highlighted in red.":::

[!NOTE] Contact Teams administrator, if you don't have the option to upload a custom app.

Create a free Teams developer tenant

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

Go to the Microsoft 365 developer program.
Select Join Now and follow the onscreen instructions.
In the welcome screen, select Setup E5 subscription.
Set up an administrator account. After you finish, the following screen displays.

:::image type="content" source="../assets/images/toolkit-v2/prerequisites/microsoft-365.png" alt-text="Screenshot of the Microsoft 365 Developer Program subscription.":::
Sign in to Teams using the new administrator account you just set up. Verify that you have the Upload a custom app option in Teams.

Set up local environment

Follow these steps to clone the repository:

Open Microsoft-Teams-Samples.
Select Code.
From the dropdown menu, select Open with GitHub Desktop.

:::image type="content" source="../assets/images/include-files/clone-repository.png" alt-text="Screenshot show the option to clone repository in local.":::
Select Clone.

Register Microsoft Entra app

The following steps help you to create and register your bot in the Azure portal:

Create and register your Azure app.
Create client secret to enable SSO authentication of the bot.
Add Teams channel to deploy the bot.
Create a tunnel to your web server's endpoints using dev tunnel (recommended) or ngrok.
Add messaging endpoint to the dev tunnel that you created.

Add App registration

Go to Azure portal.
Select App registrations.

:::image type="content" source="../assets/images/include-files/azure-app-registration.png" alt-text="Screenshot shows the Azure services to select App registrations.":::
Select + New registration.

:::image type="content" source="../assets/images/include-files/new-registration.png" alt-text="Screenshot shows the New registration page on Microsoft Entra admin center.":::
Enter the name of your app.
Select the tenant option, as required.
Select Register.

:::image type="content" source="../assets/images/include-files/app-register.png" alt-text="Screenshot shows the option to register the bot in Microsoft Entra admin center.":::

Your app is registered in Microsoft Entra ID. The app overview page appears.

:::image type="content" source="../assets/images/include-files/app-registration-overview.png" alt-text="Screenshot shows the app registration overview page.":::

[!NOTE] Save the app ID from Application (client) ID and Directory (tenant) ID for further use.

Create a tunnel

Follow one of the following two methods to create a tunnel.

dev tunnel

Open Visual Studio.
Select Create a new project.

:::image type="content" source="../assets/images/include-files/create-new-project.png" alt-text="Screenshot shows the selection to create a new project.":::
In the search box, enter ASP.NET. From the search results, select ASP.NET Core Web App.
Select Next.

:::image type="content" source="../assets/images/include-files/template-search.png" alt-text="Screenshot shows the search and selection of the template.":::
Enter Project name and select Next.

:::image type="content" source="../assets/images/include-files/project-name.png" alt-text="Screenshot shows the project name to enter.":::
Select Create.

:::image type="content" source="../assets/images/include-files/additional-information.png" alt-text="Screenshot shows the project additional information." lightbox="../assets/images/include-files/additional-information.png":::

An overview window appears.

:::image type="content" source="../assets/images/include-files/asp-net-output.png" alt-text="Screenshot shows the overview window.":::
In the debug dropdown list, select Dev Tunnels (no active tunnel) > Create a Tunnel....

:::image type="content" source="../assets/images/include-files/create-tunnel.png" alt-text="Screenshot shows the dropdown to select the dev tunnels.":::

A pop-up window appears.
Update the following details in the pop-up window:
1. Account: Enter a Microsoft or GitHub account.
2. Name: Enter a name for your tunnel.
3. Tunnel Type: From the dropdown list, select Temporary.
4. Access: From the dropdown list, select Public.
Select OK.

:::image type="content" source="../assets/images/include-files/create-tunnel-details.png" alt-text="Screenshot shows the details to update for creation of tunnel.":::

A pop-up window appears showing that dev tunnel is successfully created.
Select OK.

:::image type="content" source="../assets/images/include-files/tunnel-created.png" alt-text="Screenshot shows the pop-up message that the tunnel is created.":::

You can find the tunnel you've created in the debug dropdown list as follows:

:::image type="content" source="../assets/images/include-files/tunnel-active.png" alt-text="Screenshot shows the tunnel is active and selected.":::
Select F5 to run the application in the debug mode.
If a Security Warning dialog appears, select Yes.

:::image type="content" source="../assets/images/include-files/security-warning.png" alt-text="Screenshot shows the dialog box to accept the security warning.":::

A pop-up window appears.
Select Continue.

:::image type="content" source="../assets/images/include-files/developer-tunnel.png" alt-text="Screenshot shows the url for the tunnel.":::

The dev tunnel home page opens in a new browser window and the dev tunnel is now active.

:::image type="content" source="../assets/images/include-files/developer-tunnel-web.png" alt-text="Screenshot shows the dev tunnel welcome page in browser.":::
Go to Visual Studio, select View > Output.
From the Output console dropdown menu, select Dev Tunnels.

The Output console shows the dev tunnel URL.

:::image type="content" source="../assets/images/include-files/output-console-url.png" alt-text="Screenshot shows the url in the Visual Studio output console.":::

ngrok

Use ngrok or Command Prompt to create a tunnel to your locally running web server's publicly available HTTPS endpoints. Run the following command in ngrok:

ngrok http --host-header=localhost 3978

[!TIP] If you encounter ERR_NGROK_4018, follow the steps provided in the Command Prompt to sign up and authenticate ngrok. Then run the ngrok http --host-header=localhost 3978 command.

The window shows the HTTPS URL.

:::image type="content" source="../assets/images/include-files/ngrok-url.png" alt-text="Screenshot shows the ngrok HTTPS URL.":::

Add web authentication

In the left pane, under Manage, select Authentication.
Select Add a platform > Web.

:::image type="content" source="../assets/images/include-files/platform-web.png" alt-text="Screenshot shows the selection of web authentication.":::
Enter the redirect URI for your app by appending auth-end to the fully qualified domain name. For example, https://your-devtunnel-domain/auth-end or https://your-ngrok-domain/auth-end.
Under Implicit grant and hybrid flows, select the Access tokens and ID tokens checkboxes.
Select Configure.

:::image type="content" source="../assets/images/include-files/configure-web.png" alt-text="Screenshot shows the option to add redirect URI and select implicit grant and hybrid flows.":::
Under Web, select Add URI.
Enter https://token.botframework.com/.auth/web/redirect.
Select Save.

:::image type="content" source="../assets/images/include-files/web-add-uri.png" alt-text="Screenshot shows the option to add the redirect URI and select implicit grant and hybrid flows.":::

Create a client secret

[!NOTE] If you encounter the error Client secrets are blocked by tenant-wide policy. Contact your tenant administrator for more information., you can create a certificate instead. For step-by-step instructions, refer to create a certificate for app registration.

In the left pane, under Manage, select Certificates & secrets.
Under Client secrets, select + New client secret.

:::image type="content" source="../assets/images/include-files/new-client-secret.png" alt-text="Screenshot show the selection of new client secret.":::

The Add a client secret window appears.
Enter Description.
Select Add.

:::image type="content" source="../assets/images/include-files/add-client-secret.png" alt-text="Screenshot show the client secret description option to add.":::
Under Value, select Copy to clipboard to save the client secret value for further use.

:::image type="content" source="../assets/images/include-files/client-secret-value.png" alt-text="Screenshot show the option to copy the client secret ID value to copy value to clipboard.":::

Add API permissions

In the left pane, select API permissions.
Select + Add a permission.

:::image type="content" source="../assets/images/teams-file-upload-bot/add-api-permission.png" alt-text="Screenshot shows the option to select Add permission.":::
Select Microsoft Graph.
Select Delegated permissions.
Select User > User.Read.
Select Add permissions.

:::image type="content" source="../assets/images/teams-file-upload-bot/select-api-permission.png" alt-text="Screenshot shows the option to select permissions.":::
[!NOTE]
- If an app isn't granted IT admin consent, users must provide consent the first time they use an app.
- Users need to consent to the API permissions only if the Microsoft Entra app is registered in a different tenant.

Add application ID URI

In the left pane, under Manage, select Expose an API.
Next to Application ID URI, select Add.

:::image type="content" source="../assets/images/bots/expose-api-add-uri.png" alt-text="Screenshot shows the option to add Application ID URI for your app.":::
Update the Application ID URI in the api://botid-{AppID} format and select Save.

:::image type="content" source="../assets/images/bots/app-id-uri1.png" alt-text="Screenshot shows the option to add the app ID URI and save.":::

Add a scope

In the left pane, under Manage, select Expose an API.
Select + Add a scope.

:::image type="content" source="../assets/images/include-files/select-add-scope.png" alt-text="Screenshot shows the selection to Add a Scope.":::
Enter access_as_user as the Scope name.
Under Who can consent?, select Admins and users.
Update the values for the rest of the fields as follows:
1. Enter Teams can access the user’s profile as Admin consent display name.
2. Enter Allows Teams to call the app’s web APIs as the current user as Admin consent description.
3. Enter Teams can access the user profile and make requests on the user’s behalf as User consent display name.
4. Enter Enable Teams to call this app’s APIs with the same rights as the user as User consent description.
Ensure that State is set to Enabled.
Select Add scope.

The following image shows the fields and the values:

:::image type="content" source="../assets/images/include-files/set-add-scope.png" alt-text="Screenshot shows the values filled in the field to Add a scope.":::

[!NOTE] The Scope name must match with the Application ID URI with /access_as_user appended at the end.

:::image type="content" source="../assets/images/include-files/add-scope.png" alt-text="Screenshot shows the details in Scopes.":::

Add client application

In the left pane, under Manage, select Expose an API.

Under Authorized client applications, identify the applications that you want to authorize for your app’s web application.
Select + Add a client application.

:::image type="content" source="../assets/images/include-files/add-client-application.png" alt-text="Screenshot shows the option to Select client application.":::
Add Teams mobile or desktop and Teams web application.
1. For Teams mobile or desktop: Enter the Client ID as 1fec8e78-bce4-4aaf-ab1b-5451cc387264.
  
  :::image type="content" source="../assets/images/include-files/client-id-mobile-desktop.png" alt-text="Screenshot shows the mobile or desktop Client ID application.":::
2. For Teams web: Enter the Client ID as 5e3ce6c0-2b1f-4285-8d4b-75ee78787346.
  
  :::image type="content" source="../assets/images/include-files/client-id-web.png" alt-text="Screenshot shows the web Client ID application.":::
Select the Authorized scopes checkbox.
Select Add application.

:::image type="content" source="../assets/images/include-files/authorized-scope-add.png" alt-text="Screenshot shows the option to select authorized scopes and add application.":::

The following image displays the Client Id:

:::image type="content" source="../assets/images/include-files/add-client-application-output.png" alt-text="Screenshot shows the output of Client applications.":::

Update the manifest

In the left pane, select Manifest.
Set the value for the requestedAccessTokenVersion to 2 and select Save.

:::image type="content" source="../assets/images/include-files/manifest-token.png" alt-text="Screenshot shows the manifest option and accesstoken details in Azure portal.":::

Create your bot

Create an Azure bot resource

[!NOTE] If you're already testing your bot in Teams, sign out of this app and Teams. To see this change, sign in again.

Go to Home.
Select + Create a resource.
In the search box, enter Azure Bot.
Select Enter.
Select Azure Bot.
Select Create.

:::image type="content" source="../assets/images/include-files/azure-bot.png" alt-text="Screenshot shows the creation of Azure bot.":::
Enter the bot name in Bot handle.
Select your Subscription from the dropdown list.
Select your Resource group from the dropdown list.

:::image type="content" source="../assets/images/include-files/create-azure-bot.png" alt-text="Screenshot shows the option resource group and subscription in the Azure portal.":::

If you don't have an existing resource group, you can create a new resource group. To create a new resource group, follow these steps:
1. Select Create new.
2. Enter the resource name and select OK.
3. Select a location from New resource group location dropdown list.
:::image type="content" source="../assets/images/include-files/new-resource-location.png" alt-text="Screenshot shows the new resource group option in Azure portal.":::
Under Pricing, select Change plan.

:::image type="content" source="../assets/images/include-files/pricing-tier.png" alt-text="Screenshot shows the pricing option in Azure portal.":::
Select FO Free > Select.

:::image type="content" source="../assets/images/include-files/pricing-free.png" alt-text="Screenshot shows the option to select free.":::
Under Microsoft App ID, select Type of App as Multi Tenant.
In the Creation type, select Use existing app registration.
Enter the App ID.

[!NOTE] You can't create more than one bot with the same Microsoft App ID.
Select Review + create.

:::image type="content" source="../assets/images/include-files/review-create-app-id.png" alt-text="Screenshot shows the creation of new bot.":::
After the validation passes, select Create.

The bot takes a few minutes to provision.
Select Go to resource.

:::image type="content" source="../assets/images/include-files/resource-deployment.png" alt-text="Screenshot shows the Go to resource option in the Azure portal.":::

You've successfully created your Azure bot.

:::image type="content" source="../assets/images/include-files/azure-bot-created-output.png" alt-text="Screenshot shows the output of a bot.":::

Add a Teams channel

In the left pane, select Channels.
Under Available Channels, select Microsoft Teams.

:::image type="content" source="../assets/images/include-files/channels-teams.png" alt-text="Screenshot shows the selection of Teams in channels.":::
Select the checkbox to accept the Terms of Service.
Select Agree.

:::image type="content" source="../assets/images/include-files/terms-service.png" alt-text="Screenshot shows the acceptance of terms of service.":::
Select Apply.

:::image type="content" source="../assets/images/include-files/teams-apply.png" alt-text="Screenshot shows the Microsoft Teams as messaging to apply.":::

Add a messaging endpoint

Use one of the following ways to add a messaging endpoint:

dev tunnel

Use the dev tunnel URL in the Output console as the messaging endpoint.

:::image type="content" source="../assets/images/include-files/output-console-url.png" alt-text="Screenshot shows the url in the Visual studio output console.":::
In the left pane, under Settings, select Configuration.
Update the Messaging endpoint in the format https://your-devtunnel-domain/api/messages.

:::image type="content" source="../assets/images/include-files/devtunnels-messaging-endpoint.png" alt-text="Screenshot shows the messaging endpoint adding API.":::
Select Apply.

You've successfully set up a bot in Azure Bot service.

[!NOTE] If the Application Insights Instrumentation key shows an error, update with App ID.

ngrok

From ngrok, copy the HTTPS URL.

:::image type="content" source="../assets/images/include-files/ngrok-url.png" alt-text="Screenshot shows the ngrok HTTPS URL.":::

[!NOTE] The HTTPS URL in your ngrok is a fully qualified domain name. The WebAppDomain is a fully qualified domain name that doesn't include https:// in it.
In the left pane, under Settings, select Configuration.
Update the Messaging endpoint in the format https://your-ngrok-domain/api/messages.

:::image type="content" source="../assets/images/include-files/ngrok-messaging-endpoint.png" alt-text="Screenshot shows the messaging endpoint adding API.":::
Select Apply.

You have successfully set up a bot in Azure Bot service.

[!NOTE] If the Application Insights Instrumentation key shows an error update with App ID.

Add an OAuth connection settings

In the left pane, select Configuration.
Select Add OAuth Connection Settings.
Under New Connection Setting, update the following details:
- Name: Enter a name for your new connection setting. You can use the name in the settings of your bot service code.
- Service Provider: From the dropdown list, select Azure Active Directory v2.
- Client id: Update your Microsoft App ID.
- Client secret: Update the client secrets Value.
- Token Exchange URL: Update the Application ID URI.
- Tenant ID: Enter Common.
- Scopes: Enter User.Read.
Select Save.

:::image type="content" source="../assets/images/include-files/new-connection-setting.png" alt-text="Screenshot shows the values added to set OAuth connection.":::

Set up app settings and manifest files

Go to the appsettings.json file in the cloned repository.

:::image type="content" source="~/assets/images/teams-file-upload-bot/appsettings-file-location-bot-sso.png" alt-text="Screenshot shows the location of appsettings json file.":::
Open the appsettings.json file and update the following information:
- Set "MicrosoftAppId" to your bot's Microsoft App ID.
- Set "MicrosoftAppPassword" to your bot's client secret ID value.
- Set ConnectionName as OAuth connection name.
- Set "MicrosoftAppType" to MultiTenant.
- Set "MicrosoftAppTenantId" to common.
:::image type="content" source="~/assets/images/teams-file-upload-bot/appsettings-json-bot-sso.png" alt-text="Screenshot shows the appsettings json.":::
Go to the manifest.json file in the cloned repository.

:::image type="content" source="../assets/images/teams-file-upload-bot/manifest-file-location.png" alt-text="Screenshot shows the selection of manifest json file.":::
Open the manifest.json file and update the following changes:
- Replace all occurrences of "{TODO: MicrosoftAppId}" with your Microsoft App ID.
- Set "<<domain-name>>" to your ngrok or dev tunnel domain.
:::image type="content" source="../assets/images/teams-file-upload-bot/manifest-bot-id-botsso.png" alt-text="Screenshot shows the details filled in the manifest file in visual studio.":::

Build and run the service

Open Visual Studio.
Go to File > Open > Project/Solution....

:::image type="content" source="../assets/images/bots/project-solution_1.png" alt-text="The screenshot of Visual Studio file menu. The menu entries titled Open under File menu and Project/Solution under Open are highlighted in red.":::
From bot-conversation-sso-quickstart > csharp_dotnetcore folder, and select BotConversationSsoQuickstart.sln file.

:::image type="content" source="../assets/images/bots/filepath_1.png" alt-text="Screenshot of Project file with the file path and BotSSOCSharp.csproj file highlighted in red.":::
Select F5 to run the project.
If a Security Warning dialog appears, select Yes.

:::image type="content" source="../assets/images/bots/certificate.png" alt-text="The screenshot of Security Warning with the Yes option highlighted in red.":::

A webpage opens with a message Your bot is ready!.

[!NOTE] This page appears only when you navigate to the localhost URL.

:::image type="content" source="../assets/images/bots/yourbot.png" alt-text="The screenshot of the webpage that displays Your bot is ready.":::
Troubleshooting

If you get the Unable to find package error, follow these steps:
1. Go to Tools > NuGet Package Manager > Package Manager Settings.
2. In the Options window that appears, select NuGet Package Manager > Package Sources.
3. Select Add.
4. In Name, enter nuget.org and in Source, enter https://api.nuget.org/v3/index.json.
5. Select Update and OK.
6. Rebuild your project.

Upload the bot in Teams

In your cloned repository, go to Microsoft-Teams-Samples > samples > bot-conversation-sso-quickstart > csharp_dotnetcore > TeamsApp > appPackage.
Create a .zip file with the following files that are present in the appPackage folder:
- manifest.json
- outline.png
- color.png
:::image type="content" source="../assets/images/bots/manifest_1.png" alt-text="Screenshot of Manifest folder with the Teams Bot zip folder highlighted in red.":::
Go to Microsoft Teams.
1. In the Teams client, select Apps.
2. Select Manage your apps.
3. Select Upload an app.
4. Look for the option to Upload a custom app.
:::image type="content" source="../assets/images/bots/custom-app-upload.png" alt-text="Screenshot of Teams app with the Apps icon, Manage your apps, and showing the selection of Upload a custom app option highlighted in red.":::
Select Open to upload the .zip file that you've created in the Manifest folder.

:::image type="content" source="../assets/images/bots/app-open.png" alt-text="The screenshot of Manifest folder with Open option to upload the Teams Bot zip file highlighted in red.":::
Select Add to add the bot to your chat.

:::image type="content" source="../assets/images/bots/conversation-bot-add.png" alt-text="Screenshot of conversation bot with Add option highlighted.":::
Select Open.

:::image type="content" source="../assets/images/bots/conversation-bot-open.png" alt-text="The screenshot of scope selection dialog with Open option highlighted.":::

You can interact with the bot by sending it a message. The bot exchanges an SSO token and calls the Graph API on your behalf. It keeps you signed in unless you send a message to sign out.
Send a message to the bot. The conversation bot asks for consent for the first time.
For desktop: Select Continue to give permissions to Teams client for accessing the bot.

:::image type="content" source="../assets/images/bots/sbsdesktop-mobile-consent-request1.png" alt-text="Screenshot of additional permissions with Continue option highlighted in red.":::

[!NOTE] Now you’ve configured SSO with your bot app and it's the only time you'll have to give consent.
For mobile: Select Accept.

[!NOTE] Now you’ve configured SSO with your bot app in mobile, and it's the only time you'll have to give consent.

:::image type="content" source="../assets/images/bots/sbsdesktop-mobile-consent-request.png" alt-text="Screenshot of bot SSO output after you successfully completed the step-by-step guide.":::

Did you come up with something like this?

:::image type="content" source="../assets/images/bots/sbs-desktop-mobile.png" alt-text="Screenshot of the output after you successfully completed the step-by-step guide.":::

You've completed the tutorial to get started with build a bot with SSO authentication.

[!div class="nextstepaction"] Enable SSO for your bot

Build your first message extension app using JavaScript

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.

Tutorial: Build your first message extension app using JavaScript

This step-by-step guide helps you to build a message extension Teams app with Agents Toolkit in Visual Studio Code. You'll see the following output after you complete this guide:

:::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":::

Prerequisites

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

	Install	For using...
Required
	Visual Studio Code	JavaScript or TypeScript build environments. Use the latest version.
	Microsoft 365 Agents Toolkit	Microsoft Visual Studio Code extension that creates a project scaffolding for your app. Use the latest version.
	Node.js	Backend JavaScript runtime environment. For more information, see Node.js version compatibility table.
	Microsoft Teams	Collaborate with people you work with through apps for chats, meetings, and calls in one place.
	Microsoft Edge (recommended) or Google Chrome	A browser with developer tools essential for debugging and testing.
	Microsoft 365 developer account	Access to Teams account with appropriate permissions to install a custom app.
Optional
	Azure Tools for Visual Studio Code and Azure CLI	Azure tools to access stored data or to deploy a cloud-based backend for your Teams app in Azure.
	React Developer Tools for Chrome or React Developer Tools for Microsoft Edge	A browser DevTools extension for the open-source React JavaScript library.

Prepare development environment

After you install the required tools, set up the development environment.

Install Microsoft 365 Agents Toolkit

Microsoft 365 Agents Toolkit (previously known as 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 Agents Toolkit with Visual Studio Code or a command-line interface called Microsoft 365 Agents Toolkit CLI (previously known as TeamsFx CLI).

Visual Studio Code

Open Visual Studio Code and select Extensions (Ctrl+Shift+X or View > Extensions).
In the search box, enter Microsoft 365 Agents Toolkit.
Select Install.

:::image type="content" source="../assets/images/include-files/install-toolkit-vs.png" alt-text="Screenshot shows the Agents Toolkit extension installation.":::

The Microsoft 365 Agents Toolkit :::image type="icon" source="../assets/images/include-files/toolkit-sidebar-icon.PNG"::: icon appears in the Visual Studio Code Activity Bar.

You can also install Agents Toolkit from the Visual Studio Code Marketplace.

Command Line

To install Agents Toolkit CLI, use the npm package manager and enter the following command in Command prompt:

npm install -g @microsoft/m365agentstoolkit-cli

Depending on your configuration, you might need to use sudo to install the CLI:

sudo npm install -g --unsafe-perm @microsoft/m365agentstoolkit-cli

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

[!CAUTION] Before you can run TeamsFx in PowerShell terminals, you must enable the remote signed execution policy for PowerShell.

Set up your Teams development tenant

Check for upload an app option

After creating your custom app, you must upload your app to Teams with the Upload a custom app option. Sign in to your Microsoft 365 account to check if this option is enabled.

The following steps help you verify if you can upload apps in Teams:

In the Teams client, select the Apps icon.
Select Manage your apps.
Select Upload an app.
Look for the option to Upload a custom app. If the option is visible, you can upload custom apps.

:::image type="content" source="../assets/images/toolkit-v2/prerequisites/upload-custom-app.png" alt-text="Screenshot shows the option to upload a custom app in Teams." :::

[!NOTE] If you don't find the option to upload a custom app, contact your Teams administrator.

Create a free Teams developer tenant (optional)

If you don't have a Teams developer account, join the Microsoft 365 developer program.

Go to the Microsoft 365 developer program.
Select Join Now and follow the onscreen instructions.
In the welcome screen, select Set up E5 subscription.
Set up your administrator account. After you finish, the following screen appears:

:::image type="content" source="../assets/images/include-files/microsoft-365.png" alt-text="Screenshot shows the Microsoft 365 Developer Program.":::
Sign in to Teams using the administrator account you just set up. Verify that you have the Upload a custom app option in Teams.

Get a free Azure account

If you want to host your app or access resources in Azure, you must have an Azure subscription. Create a free account 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: You can search external systems and insert the 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 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:

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

Create your message extension project workspace

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

[!NOTE] The Visual Studio Code UI shown may differ for you depending on your operating system, Toolkit version, theme, and environment.

Visual Studio Code

Open Visual Studio Code.
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.
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.":::
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.":::
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.":::
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.":::
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.":::
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.":::
2. Select the location for project workspace.
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.":::
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="../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="../assets/images/toolkit-v2/preview-project-msg.png" alt-text="Screenshot shows a dialog saying that the message extension app is created.":::

Command Line

Use the `atk' CLI to create your first project.

Go to the folder where you want to create the project folder and open Command Prompt.
Enter the following command to create a new Teams app:
```
atk new
```
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.
2. Select Custom Search Results for App Features Using a Message Extension.
3. Select Start with a Bot for Architecture of Search Based Message Extension.
4. Select JavaScript for Programming Language.
5. Select Enter to select the default workspace folder for your app.
6. 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.

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

Visual Studio Code

Open Visual Studio Code.
Select the Microsoft 365 Agents Toolkit :::image type="icon" source="../assets/images/toolkit-v2/toolkit-sidebar-icon.png"::: icon in the activity bar.
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.":::
Close the browser after signing in using your credentials.
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!

Command Line

Go to the project folder of your message extension app and open Command Prompt.
Sign in to Microsoft 365 with Microsoft 365 Agents Toolkit CLI (previously known as TeamsFx CLI) command:
```
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.

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

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.
  2. Custom app upload is enabled for your Microsoft 365 account.
  3. Supported Node.js version is installed.
  4. 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.
Teams opens in a browser window when the build is complete. Sign in with your Microsoft 365 account, if prompted.
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":::

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":::

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.

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

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

Command Box

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

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

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

Select the three dots at the bottom of the message compose area.
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

Select Apps > Manage your apps.
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.":::
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.":::
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

Open Visual Studio Code.
Open the project folder in which you created the message extension app.
Select the Microsoft 365 Agents Toolkit :::image type="icon" source="../assets/images/toolkit-v2/toolkit-sidebar-icon.png"::: icon in the activity bar.
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.
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.

Command Line

Go to the project folder of your message extension app and open Command Prompt.
Sign in to Azure with Agents Toolkit CLI command:
```
atk account login azure
```
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.

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. You deploy the message extension app in this tutorial.

What's the difference between Provision and Deploy?

The Provision step creates resources in Azure and Microsoft 365 for your app, but no code (such as HTML, CSS, or JavaScript) is copied to the resources. The Deploy step copies the code for your app to the resources you created during the provision step. It's common to deploy multiple times without provisioning new resources. Since the provision step takes some time to complete, it's separate from the deployment step.

Visual Studio Code

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.

Select Provision.

:::image type="content" source="../assets/images/toolkit-v2/provisioning-commands.png" alt-text="Screenshot shows the selection of provision in the cloud under Agents toolkit.":::
Select a subscription.

:::image type="content" source="../assets/images/toolkit-v2/select-azure-subscription-group.png" alt-text="Screenshot shows the Azure subscription group options to choose from.":::
Select a resource group.

:::image type="content" source="../assets/images/toolkit-v2/deploy-azure/select-resource.png" alt-text="Screenshot shows the subscription to use for the Azure resources.":::

If you don't have a resource group to select, you can create a new resource group with the following steps:
1. Select + New resource group.
  
  :::image type="content" source="../assets/images/toolkit-v2/first-msgext/select-resource-new-resource.png" alt-text="Screenshot shows the option to create a new Azure resource group.":::
2. Select the default name or enter a suitable name for your resource group.
  
  :::image type="content" source="../assets/images/toolkit-v2/first-msgext/new-resource-group-name.png" alt-text="Screenshot shows the default name of the new Azure resource group.":::
3. Select the location for your resource group.
  
  :::image type="content" source="../assets/images/toolkit-v2/first-msgext/new-resource-group-location.png" alt-text="Screenshot shows the options for the location of the new Azure resource group.":::
A dialog box warns you that costs might be incurred when running resources in Azure. Select Provision.

:::image type="content" source="../assets/images/toolkit-v2/deploy-azure/provision-warning.png" alt-text="Screenshot shows a dialog box that warns the user that a cost might be incurred while provisioning Azure resources.":::

The provisioning process creates resources in the Azure cloud. It might take some time. After a few minutes, you see the following message:

:::image type="content" source="../assets/images/toolkit-v2/deploy-azure/deploy-provision-successmsgext.png" alt-text="Screenshot shows a notice that displays the message extension app successfully provisioned in the cloud.":::

If you want, you can view the provisioned resources. For this tutorial, you don't need to view resources.

The provisioned resource appears under ENVIRONMENT.

:::image type="content" source="../assets/images/toolkit-v2/deploy-azure/provisioned-resources-env.png" alt-text="Screenshot shows the resource being provisioned in the environment section.":::
Under LIFECYCLE, select Deploy.

:::image type="content" source="../assets/images/toolkit-v2/deploy-azure/deploy-cloud.png" alt-text="Screenshot shows the app deploys to the cloud.":::
A dialog box appears that asks you if you want to deploy resources in the dev environment. Select Deploy.

:::image type="content" source="../assets/images/toolkit-v2/deploy-azure/deploy-azure-confirm.png" alt-text="Screenshot shows the confirmation dialog box to deploy app in Azure.":::

As with provisioning, deployment takes some time. After a few minutes, you see a completion message.

Command Line

Go to the folder where you created your message extension app and open Command Prompt.
Run atk provision.
```
atk provision
```
When prompted, select an Azure subscription and resource group to use Azure resources. Your app is hosted using Azure resources.
Run atk deploy.
```
atk deploy
```
Your message extension app is deployed.

Run the deployed app

After the provisioning and deployment steps are complete, go to Run and Debug (Ctrl+Shift+D or View > Run) in Agents Toolkit.

Select the RUN AND DEBUG dropdown menu.
Select Launch Remote in Teams (Edge).
Select the ▷ button.

:::image type="content" source="../assets/images/toolkit-v2/deploy-azure/launch-remote.png" alt-text="Screenshot shows the launch app remotely in Teams option.":::
A dialog box opens to install your deployed app to Teams. Select Add.

:::image type="content" source="../assets/images/toolkit-v2/deploy-azure/mex-added-dev.png" alt-text="Screenshot shows message to add the deployed app.":::

Teams opens the message extension app in the most recent chat.

:::image type="content" source="../assets/images/toolkit-v2/first-msgext/mex-loaded-chat-app.png" alt-text="Screenshot shows the message extension open in a chat.":::

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?

[!div class="nextstepaction"] Build a message extension app

Build your first tab app using C sharp

Start Microsoft Teams app development by building your first Teams app with a tab capability.

In this tutorial, you'll learn:

How to set up a new project.
How to build apps with tab capability using C# and Microsoft Visual Studio 2022.

Tutorial: Build your first tab app using C#

This step-by-step guide helps you to build a tab with Microsoft 365 Agents Toolkit (previously known as Teams Toolkit). You'll see the following output after you've completed this guide:

:::image type="content" source="../assets/images/sbs-csharp/final-output.png" alt-text=" Screenshot shows the final output of the Teams tab app.":::

Prerequisites for building your app

Here's a list of tools you need to install for building and deploying a Teams app.

Install	For using...
Microsoft Teams	Microsoft Teams to collaborate with everyone you work with through apps for chat, meetings, and call all in one place.
Visual Studio 2022	You can install the enterprise version in Visual Studio 2022, and install the ASP.NET and web development workloads. Use the latest version.
Microsoft 365 Agents Toolkit	A Visual Studio extension that creates a project scaffolding for your app. Use the latest version.

Install Agents Toolkit

Agents Toolkit helps simplify the development process with tools to create a project scaffolding for your app. It creates the necessary directory structure for all selected capabilities with the required files in place, ready to build the project.

You can download the latest Visual Studio installer. Agents Toolkit is available as an extension in Visual Studio.

After you open the Visual Studio installer in the pop-up workloads window:

Select ASP.NET and web development.
Under installation details > Optional, select Microsoft Teams development tools.
Select Install.

:::image type="content" source="../assets/images/sbs-csharp/visual-studio-install.png" alt-text="Screenshot shows the Visual Studio installation." lightbox="~/assets/images/sbs-csharp/visual-studio-install.png":::
Select Launch. Visual Studio 2022 app window appears.

:::image type="content" source="../assets/images/sbs-csharp/visual-studio-launch.png" alt-text="Screenshot shows the selection of Launch in visual studio.":::
Go to Extensions > Manage Extensions.

:::image type="content" source="../assets/images/sbs-csharp/select-extension.png" alt-text="Screenshot shows the selection of Extensions.":::

The Manage Extension window appears:

:::image type="content" source="../assets/images/sbs-csharp/manage-ext.png" alt-text="Screenshot shows the Manage Extensions." lightbox="~/assets/images/sbs-csharp/manage-extension.png":::
From the left pane, select Installed. The Microsoft 365 Agents Toolkit extension is available.

:::image type="content" source="../assets/images/sbs-csharp/select-ttk.png" alt-text="Screenshot shows the selection of Agents Toolkit." lightbox="~/assets/images/sbs-csharp/select-installed-ttk.png":::

Set up your Teams development tenant

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

Check for custom app upload option

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

[!NOTE] Custom app upload is necessary for previewing and testing apps in Teams local environment. If it isn't enabled, you won't be able to preview and test your app in Teams local environment.

Do you already have a tenant, and admin access? Let's check if you do!

Verify if you can upload a custom apps in Teams:

Open Microsoft Teams, select the Apps icon.
Select Manage your apps.
Select Upload an app.
Look for the Upload a custom app option. If you see the option, custom app upload is enabled.

:::image type="content" source="../assets/images/sbs-csharp/custom-upload.png" alt-text="Illustration shows the option to upload a custom app in Teams.":::

[!NOTE] If you don't find the option to upload a custom app, contact your Teams administrator.

Create a free Teams developer tenant (optional)

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

Go to the Microsoft 365 developer program.
Select Join Now and follow the onscreen instructions.
In the welcome screen, select Setup E5 subscription.
Set up your administrator account. After you finish, the following screen appears:

:::image type="content" source="../assets/images/build-your-first-app/dev-program-subscription.png" alt-text="Screenshot shows the example of what you see after signing up for the Microsoft 365 developer program.":::
Sign in to Teams using the administrator account you set up. Verify that you've the Upload a custom app option in Teams.

Get a free Azure account

If you wish to host your app or access resources in Azure, you must have an Azure subscription. Create a free account before you begin.

Now you've got all the tools to set up your account. Next, let's set up your development environment and start building! Select the app you want to create first.

Create project workspace for your tab app using C sharp

Start Microsoft Teams app development by creating your first app. This app uses the tab capability. If the prerequisites are in place, let's begin!

The following steps help you to create project workspace for your tab app in Visual Studio:

Open Visual Studio.
Select New Project.

:::image type="content" source="../assets/images/sbs-csharp/visual-studio-welcome.png" alt-text="Screenshot shows the selection of New Project in Visual Studio.":::
In the search box, enter Teams.
Select Microsoft 365 Agents > Next.

:::image type="content" source="../assets/images/sbs-csharp/project-template.png" alt-text="Screenshot shows the selection of Teams." lightbox="../assets/images/sbs-csharp/new-project-template-vs.png":::
Enter the following details to configure your new project.
Enter required project name in Project name.
Select required location to save project files and folders.
Select Create.

:::image type="content" source="../assets/images/sbs-csharp/teams-app-project-name.png" alt-text="Screenshot shows the creation of Project name.":::
Select Tab > Create.

:::image type="content" source="../assets/images/sbs-csharp/select-tab.png" alt-text="Screenshot shows the selection of tab.":::

The Teams tab app is created in few seconds.

:::image type="content" source="../assets/images/sbs-csharp/get-started.png" alt-text="Screenshot shows the Project Creation." lightbox="../assets/images/sbs-csharp/get-started-tab-vs.png":::

Build and run your first tab app using C sharp

After you set up your project workspace with Agents Toolkit, build your tab app.

Sign in to your Microsoft 365 account

Use your Microsoft 365 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.

In the Solution Explorer, under Solution MyTeamsApp, right-click on MyTeamsApp.
Select Microsoft 365 Agents Toolkit > Select Microsoft 365 Account.

:::image type="content" source="../assets/images/sbs-csharp/app-dependencies.png" alt-text="Screenshot shows the selection of Teams app Dependencies." lightbox="../assets/images/sbs-csharp/teams-app-dependencies.png":::
Select Microsoft 365 Account > Continue.

:::image type="content" source="../assets/images/sbs-csharp/select-m365-account.png" alt-text="Screenshot shows the Selection of M365-account.":::

Build and run your app locally in Visual Studio

To build and run your app locally:

Select Debug > Start Debugging or select F5.

:::image type="content" source="../assets/images/sbs-csharp/start-debugging.png" alt-text="Screenshot shows the selection of start debugging action.":::

Visual Studio starts the debugging process and opens the Teams web client in a browser. If prompted, sign in with your Microsoft 365 account.
Select Add.

:::image type="content" source="../assets/images/sbs-csharp/select-add.png" alt-text="Screenshot of the app details dialog to add the tab app to Teams.":::
Select Open to open the app in personal scope.

Alternatively, you can either search and select the required scope or select a channel or chat from the list, and move through the dialog to select Go.

:::image type="content" source="../assets/images/sbs-csharp/add-scope.png" alt-text="Screenshot displays the scope selection dialog with the list of shared scopes.":::

Congratulations, your first tab app is running on Teams!

:::image type="content" source="../assets/images/sbs-csharp/final-output.png" alt-text=" Screenshot shows the final output of the Teams tab app.":::

Learn how to troubleshoot if your app doesn't run locally.

To successfully run your app in Teams, ensure that you've enabled custom app upload in your Teams account. You can learn more about custom app upload in the prerequisites section.

You've successfully created a tab app using C#. Agents Toolkit has added the necessary scaffolding to your app's directory structure. The tutorial is now complete.

[!div class="nextstepaction"] Create a tab [!div class="nextstepaction"] Create a new Teams project using Microsoft 365 Agents Toolkit

Add SSO to tab and message extension app

Microsoft Entra single sign-on (SSO) enables seamless user authentication in Teams.

Key aspects of Microsoft Entra SSO:

Allows the user to sign in automatically after the first sign in.
Allows the user to sign in to other devices without entering credentials again.
Obtains token for the signed in user.

Tutorial: Add SSO to tab and message extension app

This step-by-step guide helps you to create tabs and message extensions enabling Microsoft Entra SSO authentication. You'll see the following output:

:::image type="content" source="../assets/images/Tab-ME-SSO/hello-megan-profile245-1.png" alt-text="Screenshot of the tab and message extension with SSO authentication output after you've successfully completed the step-by-step guide.":::

Prerequisites for adding SSO to apps

Ensure that you install the following tools and set up your development environment:

#	Install	For using...
1.	Microsoft Teams	Microsoft Teams to collaborate with everyone you work with through apps for chat, meetings, and calls all in one place.
2.	Microsoft 365 developer account	Access to Teams account with the appropriate permissions to install an app.
3.	.NET Core SDK	Customized bindings for local debugging and Azure Functions app deployments. If you haven't installed the latest version, install the portable version.
4.	Visual Studio 2022	You can install the enterprise version in Visual Studio 2022, and install the ASP.NET and web development workloads. Use the latest version.
5.	Dev tunnel	Teams app features (conversational bots, message extensions, and incoming webhooks) need inbound connections. A tunnel connects your development system to Teams. Dev tunnel is a powerful tool to securely open your localhost to the internet and control who has access. Dev tunnel is available in Visual Studio 2022 version 17.7.0 or later. or You can also use ngrok as a tunnel to connect your development system to Teams. It isn't required for apps that only include tabs. This package is installed within the project directory (using npm `devDependencies`).

[!NOTE] After downloading ngrok, sign up and install authtoken.

Set up local environment

Open Microsoft-Teams-Samples.
Select Code.
From the dropdown menu, select Open with GitHub Desktop.

:::image type="content" source="../assets/images/include-files/clone-repository.png" alt-text="Screenshot show the option to clone repository in local.":::
Select Clone.

Register Microsoft Entra app

The following steps help you to create and register your bot in Azure portal:

Create and register your Azure app.
Create client secret to enable SSO authentication of the bot.
Add Teams channel to deploy the bot.
Create a tunnel to your web server's endpoints using dev tunnel (recommended) or ngrok.
Add messaging endpoint to the dev tunnel that you created.

Add App registration

Go to Azure portal.
Select App registrations.

:::image type="content" source="../assets/images/include-files/azure-app-registration.png" alt-text="Screenshot shows the Azure services to select App registrations.":::
Select + New registration.

:::image type="content" source="../assets/images/include-files/new-registration.png" alt-text="Screenshot shows the New registration page on Microsoft Entra admin center.":::
Enter the name of your app.
Select Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant).
Select Register.

:::image type="content" source="../assets/images/include-files/app-register.png" alt-text="Screenshot shows the option to register the bot in Microsoft Entra admin center.":::

Your app is registered in Microsoft Entra ID. The app overview page appears.

:::image type="content" source="../assets/images/include-files/app-registration-overview.png" alt-text="Screenshot shows the app registration overview page.":::

[!NOTE] Save the app ID from Application (client) ID and Directory (tenant) ID for further use.

Create a tunnel

Select one of the following ways to create a tunnel:

dev tunnel

Open Visual Studio.
Select Create a new project.

:::image type="content" source="../assets/images/include-files/create-new-project.png" alt-text="Screenshot shows the selection to create a new project.":::
In the search box, enter ASP.NET. From the search results, select ASP.NET Core Web App.
Select Next.

:::image type="content" source="../assets/images/include-files/template-search.png" alt-text="Screenshot shows the search and selection of the template.":::
Enter Project name and select Next.

:::image type="content" source="../assets/images/include-files/project-name.png" alt-text="Screenshot shows the project name to enter.":::
Select Create.

:::image type="content" source="../assets/images/include-files/additional-information.png" alt-text="Screenshot shows the project additional information." lightbox="../assets/images/include-files/additional-information.png":::

An overview window appears.

:::image type="content" source="../assets/images/include-files/asp-net-output.png" alt-text="Screenshot shows the overview window.":::
In the debug dropdown list, select Dev Tunnels (no active tunnel) > Create a Tunnel....

:::image type="content" source="../assets/images/include-files/create-tunnel.png" alt-text="Screenshot shows the dropdown to select the dev tunnels.":::

A pop-up window appears.
Update the following details in the pop-up window:
1. Account: Enter a Microsoft or GitHub account.
2. Name: Enter a name for your tunnel.
3. Tunnel Type: From the dropdown list, select Temporary.
4. Access: From the dropdown list, select Public.
Select OK.

:::image type="content" source="../assets/images/include-files/create-tunnel-details.png" alt-text="Screenshot shows the details to update for creation of tunnel.":::

A pop-up window appears showing that dev tunnel is successfully created.
Select OK.

:::image type="content" source="../assets/images/include-files/tunnel-created.png" alt-text="Screenshot shows the pop-up message that the tunnel is created.":::

You can find the tunnel you've created in the debug dropdown list as follows:

:::image type="content" source="../assets/images/include-files/tunnel-active.png" alt-text="Screenshot shows the tunnel is active and selected.":::
Select F5 to run the application in the debug mode.
If a Security Warning dialog appears, select Yes.

:::image type="content" source="../assets/images/include-files/security-warning.png" alt-text="Screenshot shows the dialog box to accept the security warning.":::

A pop-up window appears.
Select Continue.

:::image type="content" source="../assets/images/include-files/developer-tunnel.png" alt-text="Screenshot shows the url for the tunnel.":::

The dev tunnel home page opens in a new browser window and the dev tunnel is now active.

:::image type="content" source="../assets/images/include-files/developer-tunnel-web.png" alt-text="Screenshot shows the dev tunnel welcome page in browser.":::
Go to Visual Studio, and then select View > Output.
From the Output console dropdown menu, select Dev Tunnels.

The Output console shows the dev tunnel URL.

:::image type="content" source="../assets/images/include-files/output-console-url.png" alt-text="Screenshot shows the url in the Visual Studio output console.":::

ngrok

Use ngrok or Command Prompt to create a tunnel to your locally running web server's publicly available HTTPS endpoints. Run the following command in ngrok:

ngrok http --host-header=localhost xxxx

[!TIP] If you encounter ERR_NGROK_4018, follow the steps provided in the Command Prompt to sign up and authenticate ngrok. Then run the ngrok http --host-header=localhost xxxx command.

The window shows the HTTPS URL.

:::image type="content" source="../assets/images/include-files/ngrok-url.png" alt-text="Screenshot shows the ngrok HTTPS URL.":::

Add a web authentication

In the left pane, under Manage, select Authentication.
Select Add a platform > Web.

:::image type="content" source="../assets/images/include-files/platform-web.png" alt-text="Screenshot shows the selection of web authentication.":::
Enter the redirect URI for your app by appending auth-end to the fully qualified domain name. For example, https://your-devtunnel-domain/auth-end or https://your-ngrok-domain/auth-end.
Under Implicit grant and hybrid flows, select the Access tokens and ID tokens checkboxes.
Select Configure.

:::image type="content" source="../assets/images/include-files/configure-web.png" alt-text="The screenshot shows the option to add redirect uri and select implicit grant and hybrid flows.":::
Under Web, select Add URI.
Enter https://token.botframework.com/.auth/web/redirect.
Select Save.

:::image type="content" source="../assets/images/include-files/web-add-uri.png" alt-text="Screenshot shows the option to add redirect uri and select implicit grant and hybrid flows.":::

Create a client secret

[!NOTE] If you encounter the error Client secrets are blocked by tenant-wide policy. Contact your tenant administrator for more information., you can create a certificate instead. For step-by-step instructions, refer to create a certificate for app registration.

In the left pane, under Manage, select Certificates & secrets.
Under Client secrets, select + New client secret.

:::image type="content" source="../assets/images/include-files/new-client-secret.png" alt-text="Screenshot show the selection of new client secret.":::

The Add a client secret window appears.
Enter Description.
Select Add.

:::image type="content" source="../assets/images/include-files/add-client-secret.png" alt-text="Screenshot show the client secret description option to add.":::
Under Value, select Copy to clipboard to save the client secret value for further use.

:::image type="content" source="../assets/images/include-files/client-secret-value.png" alt-text="Screenshot show the option to copy the client secret ID value to copy value to clipboard.":::

Add API permissions

In the left pane, select API permissions.
Select + Add a permission.

:::image type="content" source="../assets/images/teams-file-upload-bot/add-api-permission.png" alt-text="The screenshot shows the option to select Add permission.":::
Select Microsoft Graph.
Select Delegated permissions.
Select User > User.Read.
Select Add permissions.

:::image type="content" source="../assets/images/teams-file-upload-bot/select-api-permission.png" alt-text="Screenshot show the option to select permissions.":::
[!NOTE]
- If an app isn't granted IT admin consent, users must provide consent the first time they use an app.
- Users need to consent to the API permissions only if the Microsoft Entra app is registered in a different tenant.

Add Application ID URI

In the left pane, under Manage, select Expose an API.
Next to Application ID URI, select Add.

:::image type="content" source="../assets/images/include-files/expose-api-add.png" alt-text="Screenshot shows the option to add Application ID URI.":::
Update the Application ID URI in the api://your-devtunnel-domain/botid-{AppID} or api://your-ngrok-domain/botid-{AppID} format and select Save.

:::image type="content" source="../assets/images/include-files/app-id-uri.png" alt-text="Screenshot shows the option to add redirect uri and save.":::

The following image shows the domain name:

:::image type="content" source="../assets/images/include-files/app-id-uri-output.png" alt-text="Screenshot shows the redirect uri.":::

Add a scope

In the left pane, under Manage, select Expose an API.
Select + Add a scope.

:::image type="content" source="../assets/images/include-files/select-add-scope.png" alt-text="The screenshot shows the selection to Add a Scope.":::
Enter access_as_user as the Scope name.
Under Who can consent?, select Admins and users.
Update the values for the rest of the fields as follows:
- Enter Teams can access the user’s profile as Admin consent display name.
- Enter Allows Teams to call the app’s web APIs as the current user as Admin consent description.
- Enter Teams can access the user profile and make requests on the user’s behalf as User consent display name.
- Enter Enable Teams to call this app’s APIs with the same rights as the user as User consent description.
Ensure that State is set to Enabled.
Select Add scope.

The following image shows the fields and the values:

:::image type="content" source="../assets/images/include-files/set-add-scope.png" alt-text="The screenshot shows the values filled in the field to Add a scope.":::

[!NOTE] The Scope name must match with the Application ID URI with /access_as_user appended at the end.

:::image type="content" source="../assets/images/include-files/add-scope.png" alt-text="The screenshot shows the details in Scopes.":::

Add client application

In the left pane, under Manage, select Expose an API.

Under Authorized client applications, identify the applications that you want to authorize for your app’s web application.
Select + Add a client application.

:::image type="content" source="../assets/images/include-files/add-client-application.png" alt-text="Screenshot shows the option to Select client application.":::
Add Teams mobile or desktop and Teams web application.
1. For Teams mobile or desktop: Enter the Client ID as 1fec8e78-bce4-4aaf-ab1b-5451cc387264.
  
  :::image type="content" source="../assets/images/include-files/client-id-mobile-desktop.png" alt-text="Screenshot shows the mobile or desktop Client ID application.":::
2. For Teams web: Enter the Client ID as 5e3ce6c0-2b1f-4285-8d4b-75ee78787346.
  
  :::image type="content" source="../assets/images/include-files/client-id-web.png" alt-text="Screenshot shows the web Client ID application.":::
Select the Authorized scopes checkbox.
Select Add application.

:::image type="content" source="../assets/images/include-files/authorized-scope-add.png" alt-text="Screenshot shows the option to select authorized scopes and add application.":::

The following image displays the Client Id:

:::image type="content" source="../assets/images/include-files/add-client-application-output.png" alt-text="Screenshot shows the output of Client applications.":::

Update the manifest

In the left pane, select Manifest.
Set the value for the requestedAccessTokenVersion to 2 and select Save.

:::image type="content" source="../assets/images/include-files/manifest-token.png" alt-text="Screenshot shows the manifest option and accesstoken details in Azure portal.":::

Create a bot

Create an Azure bot resource

[!NOTE] If you're already testing your bot in Teams, sign out of this app and Teams. To see this change, sign in again.

Go to Home.
Select + Create a resource.
In the search box, enter Azure Bot.
Select Enter.
Select Azure Bot.
Select Create.

:::image type="content" source="../assets/images/include-files/azure-bot.png" alt-text="Screenshot shows the creation of Azure bot.":::
Enter the bot name in Bot handle.
Select your Subscription from the dropdown list.
Select your Resource group from the dropdown list.

:::image type="content" source="../assets/images/include-files/create-azure-bot.png" alt-text="Screenshot shows the option resource group and subscription in the Azure portal.":::

If you don't have an existing resource group, you can create a new resource group. To create a new resource group, follow these steps:
1. Select Create new.
2. Enter the resource name and select OK.
3. Select a location from New resource group location dropdown list.
:::image type="content" source="../assets/images/include-files/new-resource-location.png" alt-text="Screenshot shows the new resource group option in Azure portal.":::
Under Pricing, select Change plan.

:::image type="content" source="../assets/images/include-files/pricing-tier.png" alt-text="Screenshot shows the pricing option in Azure portal.":::
Select FO Free > Select.

:::image type="content" source="../assets/images/include-files/pricing-free.png" alt-text="Screenshot shows the option to select free.":::
Under Microsoft App ID, select Type of App as Multi Tenant.
In the Creation type, select Use existing app registration.
Enter the App ID.

[!NOTE] You can't create more than one bot with the same Microsoft App ID.
Select Review + create.

:::image type="content" source="../assets/images/include-files/review-create-app-id.png" alt-text="Screenshot shows the creation of new bot.":::
After the validation passes, select Create.

The bot takes a few minutes to provision.
Select Go to resource.

:::image type="content" source="../assets/images/include-files/resource-deployment.png" alt-text="Screenshot shows the Go to resource option in the Azure portal.":::

You've successfully created your Azure bot.

:::image type="content" source="../assets/images/include-files/azure-bot-created-output.png" alt-text="Screenshot shows the output of a bot.":::

Add a Teams channel

In the left pane, select Channels.
Under Available Channels, select Microsoft Teams.

:::image type="content" source="../assets/images/include-files/channels-teams.png" alt-text="Screenshot shows the selection of Teams in channels.":::
Select the checkbox to accept the Terms of Service.
Select Agree.

:::image type="content" source="../assets/images/include-files/terms-service.png" alt-text="Screenshot shows the acceptance of terms of service.":::
Select Apply.

:::image type="content" source="../assets/images/include-files/teams-apply.png" alt-text="Screenshot shows the Microsoft Teams as messaging to apply.":::

To add a messaging endpoint

dev tunnel

Use the dev tunnel URL in the Output console as the messaging endpoint.

:::image type="content" source="../assets/images/include-files/output-console-url.png" alt-text="Screenshot shows the url in the Visual studio output console.":::
In the left pane, under Settings, select Configuration.
Update the Messaging endpoint in the format https://your-devtunnel-domain/api/messages.

:::image type="content" source="../assets/images/include-files/devtunnels-messaging-endpoint.png" alt-text="Screenshot shows the messaging endpoint adding API.":::
Select Apply.

You've successfully set up a bot in Azure Bot service.

[!NOTE] If the Application Insights Instrumentation key shows an error, update with App ID.

ngrok

From ngrok, copy the HTTPS URL.

:::image type="content" source="../assets/images/include-files/ngrok-url.png" alt-text="Screenshot shows the ngrok HTTPS URL.":::

[!NOTE] The HTTPS URL in your ngrok is a fully qualified domain name. The WebAppDomain is a fully qualified domain name that doesn't include https:// in it.
In the left pane, under Settings, select Configuration.
Update the Messaging endpoint in the format https://your-ngrok-domain/api/messages.

:::image type="content" source="../assets/images/include-files/ngrok-messaging-endpoint.png" alt-text="Screenshot shows the messaging endpoint adding API.":::
Select Apply.

You have successfully set up a bot in Azure Bot service.

[!NOTE] If the Application Insights Instrumentation key shows an error update with App ID.

Add an OAuth connection settings

In the left pane, select Configuration.
Select Add OAuth Connection Settings.
Under New Connection Setting, update the following details:
- Name: Enter a name for your new connection setting. You can use the name in the settings of your bot service code.
- Service Provider: From the dropdown list, select Azure Active Directory v2.
- Client id: Update your Microsoft App ID.
- Client secret: Update the client secrets Value.
- Token Exchange URL: Update the Application ID URI.
- Tenant ID: Enter Common.
- Scopes: Enter User.Read.
Select Save.

:::image type="content" source="../assets/images/include-files/new-connection-setting.png" alt-text="Screenshot shows the values added to set OAuth connection.":::

Set up app settings

Go to the appsettings.json file in the cloned repository.

:::image type="content" source="../assets/images/Tab-ME-SSO/app-setting-folder-1.png" alt-text="Screenshot of Project file with appsettings.json file highlighted in red.":::
Open the appsettings.json file in Visual Studio.
Update the following information:
- Replace "MicrosoftAppId" to your bot's Microsoft App ID.
- Replace "MicrosoftAppPassword" to your bot's client secrets Value.
- Replace "SiteUrl" to your ngrok URL.
- Replace "ConnectionName" to the name of OAuth connection setting.
- Replace "TenantId" to the tenant ID of the tenant where the app is used.
- Replace "ClientId" to your bot's Microsoft App ID.
- Replace "AppSecret" to your bot's client secrets Value.
- Replace "ApplicationIdURI" in the form of api://*******.ngrok.io/botid-{AppID}.
:::image type="content" source="../assets/images/Tab-ME-SSO/app-setting.png" alt-text="Screenshot of the appsettings.json file with the values entered highlighted in red.":::

Set up manifest file

Go to the manifest.json file in the cloned repository.

:::image type="content" source="../assets/images/Tab-ME-SSO/folder-manifest-1.png" alt-text="Screenshot of Manifest folder with the manifest file highlighted in red.":::
Open the manifest.json file in Visual Studio and make the following changes:
- Replace DOMAIN-NAME with your ngrok URL.
- Replace YOUR-MICROSOFT-APP-ID with your bot's Microsoft App ID.
  
  [!NOTE] Depending on the scenario [YOUR-MICROSOFT-APP-ID] and [DOMAIN-NAME] may occur multiple times.
- Replace resource as api://*******.ngrok.io/botid-{AppID}.
  
  :::image type="content" source="../assets/images/Tab-ME-SSO/vs-manifest.png" alt-text="Screenshot of the manifest.json file with the values entered highlighted in red.":::

Build and run the service

To build and run the service, use Visual Studio or Command line.

Visual Studio

Open Visual Studio.
Select File > Open > *Project/Solution...

:::image type="content" source="../assets/images/Tab-ME-SSO/open-project1.png" alt-text="Screenshot of Visual Studio file menu. The menu entries titled Open under File menu and Project/Solution under Open are highlighted in red.":::
In the csharp folder, select App SSO Sample.csproj file.

:::image type="content" source="../assets/images/Tab-ME-SSO/project-folder1-1.png" alt-text= "Screenshot of Project file with App SSO Sample.csproj file highlighted in red.":::
Press F5 to run the project.
Select Yes if the following dialog appears:

:::image type="content" source="../assets/images/sbs-outgoing-webhooks/outgoing-webhook-certificate.png" alt-text="Screenshot of Security Warning with the Yes option highlighted in red.":::

A webpage appears with a message Your bot is ready!

:::image type="content" source="../assets/images/Tab-ME-SSO/bot-completion-explorer.png" alt-text="Screenshot of the webpage that displays Your bot is ready.":::

Command line

Go to the csharp folder in a Command Prompt window and enter the following command:

dotnet run

Upload SSO App to Teams

In your cloned repository, go to csharp > App SSO Sample > TeamsAppManifest.
Create a .zip file with the following files that are present in the Manifest folder:
- manifest.json
- icon-outline.png
- icon-color.png
:::image type="content" source="../assets/images/Tab-ME-SSO/upload-tab-me-sso-1.png" alt-text="Screenshot of Manifest folder with tab manifest zip folder highlighted in red.":::
In the Teams client, select the Apps icon.
Select Manage your apps.
Select Upload an app.
Look for the option to Upload a custom app. If you see the option, custom app upload is enabled.

:::image type="content" source="../assets/images/tab-device-permission/custom-upload.png" alt-text="Screenshot shows the upload a custom app.":::

[!NOTE] Contact your Teams administrator, if you don't find the option to upload a custom app.
Select Open to upload the .zip file that you created in the Manifest folder.

:::image type="content" source="../assets/images/Tab-ME-SSO/upload-tab-me-sso-open-1.png" alt-text="Screenshot of Manifest folder with Open option to upload the Teams Bot zip file highlighted in red.":::
Select Add.

:::image type="content" source="../assets/images/Tab-ME-SSO/add-sso-app-1.png" alt-text="Screenshot of app details dialog to add tab SSO app.":::
Select Open and send a message to the bot.

:::image type="content" source="../assets/images/Tab-ME-SSO/open-sso-app.png" alt-text="Screenshot of scope selection dialog with Open option highlighted.":::
The bot performs SSO and displays profile card along with option prompt to view token.

:::image type="content" source="../assets/images/Tab-ME-SSO/Congratulation-image-1.png" alt-text="Screenshot of the profile card received in Teams.":::
Select Yes to view token or No to continue with chat.

:::image type="content" source="../assets/images/Tab-ME-SSO/token-view1-1.png" alt-text="Screenshot of the dialog to either select Yes or No.":::
If SSO isn't performed, then the bot performs default authentication method for your tab.

:::image type="content" source="../assets/images/Tab-ME-SSO/not-login11-1.png" alt-text="Screenshot of the default SSO page in Teams.":::
To sign in, if SSO isn't performed:
1. In the left pane of the Teams, select More added apps (●●●).
2. Select your new SSO application.
  
  :::image type="content" source="../assets/images/Tab-ME-SSO/recent-app-sso-1.png" alt-text="Screenshot of your app highlighted in red in Apps section.":::
3. Select sign in.
  
  :::image type="content" source="../assets/images/Tab-ME-SSO/sign-in-sso1-1.png" alt-text= "Screenshot of your app with sign in highlighted in red.":::
4. Enter your credentials in Sign in window and select Next.
  
  :::image type="content" source="../assets/images/Tab-ME-SSO/sign-in-box.png" alt-text= "Screenshot of Microsoft Sign in page with Next highlighted in red.":::
5. Select Accept.
  
  :::image type="content" source="../assets/images/Tab-ME-SSO/consent-box.png" alt-text= "Screenshot of Microsoft consent dialog with Accept highlighted in red.":::
6. Select your profile under search box. You'll see the following output:
  
  :::image type="content" source="../assets/images/Tab-ME-SSO/hello-megan-profile-1.png" alt-text= "Screenshot of the selected profile.":::
Send https://profile.botframework.com to the application to get a profile card.

:::image type="content" source="../assets/images/Tab-ME-SSO/profile-card-1.png" alt-text= "Screenshot of the selected profile after entering the URL.":::

Did you come up with output like this?

:::image type="content" source="../assets/images/Tab-ME-SSO//hello-megan-profile245-1.png" alt-text="Screenshot of the output after you've successfully completed the step-by-step guide.":::

You've completed the tutorial to get started with SSO for tab and message extension app.

[!div class="nextstepaction"] Enable SSO for tab app [!div class="nextstepaction"] Enable SSO for your app

FilesExpand file tree

tutorials.md

Latest commit

History

tutorials.md

File metadata and controls

Tutorials

Build your first bot app

Prerequisites

Set up prerequisites

Install Microsoft 365 Agents Toolkit

Set up your Teams development tenant

Check for upload an app option

Create a free Teams developer tenant

Get a free Azure account

Create project workspace for your bot app

Create your bot project workspace

Take a tour of the bot app source code

Build and run your first bot app

Sign in to your Microsoft 365 account

Build and run your first bot app locally

Deploy your first Teams app

Sign in to your Azure account

Provision and Deploy your app on Azure

Run the deployed app

Debug your AI chat bot using Microsoft 365 Agents Playground

Prerequisites

Create project workspace for your AI chat bot app

Create your bot project workspace

Take a tour of the bot app source code

Build and run your AI chat bot app

Create OpenAI key and endpoint for your AI chat bot

Get Azure OpenAI keys and endpoint

Update Azure OpenAI key and endpoints

Debug and run your AI chat bot app

Activity triggers

Predefined activity triggers

Custom activity triggers

Complete challenge

Send proactive messages

Prerequisites

Prepare development environment

Install Microsoft 365 Agents Toolkit

Set up your Teams development tenant

Check for upload an app option

Create a free Teams developer tenant (optional)

Build Proactive Message bot

Take a tour of the source code

Deploy your Proactive message bot

Sign in to your Azure account

Deploy your app to Azure

Complete challenge

Build API-based message extension

Prerequisites for building a message extension

Set up your Teams development tenant

Check for custom app upload option

Create a free Teams developer tenant (optional)

Get a free Azure account

Create OpenAPI Description document

Create response rendering template

Adaptive Card template

Create a preview card template

Response rendering template

Create app manifest

Create a Teams app manifest

Upload a custom app to Teams

Build action-based message extension

Prerequisites

Set up local environment

Register Microsoft Entra app

Add App registration

Create a tunnel

Add web authentication

Create a client secret

Add API permissions

Add application ID URI

Add a scope

Add client application

Create your bot

Create an Azure bot resource