Create an API-based message extension

You can create an API-based message extension using Developer Portal for Teams and Teams Toolkit for Visual Studio Code, command line interface (CLI), or Visual Studio.

Developer Portal for Teams

To create an API-based message extension using Developer Portal for Teams, follow these steps:

1. Go to Teams Developer Portal.

2. Go to Apps.

3. Select + New apps.

4. Enter a name of the app and select the Manifest version as Latest prerelease (devPreview).

5. Select Add.

   

6. In the left pane, under Configure, update the following Basic information:

   1. Full name
   2. Short description
   3. Long description
   4. Developer or company name
   5. Website (must be a valid HTTPS URL)
   6. Privacy policy
   7. Terms of use

7. Select Save.

8. Select App features.

9. Select Messaging extension.

   

10. Under Message extension type, select API.

    1. If you get a disclaimer, which reads Bot message extension is already in use by users. Would you like to change message extension type to API?. Select Yes, change.

11. Under OpenAPI spec, select Upload now.

    

12. Select the OpenAPI Description document in the JSON or YAML format and select Open.

13. Select Save. A pop-up appears with the message API spec saved successfully.

14. Select Got it.

    

Add commands

Note

Message extensions built from an API only support a single parameter.

You can add commands and parameters to your message extension, to add commands:

1. Under Message extension type, select Add.

   

   An Add command pop-up appears with a list of all the available APIs from the OpenAPI Description document.

2. Select an API from the list and select Next.

   

   A Command details appears.

3. Under Command details, go to Adaptive card template and select Upload now.

   

   Note

   If you have more than one API, ensure that you upload the Adaptive card template for each API.

4. Select the Adaptive Card template file in JSON format and select Open.

   The following attributes are updated automatically from the Adaptive Card template:

   • Command Type
   • Command ID
   • Command title
   • Parameter name
   • Parameter description

   

5. Under Details, update the Command description.

   1. If you want to launch a command using a trigger in Microsoft 365 Copilot, turn on the Automatically run the command when a user opens the extension toggle.

6. Select Add. The command is added successfully.

7. Select Save.

An API-based message extension is created.

To test your API-based message extension created in the Developer Portal for Teams, you can use the following methods:

• Preview in Teams: In Developer Portal, open your message extension and select Preview in Teams in the upper-right corner. You're redirected to Teams, where you can add the app to Teams to preview the app.

• Download app package: On the message extension page, select App package from the left pane and then, in the upper-left corner of the window, select Download app package. The app package is downloaded to your local machine in a .zip file. You can upload the app package to teams and test the message extension.

Visual Studio Code

Note

Teams Toolkit supports OpenAPI Specification version 2.0 and 3.0.x.

To build an API-based message extension using Teams Toolkit for Visual Studio Code, follow these steps:

1. Open Visual Studio Code.

2. From the left pane, Select Teams Toolkit.

3. Select Create a New App.

4. Select Message Extension.

   

5. Select Custom Search Results.

6. Select one of the following options:

   1. To build from the beginning, select Start with a new API.
   2. If you already have an OpenAPI description document, select Start with an OpenAPI Description Document.

   

