Tutorials

Prerequisites

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

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:

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.

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

Create your bot project workspace

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

1. Open Visual Studio Code.

2. Select the Microsoft 365 Agents Toolkit icon in the Visual Studio Code Activity Bar.

3. Select Create a New Agent/App.

   

4. Select Agents for Teams > Azure OpenAI > enter an input in Input Azure API service key now

   

5. Select Basic Agents for Teams. If you need a different functionality for your bot, select the required option.

   

6. Select the programming language as JavaScript.

   

7. Select Default folder.

   

   To change the default location, follow these steps:

   1. Select Browse.

      

   2. Select the location for the project workspace.

   3. Select Select Folder.

      

8. Enter a suitable name for your app and then select the Enter key.

   

   A dialog appears, where you need to choose yes or no to trust 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.

Build and run your AI chat bot app

Create OpenAI key and endpoint for your AI chat bot

1. Go to Azure portal.

2. Select Create a resource and search for Azure OpenAI.

3. Select Azure OpenAI and select Create.

   

4. Fill the required details and select Next.

   

5. Select All networks, including the internet, can access this resource and then select Next.

   

6. Fill the required details and select Next.

   

7. Select Create.

   

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

Get Azure OpenAI keys and endpoint

1. Select Go to resources.

   

2. Select Keys and Endpoint from the left pane and copy the KEY and Endpoint. You can copy either KEY 1 or KEY 2.

   

   Save the KEY and Endpoint for further use.

3. Select Model deployments from the left pane and select Manage Deployments.

   

   The Azure OpenAI Studio window appears.

4. Select Deployments from the left pane and select + Create new deployment.

   

5. Select the following details:

   1. Select gpt-35-turbo from the Select a model dropdown list.

      Note

      Only gpt-35-turbo model is supported for the AI chat bot.

   2. Select 0301 (Default) from the Model version dropdown list.

   3. Enter Deployment name and select Create.

      

   4. Copy and save the Deployment name for further use.

      

Update Azure OpenAI key and endpoints

1. Open your project in Visual Studio Code.

2. Under EXPLORER, go to env > .env.playground.user file.

3. Enter your SECRET_AZURE_OPENAI_API_KEY and SECRET_AZURE_OPENAI_ENDPOINT.

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

4. Go to src > app.js file.

5. Comment the OpenAI code and uncomment the Azure OpenAI code.

6. Enter your Azure OpenAI deployment name in azureDefaultDeployment.

   
   // Use OpenAI
   // apiKey: config.openAIKey,
   // defaultModel: "gpt-3.5-turbo",
   
   azureApiKey: config.azureOpenAIKey,
   azureDefaultDeployment: "gpt-35-turbo",
   azureEndpoint: config.azureOpenAIEndpoint,
   
   

Debug and run your AI chat bot app

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

   

2. Agents Playground opens your AI chat bot in a webpage.

   

Activity triggers

There are two types of activity triggers:

Predefined activity triggers

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

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.

   

   A dialog appears to preview the activity handler.

2. Select Send activity.

   

   Bot sends the following response:

   

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.

   

2. Add messageReaction to customize the activity under the type property:

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

3. Select Send activity.

   

   Bot sends an onReactionsAdded handler in response.

   

Complete challenge

Did you come up with output like this?

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

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

• Welcome messages
• Scheduled messages
• Notifications

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

Prerequisites

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

Prepare development environment

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

Install Microsoft 365 Agents Toolkit

Microsoft 365 Agents Toolkit (previously known as Teams Toolkit) helps simplify the development process with tools to provision and deploy cloud resources for your app and publish to the Teams Store.

You can use Agents Toolkit with Visual Studio Code or a command-line interface called Microsoft 365 Agents Toolkit CLI (previously known as TeamsFx CLI).

npm install -g @microsoft/m365agentstoolkit-cli

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

Set up your Teams development tenant

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

Check for upload an app option

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

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

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

2. Select Manage your apps.

3. Select Upload an app.

4. Look for the option to Upload a custom app. If the option is visible, you can upload custom apps.

   

   Note

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

Create a free Teams developer tenant (optional)

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

1. Go to the Microsoft 365 developer program.

2. Select Join Now and follow the onscreen instructions.

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

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

   

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

Build Proactive Message bot

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

1. Open Visual Studio Code.

