Tutorials

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

In this tutorial, you'll learn:

• How to set up a new project with Microsoft 365 Agents Toolkit (previously known as Teams Toolkit).
• How to build a bot app.
• How to deploy your app.

Prerequisites

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

Set up prerequisites

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

Install Microsoft 365 Agents Toolkit

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

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

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.

   

Create a free Teams developer tenant

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

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.

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

Create project workspace for your bot app

Let's create your first bot app.

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

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

In this tutorial, you learn:

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

Create your bot project workspace

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

atk new

Take a tour of the bot app source code

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

Build and run your first bot app

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

Sign in to your Microsoft 365 account

Use this account to sign in to Teams. If you're using a Microsoft 365 developer program tenant, the admin account you set up while registering is your Microsoft 365 account.

atk account login m365

Build and run your first bot app locally

To build and run your app in the local environment:

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

   Note

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

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

   In case you're wondering, when you press the F5 key, Agents Toolkit:

   1. Checks all the following prerequisites:

   • You're logged in with a Microsoft 365 account.
   • Custom app upload is enabled for your Microsoft 365 account.
   • Supported Node.js version is installed.
   • Port required by bot app is available.

   2. Install npm packages.
   3. Starts Dev Tunnel to create a 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 bot app.
   6. Registers the app in Teams Developer Portal and configures the app.
   7. Starts the bot app.
   8. Starts Teams in a web browser and uploads the custom bot app.

   

   Note

   When you run the app for the first time, all dependencies are downloaded, and the app is built. A browser window automatically opens when the build is complete. This process can take three to five minutes to complete.

   Teams runs your app in a web browser.

2. Sign in with your Microsoft 365 account, if prompted.

3. Select Add to upload the custom bot app to Teams.

   

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

   

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

   

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

   

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

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

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

   Important

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

   Tip

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

Deploy your first Teams app

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

Let's deploy the first app with Bot capability on Azure using Agents Toolkit.

Sign in to your Azure account

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

atk account login m365

atk account login azure

Provision and Deploy your app on Azure

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

Run the deployed app

Once the provisioning and deployment steps are complete:

1. Open the debug panel (Ctrl+Shift+D / ⌘⇧-D or View > Run) from Visual Studio Code.

2. Select Launch Remote (Edge) from the launch configuration dropdown.

3. Select the Start debugging (F5). You're prompted to upload the custom bot app to Teams.

   

4. Select Add.

   

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

   

   You successfully added your bot app to the Teams client.

   

Congratulations!

You've done it!

You've created a bot app.

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

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.