7. Based on the options selected in step 6, select the following:

   New API

   Note

   The authentication flow for Microsoft Entra is only functional in remote environments. You can't test it in a local environment due to the lack of authentication support in Azure Function core tools. The repair API can be invoked anonymously in a local environment.

   1. Select the authentication type:

      • None: Select if you don't want any authentication for the user to access the API.
      • API Key: Select if you want to authenticate using an API key.
      • Microsoft Entra: Select if you want to authenticate using app user's Teams identity.

      

   2. Select a programming language.

      

   3. Select Default folder.

   4. Enter the name of your app and select Enter. Teams Toolkit creates a new plugin with API from Azure functions.

   5. To get started, you must update the source code in the following files:

      File	Contents
      src/functions/repair.ts	The main file of a function in Azure Functions. Defines an Azure Function that retrieves and filters repair records based on a query parameter from an HTTP GET request, and returns the results as a JSON response.
      src/repairsData.json	The data source for the repair API.
      src/keyGen.ts	Designed to generate an API key used for authorization.
      appPackage/apiSpecificationFile/repair.yml	A file that describes the structure and behavior of the repair API.
      appPackage/responseTemplates/repair.json	A template file for rendering API response.
      teamsapp.yml	The main Teams Toolkit project file. The project file defines two primary things: Properties and configuration Stage definitions.
      teamsapp.local.yml	Overrides teamsapp.yml with actions that enable local execution and debugging.
      aad.manifest.json	Defines the configuration of Microsoft Entra app. This template only provisions a single tenant Microsoft Entra app.

   6. Based on the options selected in step a, follow these steps:

      • If you've selected none or Microsoft Entra, skip to the next step.

      • If you've selected API key, follow these steps:

        Generate and set up your API key as follows:

        1. In Visual Studio Code, go to View > Terminal.

        2. Run the following command to install dependency packages:

           npm install
           

        3. Run the following command to generate your API key:

           npm run keygen
           

           The API key is generated as Generated a new API Key: xxx.... The generated API key is registered and recorded in the API key registration tool in Developer portal for Teams. For more information on API key registration, see Register an API key.

        4. Enter the generated API key into your env/.env.*.user file. Replace <your-api-key> with the actual key:

           SECRET_API_KEY=<your-api-key>
           

   OpenAPI Description

   1. Enter or browse the OpenAPI Description document location.

      

   2. From the API list, select the required APIs and select OK.

      Note

      GET and POST APIs are supported for API-based message extensions.

   3. Select Default folder.

   4. Enter the name of your app and select Enter. Teams Toolkit scaffolds the OpenAPI Description document and created an API-based message extension.

   5. Under LIFECYCLE, select Provision.

   6. If your OpenAPI specification document has a security scheme bearerAuth, which uses the HTTP bearer scheme, enter the API key in the command window and select Enter.

      

      Note

      The API key must be a string with 10 to 128 characters.

   Note

   Teams toolkit source file includes a security check to ensure that an incoming request is authorized. It uses a function isApiKeyValid(req) to verify if the request contains a valid API key. If the API key isn't valid, the code returns an 401 HTTP status code, indicating an Unauthorized response.

8. From the left pane, select Teams Toolkit.

9. Under ACCOUNTS, sign in with your Microsoft 365 account and Azure account if you haven't already.

   

10. From the left pane, Select Run and Debug (Ctrl+Shift+D).

11. From the launch configuration dropdown, select Preview in Teams (Edge) or Preview in Teams (Chrome). Teams Toolkit launches Teams web client in a browser window.

12. Go to a chat message and select the Actions and apps icon. In the flyout menu, search for your app.

13. Select your message extension from the list and enter a search command in the search box.

14. Select an item from the list. The item unfurls into an Adaptive Card in the message compose area.

    

15. Select Send. Teams sends the search result as an Adaptive Card in the chat message.

Teams Toolkit CLI

To create an API-based message extension using Teams Toolkit CLI, follow these steps:

1. Go to Command Prompt.

2. Enter the following command:

   npm install -g @microsoft/teamsapp-cli
   

3. Type teamsapp new in the terminal

4. Select Message Extension.

   

5. Select Custom Search Results.

6. Select Start from an OpenAPI Description Document.

7. Enter a valid URL or local path of your OpenAPI Description document.

8. Select the APIs from the list and select Enter.

   

9. Enter the location for your project and select Enter.

10. Enter the name of your application and select Enter.

    

11. Go to the folder path where your project is created and enter the following command to provision your app in Azure:

    teamsapp provision --env dev Teams Toolkit CLI opens a browser window and requests you to sign in to your Microsoft Account.

12. Sign in to your Microsoft account. Teams Toolkit CLI executes validation and provisions your app on Azure.

    