2. Select the Microsoft 365 Agents Toolkit icon in the Visual Studio Code Activity Bar.

3. In the left pane, select View Samples.

   

4. From the list of samples, select Proactive Messaging. A prebuilt sample that's ready for debugging opens.

   

5. Select Create.

   

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

   

   If you want to change the default location, perform the following steps:

   1. Select Browse.

      

   2. Select the location for project workspace.

   3. Select Select Folder.

      

   The proactive message bot is created in a few seconds and displays the proactive message bot successful dialog in the lower-right corner with the option to debug:

   :::

7. Select Run and Debug icon from the top-left corner.

8. Select Debug (Edge) or Debug (Chrome) from the dropdown list.

   

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

9. Select Add.

   

10. Search and select the required scope or select a channel, chat, or meeting from the list, and move through the dialog to select Go.

    

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

    

11. Copy and paste the URL or navigate to the URL in browser. A proactive hello message is triggered and shared in the chat.

    

12. Go to Teams. You'll receive a proactive hello message from the bot.

    

Take a tour of the source code

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

The new project folder contains the following content:

Deploy your Proactive message bot

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

Sign in to your Azure account

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

1. Open Visual Studio Code.

2. Open the project folder where you created the proactive message bot app.

3. Select the Microsoft 365 Agents Toolkit icon in the Visual Studio Code Activity Bar.

4. Select Sign in to Azure using your credentials.

   Tip

   If you have the AZURE ACCOUNT extension installed and are using the same account, you can skip this step.

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

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

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

Deploy your app to Azure

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

atk new

atk provision

atk deploy

atk preview

Complete challenge

Did you come up with something like this?

You've completed the scenario.

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

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.

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.

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.

2. Select Manage your apps.

3. Select Upload an app.

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

   

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.

2. Select Join Now and follow the onscreen instructions.

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

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

   

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

Get a free Azure account

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

You have all the tools to set up your account. Next, let's set up your development environment and start building! Select the app you want to build first.

Create OpenAPI Description document

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

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

• The auth property must not be specified.

• JSON and YAML are the supported formats.

• OpenAPI Versions 2.0 and 3.0.x are supported.

• Teams doesn't support the oneOf, anyOf, allOf, and not (swagger.io) constructs.

• Constructing arrays for the request isn't supported, however, nested objects within a JSON request body are supported.

• The request body, if present, must be application/Json to ensure compatibility with a wide range of APIs.

• Define an HTTPS protocol server URL for the servers.url property.

• Only single parameter search is supported.

• Only one required parameter without a default value is allowed.

• Only POST and GET HTTP methods are supported.

• The OpenAPI Description document must have an operationId.

• The operation mustn't require Header or Cookie parameters without default values.

• A command must have exactly one parameter.

• Ensure that there are no remote references in the OpenAPI Description document.

• A required parameter with a default value is considered optional.

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

  OpenAPI Description

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

  Note

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

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

1. Go to Swagger or OpenAPI validator and validate the OpenAPI Description document.

2. Save the OpenAPI Description document.

3. Go to Swagger Editor.

4. In the left pane, paste the OpenAPI Description in the editor.

5. In the right pane, select GET.

6. Select Try it out.

7. Enter the values for the search parameter as Tool to create music.

8. Select Execute. The swagger editor displays a response with a list of products.

   

9. Go to Server response > Response Body.

10. Under products, copy the first product from the list and save it for future reference.

    

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 and ask the following query in the message compose area:

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

2. Select Send message.

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

   Following is an example of the Adaptive Card template:

   Adaptive Card template

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

4. To verify if the Adaptive Card generated binds to the sample data, follow these steps:

   1. Go to Adaptive Card Designer.

   2. Go to Select host app, and then select Microsoft Teams from the dropdown.

   3. Go to CARD PAYLOAD EDITOR and paste the Adaptive Card template code.

   4. Go to SAMPLE DATA EDITOR and paste the GET API response that you saved earlier.

      

   5. Select Preview mode. The Adaptive Card designer displays an Adaptive Card with the data that binds the response to the template.

      

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:

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

Response rendering template

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

To create a response rendering template, follow these steps:

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

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

2. Update the properties in the response rendering template as follows:

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

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

