diff --git a/msteams-platform/TOC.yml b/msteams-platform/TOC.yml index 83c7943d51b..1d855956568 100644 --- a/msteams-platform/TOC.yml +++ b/msteams-platform/TOC.yml @@ -938,10 +938,7 @@ href: concepts/device-capabilities/people-picker-capability.md - name: Use Fluid with Teams href: tabs/how-to/using-fluid-msteam.md - displayName: Fluid client, Azure Fluid Relay, Fluid Containers, React component - - name: Explore SDKs and code samples - href: get-started/tool-options-and-code-samples.md - displayName: Teams app samples, tools to build Teams app + displayName: Fluid client, Azure Fluid Relay, Fluid Containers, React components, Fluid Framework - name: Resources items: - name: Localization @@ -969,6 +966,14 @@ - name: Extend Microsoft 365 Copilot href: messaging-extensions/how-to-extend-copilot.md displayName: message extension, plugin, Copilot, Microsoft 365 Copilot +- name: Tutorials and code samples + items: + - name: Tutorials + href: get-started/tutorials.md + displayName: Build a Teams app, Build a Teams bot, Build a Teams tab, Build a message extension, Build apps for Teams meetings and calls + - name: Code samples + href: get-started/tool-options-and-code-samples.md + displayName: Teams app samples, Teams bot samples, Teams tab samples, Message extension samples, Apps for Teams meetings and calls samples - name: Integrate device capabilities items: - name: What are device capabilities? diff --git a/msteams-platform/get-started/tutorials.md b/msteams-platform/get-started/tutorials.md new file mode 100644 index 00000000000..3c5e91be055 --- /dev/null +++ b/msteams-platform/get-started/tutorials.md @@ -0,0 +1,1865 @@ +--- +title: Explore Microsoft Teams Tutorials +description: Learn about tutorials to build apps with various capabilities such as AI, UI, and various languages, to prepare your environment. +ms.localizationpriority: high +ms.date: 11/14/2025 +ms.topic: reference +--- + +# Teams app 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. | Bots | [Debug your AI chat bot using Microsoft 365 Agents Playground](#debug-your-ai-chat-bot-using-microsoft-365-agents-playground) | +| 2. | Tabs | [Build your first app using C sharp](#build-your-first-app-using-c-sharp) | +| 3. | Message extension | [Build API-based message extension](#build-api-based-message-extension) | +| 4. | SSO | - [Build a bot with SSO authentication](#build-a-bot-with-sso-authentication)
- [Add SSO to tab and message extension app](#add-sso-to-tab-and-message-extension-app) | + +## Debug your AI chat bot using Microsoft 365 Agents Playground + +
+Tutorial: Debug your AI chat bot + +### Prerequisites + +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. + +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](https://code.visualstudio.com/download) or [Visual Studio](https://visualstudio.microsoft.com/downloads/) | JavaScript, TypeScript, or C# build environments. Use the latest version. | +| [Microsoft 365 Agents Toolkit](https://marketplace.visualstudio.com/items?itemName=TeamsDevApp.ms-teams-vscode-extension) | 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](/microsoftteams/platform/toolkit/install-agents-toolkit?tabs=vscode&pivots=visual-studio-code-v5#install-agents-toolkit-for-visual-studio-code).| +| [Node.js](https://nodejs.org/en/download/) | Back-end JavaScript runtime environment. For more information, see [Node.js version compatibility table for project type](~/toolkit/build-environments.md#nodejs-version-compatibility-table-for-project-type).| +| [OpenAI](https://openai.com/api/) or [Azure OpenAI](https://oai.azure.com/portal)| 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](https://www.microsoft.com/edge) (recommended) or [Google Chrome](https://www.google.com/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="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. + +In this tutorial, learn how to: + +1. [Create your bot project workspace.](#create-your-bot-project-workspace) +1. [Take a tour of the bot app source code.](#take-a-tour-of-the-bot-app-source-code) + +#### Create your bot project workspace + +If the prerequisites are in place, let's begin! + +1. Open **Visual Studio Code**. + +1. 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**. + +1. Select **Create a New Agent/App**. + + :::image type="content" source="~/assets/images/toolkit-v2/create-project.png" alt-text="Screenshot shows the location of the Create New Project link in the Agents Toolkit sidebar."::: + +1. 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."::: + +1. 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."::: + +1. Select the programming language as **JavaScript**. + + :::image type="content" source="~/assets/images/agents-playground/select-language-bot.png" alt-text="Screenshot shows the option to select the programming language."::: + +1. Select **Default folder**. + + :::image type="content" source="~/assets/images/toolkit-v2/first-bot/select-default-location.png" alt-text="Screenshot shows 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."::: + +1. Select the location for the project workspace. +1. Select **Select Folder**. + + :::image type="content" source="~/assets/images/toolkit-v2/select-folder.png" alt-text="Screenshot shows the folder to select."::: + +1. 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.| + +[Back to top](#debug-your-ai-chat-bot-using-microsoft-365-agents-playground) + +### Build and run your AI chat bot app + +#### Create Open AI key and endpoint for your AI chat bot + +1. Go to [Azure portal](https://ms.portal.azure.com/). +1. Select **Create a resource** and search for Azure Open AI. +1. Select **Azure Open AI** and select **Create**. + + :::image type="content" source="../assets/images/agents-playground/azure-open-ai.png" alt-text="Screenshot shows the Azure open AI in Azure portal."::: + +1. 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 open AI subscription and resource group."::: + +1. 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 open AI network details."::: + +1. 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 open AI tags details."::: + +1. Select **Create**. + + :::image type="content" source="../assets/images/agents-playground/review-create.png" alt-text="Screenshot shows you to preview and create Azure open AI."::: + +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 open AI."::: + +> [!NOTE] +> You can also get OpenAI API key to debug your AI chat bot. For more information, see [setup your API key](https://platform.openai.com/docs/quickstart/step-2-setup-your-api-key). + +##### Get Azure Open AI keys and endpoint + +1. 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 open AI."::: + +1. 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. + +1. 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 open AI."::: + + The Azure Open AI Studio window appears. + +1. Select **Deployments** from the left pane and select **+ Create new deployments**. + + :::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 open AI."::: + +1. 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. + +1. Select **0301 (Default)** from the **Model version** dropdown list. +1. 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 open AI deployment."::: + +1. 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 open AI deployment."::: + +#### Update Azure Open AI key and endpoints + +1. Open your project in Visual Studio Code. + +1. Under **EXPLORER**, go to **env** > **.env.playground.user** file. + +1. Enter your **SECRET_AZURE_OPENAI_API_KEY** and **SECRET_AZURE_OPENAI_ENDPOINT**. + + ```text + ... + SECRET_AZURE_OPENAI_API_KEY= + SECRET_AZURE_OPENAI_ENDPOINT= + ``` + +1. Go to **src** > **app.js** file. + +1. Comment the `OpenAI` code and uncomment the `Azure OpenAI` code. + +1. Enter your Azure Open AI deployment name in `azureDefaultDeployment`. + + ```JavaScript + + // 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 + +1. 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."::: + +1. 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."::: + +[Back to top](#debug-your-ai-chat-bot-using-microsoft-365-agents-playground) + +### Activity triggers + +There are two types of activity triggers: + +1. [Predefined activity triggers](#predefined-activity-triggers) +1. [Custom activity triggers](#custom-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: + +1. 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. + +1. 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. + +1. 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."::: + +1. Add `messageReaction` to customize the activity under the `type` property: + + ```json + { + "type": "messageReaction", + "reactionsAdded": [ + { + "type": "like" + } + ], + "replyToId": "d60fd1cb-3e8f-44ef-849c-404806ba1b47" + } + ``` + +1. 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."::: + +[Back to top](#debug-your-ai-chat-bot-using-microsoft-365-agents-playground) + +#### 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](../toolkit/debug-your-agents-playground.md) + +
+ +[Back to top](#teams-app-tutorials) + +## Build API-based message extension + +
+Tutorial: Build API-based message extension + +> [!NOTE] +> API-based message extensions only support search commands. + +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. + +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](https://www.microsoft.com/microsoft-teams/download-app) | Microsoft Teams to collaborate with everyone you work with through apps for chat, meetings, or call - all in one place.| +| [Microsoft Edge](https://www.microsoft.com/edge) (recommended) or [Google Chrome](https://www.google.com/chrome/) | A browser with developer tools. | +| [Visual Studio Code](https://code.visualstudio.com/download) | JavaScript, TypeScript, or SharePoint Framework (SPFx) build environments. Use version 1.55 or later. | +| [Microsoft 365 developer account](../concepts/build-and-test/prepare-your-o365-tenant.md) | Access to Teams account with the appropriate permissions to install an app. | +| [Azure account](https://azure.microsoft.com/free/) | Access to Azure resources.| +|OpenAPI Description (OAD) document| A document that describes the capabilities of your API. For more information, see [OpenAPI Description](https://learn.openapis.org/specification/structure.html).| + +### 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: + +1. In the Teams client, select the **Apps** icon. +1. Select **Manage your apps**. +1. Select **Upload an app**. +1. 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! + +1. Go to the [Microsoft 365 developer program](https://developer.microsoft.com/microsoft-365/dev-program). +1. Select **Join Now** and follow the onscreen instructions. +1. In the welcome screen, select **Set up E5 subscription**. +1. 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="Screenshot shows the Microsoft 365 Developer Program."::: + +5. 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](https://azure.microsoft.com/free/) 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 + +```yml + 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: + +1. Go to [Swagger/OpenAPI validator](https://apitools.dev/swagger-parser/) and validate the OpenAPI Description document. +1. Save the OpenAPI Description document. +1. Go to [Swagger Editor](https://editor.swagger.io/). +1. In the left pane, paste the OpenAPI Description in the editor. +1. In the right pane, select **GET**. +1. Select **Try it out**. +1. Enter the values for the **search** parameter as **Tool to create music**. +1. 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."::: + +1. Go to **Server response** > **Response Body**. +1. 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: + +1. Go to [ChatGPT](https://chat.openai.com/) and ask the following query in the message compose area: + + ```http + + 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" + ] + ``` + +1. Select **Send message**. + +1. 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 + +```json + +{ +"$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" + } +] +} + +``` + +
+ +1. To verify if the Adaptive Card generated binds to the sample data, follow these steps: + 1. Go to [Adaptive Card Designer](https://adaptivecards.io/designer/). + 1. Go to **Select host app**, and then select **Microsoft Teams** from the dropdown. + 1. Go to **CARD PAYLOAD EDITOR** and paste the Adaptive Card template code. + 1. 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."::: + + 1. 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 + +```json + "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`](https://developer.microsoft.com/json-schemas/teams/v1.20/MicrosoftTeams.ResponseRenderingTemplate.schema.json). + +To create a response rendering template, follow these steps: + +1. Create a JSON file and add the following code to the file: + + ```json + { + "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.20/MicrosoftTeams.ResponseRenderingTemplate.schema.json", + "version": "1.0", +  "jsonPath": "", +  "responseLayout": "", +  "responseCardTemplate": { + }, + "previewCardTemplate": { + } + } + ``` + +1. Update the properties in the response rendering template as follows: + + 1. `"$schema"`: `"https://developer.microsoft.com/json-schemas/teams/v1.20/MicrosoftTeams.ResponseRenderingTemplate.schema.json"` + 1. `"version"`: `"1.0"` + + `version` is the version of the rendering template to use + + 1. `"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](https://www.newtonsoft.com/json/help/html/QueryJsonSelectToken.htm). + + 1. `"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`. + + 1. `"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. + + 1. `"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. + +1. 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 + +```json + +{ + "$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: + +1. Create a new JSON file. Your app manifest must conform to the 1.20 version of the schema defined in [App manifest schema](/microsoft-365/extensibility/schema/?view=m365-app-1.24&viewFallbackFrom=m365-app-1.23%3Ftoc%3D%2Fmicrosoftteams%2Fplatform%2Ftoc.json&bc=%2Fmicrosoftteams%2Fplatform%2Fbreadcrumb%2Ftoc.json&preserve-view=true). + +1. Add the following code to the JSON file: + +
App manifest + + ```json + { + "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.20/MicrosoftTeams.schema.json", + "manifestVersion": "1.20", + "version": "1.0.3", + "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": [] + } + ``` + +
+ +1. Update the app manifest properties as follows: + + - Replace `<>` 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. + +1. 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: + +1. Go to **Microsoft Teams** and sign in using your test tenant credentials. +1. Go to **Apps** > **Manage your app** > **Upload an app**. +1. Select **Upload a customized app**. +1. Select the zip file created and select **Open**. +1. 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."::: + +1. 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."::: + +1. Go to a chat, then select **+** from the message compose area, and search for your app. +1. 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."::: + +1. The app responds with an Adaptive Card in the chat window. +1. 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](../messaging-extensions/create-api-message-extension.md) + +
+ +[Back to top](#teams-app-tutorials) + +## Build a bot with SSO authentication + +
+Tutorial: 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. + +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](https://www.microsoft.com/microsoft-teams/download-app) | Microsoft Teams to collaborate with everyone you work with through apps for chat, meetings, and calls all in one place. | +| [Visual Studio 2022](https://visualstudio.microsoft.com) | 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](/microsoftteams/platform/concepts/build-and-test/prepare-your-o365-tenant) | 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](https://ngrok.com/download) 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](https://ngrok.com/download). + +### 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: + +1. In the Teams client, select the **Apps** icon. +1. Select **Manage your apps**. +1. Select **Upload an app** +1. 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! + +1. Go to the [Microsoft 365 developer program](https://developer.microsoft.com/microsoft-365/dev-program). +1. Select **Join Now** and follow the onscreen instructions. +1. In the welcome screen, select **Setup E5 subscription**. +1. 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."::: + +1. 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 + +[!INCLUDE [Set up local environment](../includes/get-started/clone-repository.md)] + +### 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. + +[!INCLUDE [Azure app registration](../includes/get-started/azure-app-registration.md)] + +**Create a tunnel** + +# [dev tunnel](#tab/dev) + +[!INCLUDE [Tunnel](../includes/get-started/dev-tunnel.md)] + +# [ngrok](#tab/ngrok) + +[!INCLUDE [Tunnel](../includes/get-started/ngrok-tunnel.md)] + +--- + +[!INCLUDE [Azure web authentication](../includes/get-started/azure-web-authentication.md)] + +[!INCLUDE [Client secret](../includes/get-started/create-client-secret.md)] + +**Add API permissions** + +1. In the left pane, select **API permissions**. + +1. 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."::: + +1. Select **Microsoft Graph**. + +1. Select **Delegated permissions**. + +1. Select **User** > **User.Read**. + +1. 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. + +**Application ID URI** + +1. In the left pane, under **Manage**, select **Expose an API**. + +1. 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."::: + +1. 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."::: + +[!INCLUDE [Azure add scope](../includes/get-started/azure-add-scope.md)] + +[!INCLUDE [Azure client application](../includes/get-started/azure-client-application.md)] + +[!INCLUDE [Manifest](../includes/get-started/azure-manifest.md)] + +### Create your bot + +[!INCLUDE [Azure bot resource](../includes/get-started/azure-bot-resource.md)] + +[!INCLUDE [Teams channel](../includes/get-started/add-teams-channel.md)] + +[!INCLUDE [Messaging endpoint](../includes/get-started/messaging-endpoint.md)] + +[!INCLUDE [Service connection](../includes/get-started/oauth-connection-settings.md)] + +### Set up app settings and manifest files + +1. 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."::: + +1. 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."::: + +1. 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."::: + +1. Open the **manifest.json** file and update the following changes: + + - Replace all occurrences of `"{TODO: MicrosoftAppId}"` with your **Microsoft App ID**. + - Set `"<>"` 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 + +1. Open Visual Studio. + +1. Go to **File** > **Open** > **Project/Solution...**. + + :::image type="content" source="~/assets/images/bots/project-solution_1.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."::: + +1. 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."::: + +1. Select **F5** to run the project. +1. If a **Security Warning** dialog appears, select **Yes**. + + :::image type="content" source="~/assets/images/bots/certificate.png" alt-text="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="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**. + 1. In the **Options** window that appears, select **NuGet Package Manager** > **Package Sources**. + 1. Select **Add**. + 1. In **Name**, enter `nuget.org` and in **Source**, enter `https://api.nuget.org/v3/index.json`. + 1. Select **Update** and **OK**. + 1. Rebuild your project. +
+ +
+ +### Upload the bot in Teams + +1. In your cloned repository, go to **Microsoft-Teams-Samples** > **samples** > **bot-conversation-sso-quickstart** > **csharp_dotnetcore** > **TeamsApp** > **appPackage**. +1. 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."::: + +1. Go to **Microsoft Teams**. + + 1. In the Teams client, select **Apps**. + 1. Select **Manage your apps**. + 1. Select **Upload an app**. + 1. 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."::: + +1. 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="Screenshot of Manifest folder with Open option to upload the Teams Bot zip file highlighted in red."::: + +1. 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."::: + +1. Select **Open**. + + :::image type="content" source="~/assets/images/bots/conversation-bot-open.png" alt-text="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. + +1. Send a message to the bot. The conversation bot asks for consent for the first time. + +1. 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. + +1. 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 app](../bots/how-to/authentication/bot-sso-overview.md) + +
+ +[Back to top](#teams-app-tutorials) + +## Build your first app using C sharp + +
+Tutorial: Build your first app using C# + +Start Microsoft Teams app development by building your first Teams app with a tab, a bot, or a message extension 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. + +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 a bot app + +Here's a list of tools you need to install for building and deploying a Teams app. + +| Install | For using... | + --- | --- | +| [Microsoft Teams](https://www.microsoft.com/microsoft-teams/download-app) | Microsoft Teams to collaborate with everyone you work with through apps for chat, meetings, and call all in one place.| +| [Visual Studio 2022](https://visualstudio.microsoft.com)
| 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](#install-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](https://visualstudio.microsoft.com). Agents Toolkit is available as an extension in Visual Studio. + +After you open the Visual Studio installer, in the pop-up workloads window. + +1. Select **ASP.NET and web development**. +1. Under **installation details** > **Optional**, select **Microsoft Teams development tools**. +1. 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"::: + +1. 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."::: + +1. 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"::: + +6. From the left pane, select **Installed**. The **Microsoft 365 Agents Toolkit** extension is avaialble. + + :::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: + +1. Open Microsoft Teams, select the **Apps** icon. +1. Select **Manage your apps**. +1. Select **Upload an app**. +1. 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! + +1. Go to the [Microsoft 365 developer program](https://developer.microsoft.com/microsoft-365/dev-program). +1. Select **Join Now** and follow the onscreen instructions. +1. In the welcome screen, select **Setup E5 subscription**. +1. 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."::: + +5. 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](https://azure.microsoft.com/free/). 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 # + +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: + +1. Open Visual Studio. +1. 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."::: + +1. In the search box, enter **Teams**. +1. 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"::: + +1. Enter the following details to configure your new project. +1. Enter required project name in **Project name**. +1. Select required location to save project files and folders. +1. Select **Create**. + + :::image type="content" source="../assets/images/sbs-csharp/teams-app-project-name.png" alt-text="Screenshot shows the creation of Project name."::: + +1. 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. + +1. In the **Solution Explorer**, under **Solution MyTeamsApp**, right-click on **MyTeamsApp**. + +1. 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"::: + +1. 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: + +1. 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. + +1. 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."::: + +1. 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 of 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](#prerequisites-for-building-a-bot-app) section. + +
+ +You have 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. + +
+ +[Back to top](#teams-app-tutorials) + +## Add SSO to tab and message extension app + +
+Tutorial: 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. + +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 have 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](https://www.microsoft.com/microsoft-teams/download-app) | 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](../concepts/build-and-test/prepare-your-o365-tenant.md) | Access to Teams account with the appropriate permissions to install an app. | +| 3. | [.NET Core SDK](https://dotnet.microsoft.com/en-us/download) | 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](https://visualstudio.microsoft.com) | 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](https://ngrok.com/downloads) 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](https://ngrok.com/downloads). + +### Set up local environment + +[!INCLUDE [Set up local environment](../includes/get-started/clone-repository.md)] + +### 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. + +[!INCLUDE [Azure app registration](../includes/get-started/azure-app-registration.md)] + +**Create a tunnel** + +# [dev tunnel](#tab/dev) + +[!INCLUDE [Tunnel](../includes/get-started/dev-tunnel.md)] + +# [ngrok](#tab/ngrok) + +[!INCLUDE [Tunnel](../includes/get-started/ngrok-tunnel.md)] + +--- + +[!INCLUDE [Azure web authentication](../includes/get-started/azure-web-authentication.md)] + +[!INCLUDE [Client secret](../includes/get-started/create-client-secret.md)] + +**Add API permissions** + +1. In the left pane, select **API permissions**. + +1. 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."::: + +1. Select **Microsoft Graph**. + +1. Select **Delegated permissions**. + +1. Select **User** > **User.Read**. + +1. 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. + +[!INCLUDE [Application ID URI](../includes/get-started/application-id-uri.md)] + +[!INCLUDE [Azure add scope](../includes/get-started/azure-add-scope.md)] + +[!INCLUDE [Azure client application](../includes/get-started/azure-client-application.md)] + +[!INCLUDE [Manifest](../includes/get-started/azure-manifest.md)] + +### Create your bot + +[!INCLUDE [Azure bot resource](../includes/get-started/azure-bot-resource.md)] + +[!INCLUDE [Teams channel](../includes/get-started/add-teams-channel.md)] + +[!INCLUDE [Messaging endpoint](../includes/get-started/messaging-endpoint.md)] + +[!INCLUDE [Service connection](../includes/get-started/oauth-connection-settings.md)] + +### Set up app settings + +1. 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."::: + +1. 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 + +1. Go to the **manifest.json** file in the cloned repository. + + :::image type="content" source="../assets/images/Tab-ME-SSO/folder-manifest.png" alt-text="Screenshot of Manifest folder with the manifest file highlighted in red."::: + +1. Open the **manifest.json** file in Visual Studio and make the following changes: + + 1. Replace `DOMAIN-NAME` with your ngrok URL. + 1. 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. + + 1. 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](#tab/vs2019) + +1. Open Visual Studio. +1. 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 the File menu and Project/Solution under Open are highlighted in red."::: + +1. 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."::: + +1. Press **F5** to run the project. + +1. 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."::: + + 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 the message that your bot is ready."::: + +# [Command line](#tab/cli) + +Go to the **csharp** folder in a Command Prompt window and enter the following command: + +```bash + dotnet run +``` + +![Dotnet](../assets/images/Tab-ME-SSO/dotnet-run1.png) + +--- + +### Upload SSO App to Teams + +1. In your cloned repository, go to **csharp** > **App SSO Sample** > **TeamsAppManifest**. + +1. 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."::: + +1. In the Teams client, select the **Apps** icon. + +1. Select **Manage your apps**. + +1. Select **Upload an app**. + +1. 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. + +1. 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 the Manifest folder with Open option to upload the Teams bot zip file highlighted in red."::: + +1. 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."::: + +1. 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 the Open option highlighted."::: + +1. 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."::: + +1. 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."::: + +1. 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."::: + +1. To sign in, if SSO isn't performed: + + 1. In the left pane of the Teams, select More added apps (●●●). + + 1. 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."::: + + 1. 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."::: + + 1. 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."::: + + 1. 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."::: + + 1. 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."::: + + 1. 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."::: + +### Complete challenge + +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 have successfully completed the step-by-step guide."::: + +You've completed the tutorial to get started with SSO for tab and message extension app. + +
+ +[Back to top](#teams-app-tutorials) + +## Build action based message extension + +
+Tutorial: 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. + +**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 have successfully completed the step-by-step guide."::: + +### Prerequisites + +Ensure that you install the following tools and set up your development environment: + +|   | Install | For using... | +| --- | --- | --- | +| 1. | [Microsoft Teams](https://www.microsoft.com/microsoft-teams/download-app) | Microsoft Teams to collaborate with everyone you work with through apps for chat, meetings, and call all in one place.| +| 2. | [Visual Studio 2022](https://visualstudio.microsoft.com) |You can install the enterprise version in Visual Studio 2022, and install the ASP.NET and web development workloads. Use the latest version. | +| 3. | [.NET Core SDK](https://dotnet.microsoft.com/en-us/download) | Customized bindings for local debugging and Azure Functions app deployments. If you haven't installed the latest version, install the portable version. | +| 4. | 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](https://ngrok.com/downloads) 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](https://ngrok.com/downloads). + +### Set up local environment + +[!INCLUDE [Set up local environment](../includes/get-started/clone-repository.md)] + +### 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. + +[!INCLUDE [Azure app registration](../includes/get-started/azure-app-registration.md)] + +**Create a tunnel** + +# [dev tunnel](#tab/dev) + +[!INCLUDE [Tunnel](../includes/get-started/dev-tunnel.md)] + +# [ngrok](#tab/ngrok) + +[!INCLUDE [Tunnel](../includes/get-started/ngrok-tunnel.md)] + +--- + +[!INCLUDE [Azure web authentication](../includes/get-started/azure-web-authentication.md)] + +[!INCLUDE [Client secret](../includes/get-started/create-client-secret.md)] + +[!INCLUDE [API Permissions](../includes/get-started/azure-api-permissions.md)] + +[!INCLUDE [Application ID URI](../includes/get-started/application-id-uri.md)] + +[!INCLUDE [Azure add scope](../includes/get-started/azure-add-scope.md)] + +[!INCLUDE [Azure client application](../includes/get-started/azure-client-application.md)] + +### Create your bot + +[!INCLUDE [Azure bot resource](../includes/get-started/azure-bot-resource.md)] + +[!INCLUDE [Teams channel](../includes/get-started/add-teams-channel.md)] + +[!INCLUDE [Messaging endpoint](../includes/get-started/messaging-endpoint.md)] + +### Set up app settings and manifest files + +1. Go to the **appsettings.json** file in cloned repository. + + :::image type="content" source="../assets/images/sbs-messagingextension-action/appsettingslocation.png" alt-text="Screenshot of cloned repository with the file path and appsettings JSON file highlighted in red."::: + +1. Open the **appsettings.json** file and update the following information: + + - Set `"MicrosoftAppType"` to **MultiTenant**. + - Set `"MicrosoftAppId"` to your bot's **Microsoft App ID**. + - Set `"MicrosoftAppPassword"` to your bot's **Value** of **Client Secret**. + - Leave `"MicrosoftAppTenantId"` blank for MultiTenant bot. + - Set `"BaseUrl"` to the fully qualified domain name. + + :::image type="content" source="../assets/images/sbs-messagingextension-action/json-file.png" alt-text="Screenshot of appsettings JSON file displaying the appsettings information."::: + +1. Go to the **manifest.json** file in the cloned repository. + + :::image type="content" source="../assets/images/sbs-messagingextension-action/manifestlocation.png" alt-text="Screenshot of Teams App Manifest folder with the file path and manifest file highlighted in red."::: + +1. Open the **manifest.json** file and make the following changes: + + - Replace the `<>` with your fully qualified domain name. + - Replace all occurrences of `<>` with your bot's **Microsoft App ID**. + + :::image type="content" source="../assets/images/sbs-messagingextension-action/botid1.png" alt-text="Screenshot of manifest page with the ID, bot ID, and Valid domains highlighted in red."::: + +### Build and run the service + +To build and run the service, use Visual Studio or Command line. + +# [Visual Studio](#tab/vs2019) + +1. Open Visual Studio. + +1. 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."::: + +1. 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."::: + +1. Press **F5** to run the project. + +1. Select **Yes** if the following dialog appears: + + :::image type="content" source="../assets/images/sbs-messagingextension-action/certificate.png" alt-text="Screenshot of Security Warning with the Yes option highlighted in red color."::: + + 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](#tab/cli) + +Go to **samples** > **msgext-action** > **csharp** in Command Prompt window and enter the following command: + +```bash + 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 + +1. In your cloned repository, go to **samples** > **msgext-action** > **csharp** > **TeamsAppManifest**. + +1. 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."::: + +1. In the Teams client, select the **Apps** icon. + +1. Select **Manage your apps**. + +1. Select **Upload an app**. + +1. 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. + +1. 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."::: + +1. 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."::: + +1. 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 + +1. 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."::: + +1. 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."::: + +1. 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."::: + +1. Select More options (...) from the overflow menu. + +1. 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."::: + +1. 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? + +:::image type="content" source="../assets/images/sbs-messagingextension-action/sharemessageoutput1.png" alt-text="Screenshot of the action based message extension output after you have successfully completed the step-by-step guide."::: + +You've completed the tutorial to get started with a **Action Message Extension** app! + +
+ +[Back to top](#teams-app-tutorials) diff --git a/msteams-platform/messaging-extensions/create-api-message-extension.md b/msteams-platform/messaging-extensions/create-api-message-extension.md index d33f4ab2845..bbb82fb8fc0 100644 --- a/msteams-platform/messaging-extensions/create-api-message-extension.md +++ b/msteams-platform/messaging-extensions/create-api-message-extension.md @@ -1160,581 +1160,7 @@ Now you've successfully created a message extension with multiple parameters. To build an API-based message extension, follow these step-by-step guides: * [For beginners](../sbs-api-msg-ext-ttk.yml): Build an API-based message extension using Agents Toolkit. -* [For advanced users](../sbs-api-based-message-extensions.yml): Build an API-based message extension from the ground up. - -
-Tutorial: Build API-based message extension - -> [!NOTE] -> API-based message extensions only support search commands. - -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. - -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 - -Here's a list of tools you need for building and deploying your apps. - -| Install | For using... | -| --- | --- | -|[Microsoft Teams](https://www.microsoft.com/microsoft-teams/download-app) | Microsoft Teams to collaborate with everyone you work with through apps for chat, meetings, or call - all in one place.| -|[Microsoft Edge](https://www.microsoft.com/edge) (recommended) or [Google Chrome](https://www.google.com/chrome/) | A browser with developer tools. | -|[Visual Studio Code](https://code.visualstudio.com/download) | JavaScript, TypeScript, or SharePoint Framework (SPFx) build environments. Use version 1.55 or later. | -|[Microsoft 365 developer account](../concepts/build-and-test/prepare-your-o365-tenant.md) | Access to Teams account with the appropriate permissions to install an app. | -|[Azure account](https://azure.microsoft.com/free/) | Access to Azure resources.| -|OpenAPI Description (OAD) document| A document that describes the capabilities of your API. For more information, see [OpenAPI Description](https://learn.openapis.org/specification/structure.html).| - -### 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: - -1. In the Teams client, select the **Apps** icon. -1. Select **Manage your apps**. -1. Select **Upload an app**. -1. 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! - -1. Go to the [Microsoft 365 developer program](https://developer.microsoft.com/microsoft-365/dev-program). -1. Select **Join Now** and follow the onscreen instructions. -1. In the welcome screen, select **Set up E5 subscription**. -1. 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="Screenshot shows the Microsoft 365 Developer Program."::: - -1. 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](https://azure.microsoft.com/free/) 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 - -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 - -```yml -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: - -1. Go to [Swagger/OpenAPI validator](https://apitools.dev/swagger-parser/) and validate the OpenAPI Description document. -1. Save the OpenAPI Description document. -1. Go to [Swagger Editor](https://editor.swagger.io/). -1. In the left pane, paste the OpenAPI Description in the editor. -1. In the right pane, select **GET**. -1. Select **Try it out**. -1. Enter the values for the **search** parameter as **Tool to create music**. -1. 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."::: - -1. Go to **Server response** > **Response Body**. -1. 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: - -1. Go to [ChatGPT](https://chat.openai.com/) and ask the following query in the message compose area: - - ```text - 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" - ] - ``` - -1. Select **Send message**. - -1. 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 - -```json -{ -"$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" - } -] -} - -``` - -
- -1. To verify if the Adaptive Card generated binds to the sample data, follow these steps: - 1. Go to [Adaptive Card Designer](https://adaptivecards.io/designer/). - 1. Go to **Select host app**, and then select **Microsoft Teams** from the dropdown. - 1. Go to **CARD PAYLOAD EDITOR** and paste the Adaptive Card template code. - 1. 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."::: - - 1. 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 - -```json - "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`](https://developer.microsoft.com/json-schemas/teams/v1.20/MicrosoftTeams.ResponseRenderingTemplate.schema.json). - -To create a response rendering template, follow these steps: - -1. Create a JSON file and add the following code to the file: - - ```json - { - "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.20/MicrosoftTeams.ResponseRenderingTemplate.schema.json", - "version": "1.0", -  "jsonPath": "", -  "responseLayout": "", -  "responseCardTemplate": { - }, - "previewCardTemplate": { - } - } - ``` - -1. Update the properties in the response rendering template as follows: - - 1. `"$schema"`: `"https://developer.microsoft.com/json-schemas/teams/v1.20/MicrosoftTeams.ResponseRenderingTemplate.schema.json"` - 1. `"version"`: `"1.0"` - - `version` is the version of the rendering template to use - - 1. `"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](https://www.newtonsoft.com/json/help/html/QueryJsonSelectToken.htm). - - 1. `"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`. - - 1. `"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. - - 1. `"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. - -1. 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 - -```json -{ - "$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: - -1. Create a new JSON file. Your app manifest must conform to the 1.20 version of the schema defined in [App manifest schema](/microsoft-365/extensibility/schema/?view=m365-app-1.24&viewFallbackFrom=m365-app-1.23%3Ftoc%3D%2Fmicrosoftteams%2Fplatform%2Ftoc.json&bc=%2Fmicrosoftteams%2Fplatform%2Fbreadcrumb%2Ftoc.json&preserve-view=true). - -1. Add the following code to the JSON file: - -
App manifest - - ```json - { - "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.20/MicrosoftTeams.schema.json", - "manifestVersion": "1.20", - "version": "1.0.3", - "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": [] - } - ``` - -
- -1. Update the app manifest properties as follows: - - * Replace `<>` 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. - -1. 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: - -1. Go to **Microsoft Teams** and sign in using your test tenant credentials. -1. Go to **Apps** > **Manage your app** > **Upload an app**. -1. Select **Upload a customized app**. -1. Select the zip file created and select **Open**. -1. 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."::: - -1. 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."::: - -1. Go to a chat, then select **+** from the message compose area, and search for your app. -1. 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."::: - -1. The app responds with an Adaptive Card in the chat window. -1. 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. - -
+* [For advanced users](../get-started/tutorials.md#build-api-based-message-extension): Build an API-based message extension from the ground up. ## See also