13. In the command prompt window, enter the following command to preview your app in Teams:

    Preview the app: teamsapp preview --env dev

A new browser window with Teams web client opens. You can add your app to Teams.

Visual Studio

Before you get started, ensure that you install Visual Studio Enterprise 2022 Preview version 17.9.0 Preview 1.0 and install the Microsoft Teams development tools under ASP.NET and web development workload.

To create an API-based message extension using Teams Toolkit for Visual Studio, follow these steps:

1. Open Visual Studio.

2. Go to File > New > Project... or New Project.

3. Search for Teams and select Microsoft Teams App.

   

4. Enter the Project name and Location.

5. Select Create.

   

6. Select Search Results from API.

7. Select any of the following options:

   • If you want to start without an API, select Start with a new API.
   • If you have an existing OpenAPI Description document, select Start with an OpenAPI Description.

8. Select Next.

   

9. Based on the options selected in step 7, select the following:

   New API

   1. To get started, you must update the source code in the following files:

      File	Contents
      Repair.cs	The main file of a function in Azure Functions. Defines an Azure Function that retrieves and filters repair records based on a query parameter from an HTTP GET request, and returns the results as a JSON response.
      RepairData.cs	The data source for the repair API. Contains a method that returns a hardcoded list of car repair tasks.
      Models/RepairModel.cs	Defines a data model that represents a repair task with properties such as ID, Title, Description, AssignedTo, Date, and Image.
      appPackage/apiSpecificationFile/repair.yml	A file that describes the structure and behavior of the repair API.
      appPackage/responseTemplates/repair.json	A generated Adaptive Card that used to render API response.
      appPackage/responseTemplates/repair.data.json	The data source for the repair API.
      teamsapp.yml	The main Teams Toolkit project file. The project file defines two primary things: Properties and configuration Stage definitions.
      teamsapp.local.yml	Overrides teamsapp.yml with actions that enable local execution and debugging.

   2. After you've updated the source code, in the debug dropdown menu, select Dev Tunnels (no active tunnel) > Create a Tunnel....

      

   3. Select an account to create the tunnel. The supported account types are Azure, Microsoft Account (MSA), and GitHub.

      1. Name: Enter a name for the tunnel.
      2. Tunnel Type: Select Persistent or Temporary.
      3. Access: Select Public.
      4. Select OK. Visual Studio displays a confirmation message that a tunnel is created.

      The tunnel you created is listed under Dev Tunnels.

   4. Go to Solution Explorer and select your project.

   5. Right-click the menu and select Teams Toolkit > Prepare Teams App Dependencies.

      If prompted, sign in with a Microsoft 365 account. A message appears that the app is successfully prepared.

   6. Select the F5 key or select Debug > Start Debugging. Visual Studio launches a Teams web client.

   OpenAPI Description

   1. Enter OpenAPI specification URL or select Browse.. to upload a file from your local machine.

   2. Select the dropdown and select the APIs from the list.

   3. Select Create. The project is scaffolded and you can find API specification, manifest, and response template files in the appPackage folder.

   4. Go to Solution Explorer and select your project.

   5. Right-click the menu and select Teams Toolkit > Provision in the Cloud.

      

      If prompted, sign in with a Microsoft 365 account. A message appears that the app is successfully prepared.

   6. Right-click your project and select Teams Toolkit > Preview in > Teams.

   7. Select the manifest.json file and select Open. Visual Studio launches a Teams web client.

10. Go to a chat and select Actions and apps.

11. From the message extension fly-out menu, enter the name of your message extension in the search box.

12. Select the message extension and enter your search query.

    

13. Select an item from the list. The item unfurls into an Adaptive Card in the message compose area.

14. Select Send. Teams sends the search result as an Adaptive Card in the chat message.

    

Step-by-step guides

To build an API-based message extension, follow these step-by-step guides:

• For beginners: Build an API-based message extension using Teams Toolkit.
• For advanced users: Build an API-based message extension from the ground up.