{
    "$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.

2. Add the following code to the JSON file:

   App manifest

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

3. Update the app manifest properties as follows:

   • Replace <<YOUR-MICROSOFT-APP-ID>> with bot's Microsoft App ID.
   • Update the value for composeExtensionType to apiBased.
   • Update the value for apiSpecificationFile to the path of your OpenAPI Description file.
   • Update the value for commands.id to searchTools.
   • Update the value for commands.title to Search for AI Tools.
   • Update the value for commands.description to Search for AI Tools.
   • Update the value for parameters.name to search. If there are no parameters, then the values must be query parameters or properties.name if referencing a property in the request body schema.
   • Update the apiResponseRenderingTemplateFile to the path of your response rendering template file.
   • Update the value for validDomains to the service URL endpoint defined in the OpenAPI Description file.

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

2. Go to Apps > Manage your app > Upload an app.

3. Select Upload a customized app.

4. Select the zip file created and select Open.

5. Select Add.

   

6. Select Open.

   

7. Go to a chat, then select + from the message compose area, and search for your app.

8. Select the app and make a search query.

   

9. The app responds with an Adaptive Card in the chat window.

10. Select Send.

    

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

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:

Prerequisites

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

Set up local environment

1. Open Microsoft-Teams-Samples.

2. Select Code.

3. From the dropdown menu, select Open with GitHub Desktop.

   

4. Select Clone.

Register Microsoft Entra app

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

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

Add App registration

1. Go to Azure portal.

2. Select App registrations.

   

3. Select + New registration.

   

4. Enter the name of your app.

5. Select Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant).

6. Select Register.

   

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

   

   Note

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

Create a tunnel

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

ngrok http --host-header=localhost 3978

Add web authentication

1. In the left pane, under Manage, select Authentication.

2. Select Add a platform > Web.

   

3. Enter the redirect URI for your app by appending auth-end to the fully qualified domain name. For example, https://your-devtunnel-domain/auth-end or https://your-ngrok-domain/auth-end.

4. Under Implicit grant and hybrid flows, select the Access tokens and ID tokens checkboxes.

5. Select Configure.

   

6. Under Web, select Add URI.

7. Enter https://token.botframework.com/.auth/web/redirect.

8. Select Save.

   

Create a client secret

1. In the left pane, under Manage, select Certificates & secrets.

2. Under Client secrets, select + New client secret.

   

   The Add a client secret window appears.

3. Enter Description.

4. Select Add.

   

5. Under Value, select Copy to clipboard to save the client secret value for further use.

   

Add API permissions

1. In the left pane, select API permissions.

2. Select + Add a permission.

   

3. Select Microsoft Graph.

4. Select Delegated permissions.

5. Select User > User.Read.

6. Select Add permissions.

   

   Note

   • If an app isn't granted IT admin consent, users must provide consent the first time they use an app.
   • Users need to consent to the API permissions only if the Microsoft Entra app is registered in a different tenant.

Add application ID URI

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

2. Next to Application ID URI, select Add.

   

3. Update the Application ID URI in the api://botid-{AppID} format and select Save.

   

Add a scope

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

2. Select + Add a scope.

   

3. Enter access_as_user as the Scope name.

4. Under Who can consent?, select Admins and users.

5. Update the values for the rest of the fields as follows:

   • Enter Teams can access the user’s profile as Admin consent display name.

   • Enter Allows Teams to call the app’s web APIs as the current user as Admin consent description.

   • Enter Teams can access the user profile and make requests on the user’s behalf as User consent display name.

   • Enter Enable Teams to call this app’s APIs with the same rights as the user as User consent description.

6. Ensure that State is set to Enabled.

7. Select Add scope.

   The following image shows the fields and the values:

   

   Note

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

   

Add client application

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

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

2. Select + Add a client application.

   

3. Add Teams mobile or desktop and Teams web application.

   1. For Teams mobile or desktop: Enter the Client ID as 1fec8e78-bce4-4aaf-ab1b-5451cc387264.

      

   2. For Teams web: Enter the Client ID as 5e3ce6c0-2b1f-4285-8d4b-75ee78787346.

      

4. Select the Authorized scopes checkbox.

5. Select Add application.

   

   The following image displays the Client Id:

   

Create your bot

Create an Azure bot resource

1. Go to Home.

2. Select + Create a resource.

3. In the search box, enter Azure Bot.

4. Select Enter.

5. Select Azure Bot.

6. Select Create.

   

7. Enter the bot name in Bot handle.

8. Select your Subscription from the dropdown list.

