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 Open AI key and endpoint for your AI chat bot

1. Go to Azure portal.

2. Select Create a resource and search for Azure Open AI.

3. Select Azure Open AI 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 Open AI 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 Open AI 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 Open AI 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 Open AI 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.

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.

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:

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

   

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