9. Select your Resource group from the dropdown list.

   

   If you don't have an existing resource group, you can create a new resource group. To create a new resource group, follow these steps:

   1. Select Create new.
   2. Enter the resource name and select OK.
   3. Select a location from New resource group location dropdown list.

   

10. Under Pricing, select Change plan.

    

11. Select FO Free > Select.

    

12. Under Microsoft App ID, select Type of App as Multi Tenant.

13. In the Creation type, select Use existing app registration.

14. Enter the App ID.

    Note

    You can't create more than one bot with the same Microsoft App ID.

15. Select Review + create.

    

16. After the validation passes, select Create.

    The bot takes a few minutes to provision.

17. Select Go to resource.

    

    You've successfully created your Azure bot.

    

Add a Teams channel

1. In the left pane, select Channels.

2. Under Available Channels, select Microsoft Teams.

   

3. Select the checkbox to accept the Terms of Service.

4. Select Agree.

   

5. Select Apply.

   

Add a messaging endpoint

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

Set up app settings and manifest files

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

   

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

   

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

   

4. Open the manifest.json file and update the following changes:

   • Replace all occurrences of "{TODO: MicrosoftAppId}" with your Microsoft App ID.
   • Set "<<domain-name>>" to your ngrok or dev tunnel domain.

   

Build and run the service

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

    dotnet run

Add Action Message Extension app to Teams

1. In your cloned repository, go to samples > msgext-action > csharp > TeamsAppManifest.

2. Create a .zip with the following files that are present in the Manifest folder:

   • manifest.json
   • icon-outline.png
   • icon-color.png

   

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

4. Select Manage your apps.

5. Select Upload an app.

6. Look for the option to Upload a custom app. If you see the option, custom app upload is enabled.

   

   Note

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

7. Select Open to upload the messaging.zip file that you created in the TeamsAppManifest folder.

   

8. Select Add.

   

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

   

Interact with the app in Teams

1. Select Create Card command from the compose box command list.

   

2. Enter your information in the modal pop-up window.

   

3. Select Submit.

   

4. Select More options (...) from the overflow menu.

5. Select More actions > Share Message.

   

6. If you want to include an image, select the Include image in Hero Card checkbox and then select Submit.

   

Complete challenge

Did you come up with something like this?

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

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:

Prerequisites for building a bot

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

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.

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.

2. Select Manage your apps.

3. Select Upload an app

4. Look for the option Upload a custom app. If you see the option, custom app upload is enabled.

   

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.

2. Select Join Now and follow the onscreen instructions.

3. In the welcome screen, select Setup E5 subscription.

4. Set up an administrator account. After you finish, the following screen displays.

   

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

Set up local environment

Follow these steps to clone the repository:

1. Open Microsoft-Teams-Samples.

2. Select Code.

3. From the dropdown menu, select Open with GitHub Desktop.

   

4. Select Clone.

Register Microsoft Entra app

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

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

Add App registration

1. Go to Azure portal.

2. Select App registrations.

   

3. Select + New registration.

   

4. Enter the name of your app.

5. Select the tenant option, as required.

6. Select Register.

   

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

   

   Note

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

Create a tunnel

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

ngrok http --host-header=localhost 3978

Add web authentication

1. In the left pane, under Manage, select Authentication.

2. Select Add a platform > Web.

   

3. Enter the redirect URI for your app by appending auth-end to the fully qualified domain name. For example, https://your-devtunnel-domain/auth-end or https://your-ngrok-domain/auth-end.

4. Under Implicit grant and hybrid flows, select the Access tokens and ID tokens checkboxes.

5. Select Configure.

   

6. Under Web, select Add URI.

7. Enter https://token.botframework.com/.auth/web/redirect.

8. Select Save.

   

Create a client secret

1. In the left pane, under Manage, select Certificates & secrets.

2. Under Client secrets, select + New client secret.

   

   The Add a client secret window appears.

3. Enter Description.

4. Select Add.

   

5. Under Value, select Copy to clipboard to save the client secret value for further use.

   

Add API permissions

1. In the left pane, select API permissions.

2. Select + Add a permission.

   

3. Select Microsoft Graph.

4. Select Delegated permissions.

5. Select User > User.Read.

6. Select Add permissions.

   

   Note

   • If an app isn't granted IT admin consent, users must provide consent the first time they use an app.
   • Users need to consent to the API permissions only if the Microsoft Entra app is registered in a different tenant.

Add application ID URI

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

2. Next to Application ID URI, select Add.

   

3. Update the Application ID URI in the api://botid-{AppID} format and select Save.

   

Add a scope

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

2. Select + Add a scope.

   

3. Enter access_as_user as the Scope name.

4. Under Who can consent?, select Admins and users.

5. Update the values for the rest of the fields as follows:

   1. Enter Teams can access the user’s profile as Admin consent display name.

   2. Enter Allows Teams to call the app’s web APIs as the current user as Admin consent description.

   3. Enter Teams can access the user profile and make requests on the user’s behalf as User consent display name.

   4. Enter Enable Teams to call this app’s APIs with the same rights as the user as User consent description.

6. Ensure that State is set to Enabled.

7. Select Add scope.

   The following image shows the fields and the values:

   

   Note

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

   

Add client application

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

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

2. Select + Add a client application.

   

3. Add Teams mobile or desktop and Teams web application.

   1. For Teams mobile or desktop: Enter the Client ID as 1fec8e78-bce4-4aaf-ab1b-5451cc387264.

      

   2. For Teams web: Enter the Client ID as 5e3ce6c0-2b1f-4285-8d4b-75ee78787346.

      

4. Select the Authorized scopes checkbox.

5. Select Add application.

   

   The following image displays the Client Id:

   

Update the manifest

1. In the left pane, select Manifest.

2. Set the value for the requestedAccessTokenVersion to 2 and select Save.

   

Create your bot

Create an Azure bot resource

1. Go to Home.

2. Select + Create a resource.

3. In the search box, enter Azure Bot.

4. Select Enter.

5. Select Azure Bot.

6. Select Create.

   

7. Enter the bot name in Bot handle.

8. Select your Subscription from the dropdown list.

9. Select your Resource group from the dropdown list.

   

   If you don't have an existing resource group, you can create a new resource group. To create a new resource group, follow these steps:

   1. Select Create new.
   2. Enter the resource name and select OK.
   3. Select a location from New resource group location dropdown list.

   

10. Under Pricing, select Change plan.

    

11. Select FO Free > Select.

    

12. Under Microsoft App ID, select Type of App as Multi Tenant.

13. In the Creation type, select Use existing app registration.

14. Enter the App ID.

    Note

    You can't create more than one bot with the same Microsoft App ID.

15. Select Review + create.

    

16. After the validation passes, select Create.

    The bot takes a few minutes to provision.

17. Select Go to resource.

    

    You've successfully created your Azure bot.

    

Add a Teams channel

1. In the left pane, select Channels.

2. Under Available Channels, select Microsoft Teams.

   

3. Select the checkbox to accept the Terms of Service.

4. Select Agree.

   

5. Select Apply.

   

Add a messaging endpoint

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

Add an OAuth connection settings

1. In the left pane, select Configuration.

2. Select Add OAuth Connection Settings.

3. Under New Connection Setting, update the following details:

   • Name: Enter a name for your new connection setting. You can use the name in the settings of your bot service code.
   • Service Provider: From the dropdown list, select Azure Active Directory v2.
   • Client id: Update your Microsoft App ID.
   • Client secret: Update the client secrets Value.
   • Token Exchange URL: Update the Application ID URI.
   • Tenant ID: Enter Common.
   • Scopes: Enter User.Read.

4. Select Save.

   

Set up app settings and manifest files

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

   

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

   

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

   

4. Open the manifest.json file and update the following changes:

   • Replace all occurrences of "{TODO: MicrosoftAppId}" with your Microsoft App ID.
   • Set "<<domain-name>>" to your ngrok or dev tunnel domain.

   

Build and run the service

1. Open Visual Studio.

2. Go to File > Open > Project/Solution....

   

3. From bot-conversation-sso-quickstart > csharp_dotnetcore folder, and select BotConversationSsoQuickstart.sln file.

   

4. Select F5 to run the project.

5. If a Security Warning dialog appears, select Yes.

   

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

   Note

   This page appears only when you navigate to the localhost URL.

   

   Troubleshooting

   If you get the Unable to find package error, follow these steps:

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

Upload the bot in Teams

1. In your cloned repository, go to Microsoft-Teams-Samples > samples > bot-conversation-sso-quickstart > csharp_dotnetcore > TeamsApp > appPackage.

2. Create a .zip file with the following files that are present in the appPackage folder:

   • manifest.json
   • outline.png
   • color.png

   

3. Go to Microsoft Teams.

   1. In the Teams client, select Apps.
   2. Select Manage your apps.
   3. Select Upload an app.
   4. Look for the option to Upload a custom app.

   

4. Select Open to upload the .zip file that you've created in the Manifest folder.

   

5. Select Add to add the bot to your chat.

   

6. Select Open.

   

   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.

7. Send a message to the bot. The conversation bot asks for consent for the first time.

8. For desktop: Select Continue to give permissions to Teams client for accessing the bot.

   

   Note

   Now you’ve configured SSO with your bot app and it's the only time you'll have to give consent.

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

   

Did you come up with something like this?

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

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

Prerequisites

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

Prepare development environment

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

Install Microsoft 365 Agents Toolkit

Microsoft 365 Agents Toolkit (previously known as Teams Toolkit) helps simplify the development process with tools to provision and deploy cloud resources for your app and publish to the Teams Store.

You can use Agents Toolkit with Visual Studio Code or a command-line interface called Microsoft 365 Agents Toolkit CLI (previously known as TeamsFx CLI).

npm install -g @microsoft/m365agentstoolkit-cli

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

Set up your Teams development tenant

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

Check for upload an app option

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

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

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

2. Select Manage your apps.

3. Select Upload an app.

4. Look for the option to Upload a custom app. If the option is visible, you can upload custom apps.

   

   Note

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

Create a free Teams developer tenant (optional)

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

1. Go to the Microsoft 365 developer program.

2. Select Join Now and follow the onscreen instructions.

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

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

   

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

Get a free Azure account

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

Create project workspace for your message extension app

Now, let's create your first message extension app.

The message extension capability lets you interact with a web service through buttons and forms. Use the message compose area, command box, or a message directly in Teams client to search and initiate actions in an external system. Message extensions rely on bots to provide a dialog between the user and your code.

There are two types of Teams message extensions:

• Search commands: You can search external systems and insert the results into a message in the form of a card.
• Action commands: You can present your users with a modal pop-up to collect or display information. Then, you can process their interaction and send the information back to Teams.

Let's create a message extension app with a search command. First, set up a new Teams project for creating the message extension app.

In this tutorial, you'll learn:

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

Create your message extension project workspace

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

Take a tour of the message extension app source code

A message extension uses Bot Framework to interact with your service through a conversation. After scaffolding, view the project directories and files under EXPLORER.

Build and run your first message extension app

After you set up your project workspace with Agents Toolkit, it's time to build your project. You need to sign in to your Microsoft 365 account.

Sign in to your Microsoft 365 account

Sign in with the admin account you created while joining the Microsoft 365 developer program.

Build and run your app in the local environment

Now you can build and debug your first Teams message extension app locally.

Build and run your app locally

1. Select the F5 key in Visual Studio Code to run your application in debug mode.

   Note

   If Agents Toolkit is unable to verify a particular prerequisite, it prompts you to check.

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

   When you select F5, Agents Toolkit performs the following functions:

   1. Checks the following prerequisites:

      1. You're signed in with a Microsoft 365 account.
      2. Custom app upload is enabled for your Microsoft 365 account.
      3. Supported Node.js version is installed.
      4. Port required by bot app is available.

   2. Installs npm packages

   3. Starts Dev Tunnel to create an HTTP tunnel.

   4. Registers the app in Microsoft Entra ID and configures the app.

   5. Registers the bot app in Bot Framework and configures the app.

   6. Registers the app in Teams Developer Portal and configures the app.

   7. Starts the message extension app hosted locally.

   8. Starts Teams in a web browser and uploads the Teams app.

   

   When you debug the app for the first time, Teams downloads the dependencies and builds the app. This process can take 3 to 5 minutes to complete.

2. Teams opens in a browser window when the build is complete. Sign in with your Microsoft 365 account, if prompted.

3. A dialog box opens to let you add the message extension app to Teams. Select Add.

   

   Teams loads the message extension app.

   

   As message extension apps rely on bots for enabling communication between the user and the web service, your app loads in to a chat feature of a bot.

   • If you created a bot app before you created the message extension app, Teams loads the message extension in the bot app you created. Previous chat messages of the bot app are visible.
   • If you created a message extension first, Teams loads your app in the most recent chat that is open on Teams.

Test your app

The first time your app loads, the message extension app is open for you to test. This sample app lets you search open-source npm packages from the software registry.

How to run a search query

How to open your message extension app

You tested the search feature of the message extension app in the previous step. Now, learn the different ways to open the message extension app.

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

To run your app in Teams, you must have a Microsoft 365 development account that allows custom app upload. You can learn more about custom app upload in the Prerequisites section.

Deploy your first Teams app

Let's deploy your first message extension app on Azure using Agents Toolkit.

Sign in to your Azure account

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

Deploy your app to Azure

Deployment consists of two steps. First, necessary cloud resources are created (also known as provisioning). Then, your app's code is copied into the created cloud resources. You deploy the message extension app in this tutorial.

Run the deployed app

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

1. Select the RUN AND DEBUG dropdown menu.

2. Select Launch Remote in Teams (Edge).

3. Select the ▷ button.

   

4. A dialog box opens to install your deployed app to Teams. Select Add.

   

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

   

Learn what happens when you deployed your app to Azure

Before deployment, the app runs locally.

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

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

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

Congratulations

You completed the tutorial to build a message extension app with JavaScript!

Did you come up with something like this?

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:

Prerequisites for building your app

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

Install Agents Toolkit

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

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

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

1. Select ASP.NET and web development.

2. Under installation details > Optional, select Microsoft Teams development tools.

3. Select Install.

   

4. Select Launch. Visual Studio 2022 app window appears.

   

5. Go to Extensions > Manage Extensions.

   

   The Manage Extension window appears:

   

6. From the left pane, select Installed. The Microsoft 365 Agents Toolkit extension is available.

   

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.

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.

2. Select Manage your apps.

3. Select Upload an app.

4. Look for the Upload a custom app option. If you see the option, custom app upload is enabled.

   

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.

2. Select Join Now and follow the onscreen instructions.

3. In the welcome screen, select Setup E5 subscription.

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

   

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

Get a free Azure account

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

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

Create project workspace for your tab app using C sharp

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

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

1. Open Visual Studio.

2. Select New Project.

   

3. In the search box, enter Teams.

4. Select Microsoft 365 Agents > Next.

   

5. Enter the following details to configure your new project.

6. Enter required project name in Project name.

7. Select required location to save project files and folders.

8. Select Create.

   

9. Select Tab > Create.

   

The Teams tab app is created in few seconds.

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.

2. Select Microsoft 365 Agents Toolkit > Select Microsoft 365 Account.

   

3. Select Microsoft 365 Account > Continue.

   

Build and run your app locally in Visual Studio

To build and run your app locally:

1. Select Debug > Start Debugging or select F5.

   

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

2. Select Add.

   

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

Congratulations, your first tab app is running on Teams!

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

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

Prerequisites for adding SSO to apps

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

Set up local environment

1. Open Microsoft-Teams-Samples.

2. Select Code.

3. From the dropdown menu, select Open with GitHub Desktop.

   

4. Select Clone.

Register Microsoft Entra app

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

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

Add App registration

1. Go to Azure portal.

2. Select App registrations.

   

3. Select + New registration.

   

4. Enter the name of your app.

5. Select Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant).

6. Select Register.

   

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

   

   Note

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

Create a tunnel

Select one of the following ways to create a tunnel:

ngrok http --host-header=localhost xxxx

Add a web authentication

1. In the left pane, under Manage, select Authentication.

2. Select Add a platform > Web.

   

3. Enter the redirect URI for your app by appending auth-end to the fully qualified domain name. For example, https://your-devtunnel-domain/auth-end or https://your-ngrok-domain/auth-end.

4. Under Implicit grant and hybrid flows, select the Access tokens and ID tokens checkboxes.

5. Select Configure.

   

6. Under Web, select Add URI.

7. Enter https://token.botframework.com/.auth/web/redirect.

8. Select Save.

   

Create a client secret

1. In the left pane, under Manage, select Certificates & secrets.

2. Under Client secrets, select + New client secret.

   

   The Add a client secret window appears.

3. Enter Description.

4. Select Add.

   

5. Under Value, select Copy to clipboard to save the client secret value for further use.

   

Add API permissions

1. In the left pane, select API permissions.

2. Select + Add a permission.

   

3. Select Microsoft Graph.

4. Select Delegated permissions.

5. Select User > User.Read.

6. Select Add permissions.

   

   Note

   • If an app isn't granted IT admin consent, users must provide consent the first time they use an app.
   • Users need to consent to the API permissions only if the Microsoft Entra app is registered in a different tenant.

Add Application ID URI

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

2. Next to Application ID URI, select Add.

   

3. Update the Application ID URI in the api://your-devtunnel-domain/botid-{AppID} or api://your-ngrok-domain/botid-{AppID} format and select Save.

   

   The following image shows the domain name:

   

Add a scope

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

2. Select + Add a scope.

   

3. Enter access_as_user as the Scope name.

4. Under Who can consent?, select Admins and users.

5. Update the values for the rest of the fields as follows:

   • Enter Teams can access the user’s profile as Admin consent display name.

   • Enter Allows Teams to call the app’s web APIs as the current user as Admin consent description.

   • Enter Teams can access the user profile and make requests on the user’s behalf as User consent display name.

   • Enter Enable Teams to call this app’s APIs with the same rights as the user as User consent description.

6. Ensure that State is set to Enabled.

7. Select Add scope.

   The following image shows the fields and the values:

   

   Note

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

   

Add client application

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

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

2. Select + Add a client application.

   

3. Add Teams mobile or desktop and Teams web application.

   1. For Teams mobile or desktop: Enter the Client ID as 1fec8e78-bce4-4aaf-ab1b-5451cc387264.

      

   2. For Teams web: Enter the Client ID as 5e3ce6c0-2b1f-4285-8d4b-75ee78787346.

      

4. Select the Authorized scopes checkbox.

5. Select Add application.

   

   The following image displays the Client Id:

   

Update the manifest

1. In the left pane, select Manifest.

2. Set the value for the requestedAccessTokenVersion to 2 and select Save.

   

Create a bot

Create an Azure bot resource

1. Go to Home.

2. Select + Create a resource.

3. In the search box, enter Azure Bot.

4. Select Enter.

5. Select Azure Bot.

6. Select Create.

   

7. Enter the bot name in Bot handle.

8. Select your Subscription from the dropdown list.

9. Select your Resource group from the dropdown list.

   

   If you don't have an existing resource group, you can create a new resource group. To create a new resource group, follow these steps:

   1. Select Create new.
   2. Enter the resource name and select OK.
   3. Select a location from New resource group location dropdown list.

   

10. Under Pricing, select Change plan.

    

11. Select FO Free > Select.

    

12. Under Microsoft App ID, select Type of App as Multi Tenant.

13. In the Creation type, select Use existing app registration.

14. Enter the App ID.

    Note

    You can't create more than one bot with the same Microsoft App ID.

15. Select Review + create.

    

16. After the validation passes, select Create.

    The bot takes a few minutes to provision.

17. Select Go to resource.

    

    You've successfully created your Azure bot.

    

Add a Teams channel

1. In the left pane, select Channels.

2. Under Available Channels, select Microsoft Teams.

   

3. Select the checkbox to accept the Terms of Service.

4. Select Agree.

   

5. Select Apply.

   

To add a messaging endpoint

Add an OAuth connection settings

1. In the left pane, select Configuration.

2. Select Add OAuth Connection Settings.

3. Under New Connection Setting, update the following details:

   • Name: Enter a name for your new connection setting. You can use the name in the settings of your bot service code.
   • Service Provider: From the dropdown list, select Azure Active Directory v2.
   • Client id: Update your Microsoft App ID.
   • Client secret: Update the client secrets Value.
   • Token Exchange URL: Update the Application ID URI.
   • Tenant ID: Enter Common.
   • Scopes: Enter User.Read.

4. Select Save.

   

Set up app settings

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

   

2. Open the appsettings.json file in Visual Studio.

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

   

Set up manifest file

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

   

2. Open the manifest.json file in Visual Studio and make the following changes:

   • Replace DOMAIN-NAME with your ngrok URL.

   • Replace YOUR-MICROSOFT-APP-ID with your bot's Microsoft App ID.

     Note

     Depending on the scenario [YOUR-MICROSOFT-APP-ID] and [DOMAIN-NAME] may occur multiple times.

   • Replace resource as api://*******.ngrok.io/botid-{AppID}.
     

     

Build and run the service

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

dotnet run