diff --git a/msteams-platform/messaging-extensions/api-based-overview.md b/msteams-platform/messaging-extensions/api-based-overview.md
index b352b1df4d0..5a37341f0af 100644
--- a/msteams-platform/messaging-extensions/api-based-overview.md
+++ b/msteams-platform/messaging-extensions/api-based-overview.md
@@ -14,12 +14,12 @@ ms.date: 02/26/2025
> [!NOTE]
>
> * API-based message extensions support only search commands.
-> * API-based message extensions aren't supported in Microsoft 365 Copilot. If you want to create API-based message extensions compatible with Microsoft 365 Copilot, see [API agents for Microsoft 365 Copilot](/microsoft-365-copilot/extensibility/overview-api-plugins).
+> * API-based message extensions aren't supported in Microsoft 365 Copilot. If developers want to create API-based message extensions compatible with Microsoft 365 Copilot, see [API agents for Microsoft 365 Copilot](/microsoft-365-copilot/extensibility/overview-api-plugins).
-Message extensions built using API (API-based) use a web service to manage user requests and responses and don't require a bot registration. API-based message extensions are a Microsoft Teams app capability that integrates external APIs directly into Teams, enhancing your app's usability and offering a seamless user experience. API-based message extensions support search commands and can be used to fetch and display data from external services within Teams, streamlining workflows by reducing the need to switch between applications. API-based message extensions help your apps to interact directly with third-party data, apps, and services, enhancing its capabilities. With API-based message extension, you can:
+API-based message extensions use a web service to manage user requests and responses without requiring a bot registration. This Microsoft Teams app capability integrates external APIs directly into Teams, enhancing app usability and delivering a seamless user experience. API-based message extensions support search commands and enable developers to fetch and display data from external services within Teams, streamlining workflows by reducing application switching. They allow apps to interact directly with third-party data, applications, and services, extending functionality. With an API-based message extension, developers can:
-* Retrieve real-time information, such as latest news coverage on a product launch.
-* Retrieve knowledge-based information, for example, my team’s design files in Figma.
+* Retrieve real-time information, such as the latest news coverage on a product launch.
+* Retrieve knowledge-based information, for example, team design files in Figma.
See the video to learn more about building an API-based message extension using Microsoft 365 Agents Toolkit (previously known as Teams Toolkit):
@@ -31,45 +31,38 @@ See the video to learn more about building an API-based message extension using
|Traditional bot-based message extensions |API-based message extensions |
|---------|---------|
-|Developers need to build, deploy, and maintain a service to handle invoke commands from the Teams client. | If the end-service's APIs can be described using the OpenAPI Specification, developers can eliminate the need for the middle-layer handling service. |
-|This service processes the incoming query and makes a call to the developer’s end-service. | Teams can directly use the [OpenAPI Specification](https://swagger.io/resources/open-api/) to build requests and communicate with the developer's end-service. |
+|Developers need to build, deploy, and maintain a service to handle invoke commands from the Teams client. |If the end-service's APIs can be described using the OpenAPI Specification, developers eliminate the need for a middle-layer handling service. |
+|This service processes the incoming query and calls the developer’s end-service. |Teams directly use the [OpenAPI Specification](https://swagger.io/resources/open-api/) to build requests and communicate with the developer's end-service. |
-The following images show the flow of user queries through Traditional message extensions and API message extensions:
+The images illustrate the flow of user queries through Traditional message extensions and API message extensions:
-:::image type="content" source="../assets/images/Copilot/api-based-me-flow.png" alt-text="Screenshot shows user query flow between a user, Teams Client, and Teams bot service using Traditional message extensions. The diagram also shows how the API spec, the rendering templates, the API relate to each other." lightbox="../assets/images/Copilot/api-based-me-flow.png":::
-*User query flow using Traditional Message Extensions. The developer must maintain a custom bot handler service, which handles the requests from a Teams bot. The handler service sends a request to the developer’s service when a query is invoked.*
+:::image type="content" source="../assets/images/Copilot/api-based-me-flow.png" alt-text="Screenshot shows user query flow between a user, Teams Client, and Teams bot service using Traditional message extensions. The diagram also shows how the API spec, the rendering templates, and the API relate to each other." lightbox="../assets/images/Copilot/api-based-me-flow.png":::
+*User query flow using Traditional Message Extensions. Developers must maintain a custom bot handler service that processes requests from a Teams bot. The handler service sends a request to the developer’s service upon query invocation.*
-:::image type="content" source="../assets/images/Copilot/api-based-me-flow-2.png" alt-text="Screenshot shows the query flow between a user, Teams Client, and Teams bot service using API Message Extensions. The diagram also shows how the API spec, the rendering templates, the API relate to each other." lightbox="../assets/images/Copilot/api-based-me-flow-2.png":::
-*User query flow using API Message Extensions. There's no need for a developer maintained handler service as long as the interaction is clearly outlined in the OpenAPI Specification in the App Package.*
+:::image type="content" source="../assets/images/Copilot/api-based-me-flow-2.png" alt-text="Screenshot shows the query flow between a user, Teams Client, and Teams bot service using API Message Extensions. The diagram also shows how the API spec, the rendering templates, and the API relate to each other." lightbox="../assets/images/Copilot/api-based-me-flow-2.png":::
+*User query flow using API Message Extensions. No developer-maintained handler service is required if the interaction is clearly outlined in the OpenAPI Specification in the App Package.*
-Here's a high-level sequence of events that occur during a query command invocation:
+The high-level sequence of events during a query command invocation is as follows:
-1. When a user invokes a query command, the parameters of the query command are received by the Teams Bot Service.
-
-1. The query command is defined inside the app manifest file. The command definition contains a reference to the `operationId` inside the OpenAPI Specification file along with the details of the parameters that the Teams client renders for that command. For reference, the `operationId` inside the OpenAPI Specification file is unique to a particular HTTP operation.
-
-1. The Teams Bot Service then uses the parameters supplied by the user along with the copy of the OpenAPI Specification for the associated `operationId` to build an HTTP request for the developer’s endpoint.
-
-1. If authentication is required and is configured in the manifest. It's resolved to the appropriate token or key. This token or key is used as part of the outgoing request. *[Optionally]*
-
-1. The Teams bot service performs the HTTP request to the developer’s service.
-
-1. The developer’s service should respond in accordance with the schema outlined in the OpenAPI Specification. This is in JSON format.
-
-1. The Teams client must show the results back to the user. To convert the JSON results from the previous step to UI, the Teams bot service uses the response Rendering template to build an Adaptive Card for each result.
-
-1. The Adaptive Cards are sent to the client, which renders them in the UI.
+1. A user invokes a query command, and Teams Bot Service receives the command parameters.
+2. The query command, defined in the app manifest file, references an `operationId` inside the OpenAPI Specification file and details the parameters rendered by the Teams client. The `operationId` in the OpenAPI Specification file uniquely identifies a particular HTTP operation.
+3. Teams Bot Service uses the user-supplied parameters along with the OpenAPI Specification copy for the associated `operationId` to build an HTTP request for the developer’s endpoint.
+4. If authentication is configured in the manifest and required, the process resolves it to the appropriate token or key, which then becomes part of the outgoing request. *[Optionally]*
+5. Teams Bot Service performs the HTTP request to the developer’s service.
+6. The developer’s service responds in accordance with the schema specified in the OpenAPI Specification in JSON format.
+7. Teams client displays the results back to the user. Teams Bot Service converts the JSON results to UI elements using the response Rendering template to build an Adaptive Card for each result.
+8. Teams client renders the Adaptive Cards in the UI.
:::image type="content" source="../assets/images/Copilot/api-based-me-query-sequence-diagram.png" alt-text="Diagram shows the high-level sequence flow when a query is invoked in an API-based message extension." lightbox="../assets/images/Copilot/api-based-me-query-sequence-diagram.png":::
## Prerequisites
-The app definition package includes various compelling artifacts that support the functionality of this feature. Before you get started, ensure that have a basic understanding of the following files:
+The app definition package includes several artifacts that support this feature. Before proceeding, ensure an understanding of the following files:
> [!div class="checklist"]
>
@@ -79,128 +72,128 @@ The app definition package includes various compelling artifacts that support th
### OpenAPI Description (OAD)
-OpenAPI description documenat is an adopted industry standard for describing APIs. It allows you to abstract your APIs from their implementation, providing language-agnostic definitions that are both human-readable and machine-readable. The OpenAPI description documenat outlines the interactions your extension supports, enabling Teams to build requests and communicate directly with your service without the need for a middle-layer handling service.
+The OpenAPI description document is an industry-standard model for describing APIs. It abstracts APIs from their implementation, providing language-agnostic definitions that are human-readable and machine-readable. The document outlines the interactions the extension supports, allowing Teams to build requests and communicate directly with the service without a middle-layer handling service.
-An OpenAPI description document contains details to communicate with the developer’s service. Ensure that you adhere to following guidelines for OpenAPI Description (OAD) document:
+The document contains details for communicating with the developer’s service. Developers must adhere to the following guidelines for the OpenAPI Description (OAD) document:
* OpenAPI versions 2.0 and 3.0.x are supported.
-* JSON and YAML are the supported formats.
+* JSON and YAML formats are supported.
* The request body, if present, must be application/Json.
-* Define an HTTPS protocol server URL for the `servers.url` property.
+* Define an HTTPS protocol server URL for the servers.url property.
* Only POST and GET HTTP methods are supported.
-* The OpenAPI Description document must have an `operationId`.
+* The OpenAPI Description document must include an `operationId`.
* Only one required parameter without a default value is allowed.
* A required parameter with a default value is considered optional.
* Users must not enter a parameter for a header or cookie.
-* The operation must not have a required header or cookie parameters without default values.
-* Ensure that there are no remote references in the OpenAPI Description document.
+* The operation must not have required header or cookie parameters without default values.
+* Avoid remote references in the OpenAPI Description document.
* Constructing arrays for the request isn’t supported; however, nested objects within a JSON request body are supported.
-* Teams doesn't support the `oneOf`, `anyOf`, `allOf`, and `not` (swagger.io) constructs.
+* Teams doesn't support the oneOf, anyOf, allOf, and not (swagger.io) constructs.
-The following code is an example of an OpenAPI Description document:
+The following code provides an example of an OpenAPI Description document:
Sample OpenAPI Description document
```yml
openapi: 3.0.1
info:
-title: OpenTools Plugin
-description: A plugin that allows the user to find the most appropriate AI tools for their use cases, with their pricing information.
-version: 'v1'
+ 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, ?search="tool to create music" will give 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'
+ /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, ?search="tool to create music" will give 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.
+ 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.
```
-For more information on how to write OpenAPI definitions in YAML, see [OpenAPI structure.](https://swagger.io/docs/specification/basic-structure/)
+Developers refer to [OpenAPI structure.](https://swagger.io/docs/specification/basic-structure/) for details on writing OpenAPI definitions in YAML.
### App manifest
-App manifest is a blueprint for your Teams app, defining how and where the message extension is invoked within the Teams client. It includes the commands your extension supports and the locations from which they can be accessed, such as the compose message area, command bar, and message. The manifest links to the OpenAPI Specification and the Response Rendering Template to ensure proper functionality.
+The app manifest serves as the blueprint for a Teams app. It defines how and where the message extension is invoked within the Teams client. The manifest includes the supported commands and the locations from which they can be accessed, such as the compose message area, command bar, and message. It links to the OpenAPI Specification and the Response Rendering Template to ensure proper functionality.
-App manifest contains query command definition. Ensure that you adhere to following guidelines for app manifest:
+The app manifest contains the query command definition. Developers must adhere to the following guidelines for the app manifest:
-* Set the app manifest version to `1.17`.
-* Set `composeExtensions.composeExtensionType` to `apiBased`.
-* Define `composeExtensions.apiSpecificationFile` as the relative path to the OpenAPI Description document within the folder. This links the app manifest to the API specification.
-* Define `apiResponseRenderingTemplateFile` as the relative path to the response rendering template. This specifies the location of the template used for rendering API responses.
-* Each command must have a link to the response rendering template. This connects each command to its corresponding response format.
-* The `Commands.id` property in the app manifest must match the `operationId` in the OpenAPI Description document.
-* If a required parameter is without a default value, the command `parameters.name` in the app manifest must match the `parameters.name` in the OpenAPI description document.
-* If there’s no required parameter, the command `parameters.name` in the app manifest must match the optional `parameters.name` in the OpenAPI Description document.
-* Ensure that the name of parameters for each command in the app manifest match exactly with the corresponding name of the parameter defined for the operation in the OpenAPI Description document.
-* A response rendering template must be defined per command, which is used to convert responses from an API.
+* Set the app manifest version to 1.17.
+* Set composeExtensions.composeExtensionType to apiBased.
+* Define composeExtensions.apiSpecificationFile as the relative path to the OpenAPI Description document within the folder. This links the app manifest to the API specification.
+* Define apiResponseRenderingTemplateFile as the relative path to the response rendering template. This specifies the location of the template used for rendering API responses.
+* Each command must include a link to a response rendering template. This associates each command with its corresponding response format.
+* The Commands.id property in the app manifest must match the operationId in the OpenAPI Description document.
+* If a required parameter is without a default value, the command parameters.name in the app manifest must match the parameters.name in the OpenAPI Description document.
+* If no parameter is required, the command parameters.name in the app manifest must match the optional parameters.name in the OpenAPI Description document.
+* The names for parameters in each command of the app manifest must exactly match their corresponding names in the OpenAPI Description document.
+* A response rendering template is required for each command to convert API responses to UI elements.
* The command and parameter descriptions must not exceed 128 characters.
-The following is an app manifest example with definitions for API-based message extensions:
+The following provides a sample app manifest with definitions for API-based message extensions:
App manifest example
@@ -272,33 +265,35 @@ The following is an app manifest example with definitions for API-based message
|Name |Description |
|:---------| ---------------------------------------------------------|
-|`composeExtensions.composeExtensionType` | Compose extension type. Update the value to `apiBased`. |
-|`composeExtensions.authorization`|Authorization related information for the API-based message extension|
-|`composeExtensions.authorization.authType`|Enum of possible authorization types. Supported values are `none`, `apiSecretServiceAuth`, and `microsoftEntra`.|
-|`composeExtensions.authorization.apiSecretServiceAuthConfiguration`|Object capturing details needed to do service auth. Applicable only when auth type is `apiSecretServiceAuth`.|
-|`composeExtensions.authorization.apiSecretServiceAuthConfiguration.apiSecretRegistrationId`| Registration ID returned when developer submits the API key through Developer Portal.|
-|`composeExtensions.apiSpecificationFile` | References an OpenAPI Description file in the app package. Include when type is `apiBased`. |
-|`composeExtensions.commands.id` | Unique ID that you assign to search command. The user request includes this ID. The ID must match the `operationId` available in the OpenAPI Description. |
-|`composeExtensions.commands.context` | Array where the entry points for message extension is defined. The default values are `compose` and `commandBox`. |
-|`composeExtensions.commands.parameters` | Defines a static list of parameters for the command. The name must map to the `parameters.name` in the OpenAPI Description. If you're referencing a property in the request body schema, then the name must map to `properties.name` or query parameters. |
-|`composeExtensions.commands.apiResponseRenderingTemplateFile`| Template used to format the JSON response from developer’s API to Adaptive Card response. *[Mandatory]* |
-
-For more information, see [composeExtensions](../resources/schema/manifest-schema-dev-preview.md#composeextensions).
+|`composeExtensions.composeExtensionType` | Compose extension type. Update the value to apiBased. |
+|`composeExtensions.authorization`|Authorization related information for the API-based message extension.|
+|`composeExtensions.authorization.authType`|Enum of possible authorization types. Supported values are none, apiSecretServiceAuth, and microsoftEntra.|
+|`composeExtensions.authorization.apiSecretServiceAuthConfiguration`|Object capturing details needed to do service auth. Applicable only when auth type is apiSecretServiceAuth.|
+|`composeExtensions.authorization.apiSecretServiceAuthConfiguration.apiSecretRegistrationId`| Registration ID returned when a developer submits the API key through Developer Portal.|
+|`composeExtensions.apiSpecificationFile` | References an OpenAPI Description file in the app package. Include when type is apiBased. |
+|`composeExtensions.commands.id` | Unique ID assigned to the search command. The user request includes this ID. The ID must match the operationId available in the OpenAPI Description. |
+|`composeExtensions.commands.context` | Array defining the entry points for the message extension. The default values are compose and commandBox. |
+|`composeExtensions.commands.parameters` | Static list of parameters for the command. The name must map to parameters.name in the OpenAPI Description. If referencing a property in the request body schema, the name must map to properties.name or query parameters. |
+|`composeExtensions.commands.apiResponseRenderingTemplateFile`| Template used to format the JSON response from the developer’s API into an Adaptive Card response. *[Mandatory]* |
+
+Developers refer to [composeExtensions](../resources/schema/manifest-schema-dev-preview.md#composeextensions) for more details.
### Response rendering template
-Response rendering template is a predefined format that dictates how the results from your API are displayed within Teams. It uses templates to create Adaptive Cards or other UI elements from the API’s response, ensuring a seamless and integrated user experience within Teams. The template defines the layout and style of the information presented, which can include text, images, and interactive components. Ensure that you adhere to following guidelines for response rendering template:
+The response rendering template defines how the API results display within Teams. It uses templates to create Adaptive Cards or other UI elements from the API’s response, ensuring an integrated user experience. The template outlines layout and style details, including text, images, and interactive elements. Developers must adhere to the following guidelines for the response rendering template:
-* Define the schema reference URL in the `$schema` property to establish the structure of your template to the [response rendering template schema](https://developer.microsoft.com/json-schemas/teams/v1.17/MicrosoftTeams.ResponseRenderingTemplate.schema.json).
-* The supported values for `responseLayout` are `list` and `grid`, which determine how the response is visually presented. For more information on the layout, see [respond to user requests](how-to/search-commands/respond-to-search.md#respond-to-user-requests).
-* A `jsonPath` is rerequired for arrays or when the data for the Adaptive Card isn't the root object. For example, if your data is nested under `productDetails`, your JSON path would be `productDetails`.
-* Define `jsonPath` as the path to the relevant data or array in the API response. If the path points to an array, then each entry in the array binds with the Adaptive Card template and returns as a separate result. *[Optional]*
-* Get a sample response for validating the response rendering template. This serves as a test to ensure your template works as expected.
-* Use tools such as Fiddler or Postman to call the API and ensure that the request and the response are valid. This step is crucial for troubleshooting and confirming that your API is functioning correctly.
-* You can use the Adaptive Card Designer to bind the API response to the response rendering template and preview the Adaptive Card. Insert the Adaptive Card template in the **CARD PAYLOAD EDITOR** and insert the sample response entry in the **SAMPLE DATA EDITOR**.
+* Define the schema reference URL in the $schema property to establish the structure using [response rendering template schema](https://developer.microsoft.com/json-schemas/teams/v1.17/MicrosoftTeams.ResponseRenderingTemplate.schema.json).
+* Set responseLayout to either list or grid to determine how results appear. Developers refer to [respond to user requests](how-to/search-commands/respond-to-search.md#respond-to-user-requests) for layout details.
+* Use jsonPath for arrays or when the data for the Adaptive Card is nested. For instance, if data is under productDetails, use jsonPath as productDetails.
+* Define jsonPath as the path to the relevant data or array in the API response. If the path points to an array, each entry binds with the Adaptive Card template and returns as a separate result. *[Optional]*
+* Provide a sample response for validating the response rendering template, ensuring the template performs as expected.
+* Use tools such as Fiddler or Postman to call the API, validating both requests and responses. This helps troubleshoot and confirm API functionality.
+* Use Adaptive Card Designer to bind the API response to the response rendering template and preview the Adaptive Card by inserting the template in the CARD PAYLOAD EDITOR and a sample response in the SAMPLE DATA EDITOR.
+
+The following example illustrates a Response rendering template:
-The following code is an example of a Response rendering template:
+
Response rendering template example
```json
@@ -391,7 +386,7 @@ The following code is an example of a Response rendering template:
**Preview Card**
-A preview card template in the response rendering template schema is used to map JSON responses to a preview card that users see when they select a search result. The preview card then expands into an Adaptive Card in the message compose box. The preview card template is part of the response rendering template, which also includes an Adaptive Card template and metadata.
+A preview card template in the response rendering template schema maps JSON responses to a preview card that developers see when a search result is selected. The preview card then expands into an Adaptive Card in the message compose box. The preview card template is part of the overall response rendering template, which includes an Adaptive Card template and metadata.
:::image type="content" source="../assets/images/Copilot/api-based-message-extension-preview-card.png" alt-text="Screenshot shows an example of compose extension displaying an array of preview cards when searching for a specific word. In this case, searching for 'a' in the 'test app' returns five cards showing 'Title', 'Description' (truncated) and 'AssignedTo' properties and values in each one.":::
@@ -404,17 +399,17 @@ A preview card template in the response rendering template schema is used to map
|Property |Type |Description |Required |
|--------- |---------|---------|---------|
|`version` | `string` | The schema version of the current response rendering template. | Yes |
-|`jsonPath` | `string` | The path to the relevant section in the results to which the responseCardTemplate and previewCardTemplate should be applied. If not set, the root object is treated as the relevant section. If the relevant section is an array, each entry is mapped to the responseCardTemplate and the previewCardTemplate. | No |
-|`responseLayout` | `responseLayoutType` | Specifies the layout of the results in the message extension flyout. The supported types are `list` and `grid`. | Yes |
-|`responseCardTemplate` | `adaptiveCardTemplate` | A template for creating an Adaptive Card from a result entry. | Yes |
-|`previewCardTemplate` | `previewCardTemplate` | A template for creating a preview card from a result entry. The resulting preview card is displayed in the message extension flyout menu. | Yes |
+|`jsonPath` | `string` | The path to the relevant section in the results to which the responseCardTemplate and previewCardTemplate apply. If not set, the root object is considered as the relevant section. If the section is an array, each entry maps to the responseCardTemplate and previewCardTemplate. | No |
+|`responseLayout` | `responseLayoutType` | Specifies the layout of the results in the message extension flyout. Supported types are list and grid. | Yes |
+|`responseCardTemplate` | `adaptiveCardTemplate` | Template for creating an Adaptive Card from a result entry. | Yes |
+|`previewCardTemplate` | `previewCardTemplate` | Template for creating a preview card from a result entry. The preview card displays in the message extension flyout menu. | Yes |
#### Json path
-The [JSON path](https://www.newtonsoft.com/json/help/html/QueryJsonSelectToken.htm) is optional but should be used for arrays or where the object to be used as the data for the Adaptive Card isn't the root object. The JSON path should follow the format defined by Newtonsoft. This tool can be used. You can use the [JSON tool](https://jsonpath.com/) to validate if a JSON path is correct. If the JSON path points to an array, then each entry in that array is bound with the Adaptive Card template and returns as separate results.
+The [JSON path](https://www.newtonsoft.com/json/help/html/QueryJsonSelectToken.htm) remains optional but is recommended for arrays or when the object to be utilized as the data for the Adaptive Card is nested. The JSON path must follow the format defined by Newtonsoft. Developers can use the [JSON tool](https://jsonpath.com/) to verify a JSON path. When the JSON path points to an array, each entry in the array binds to the Adaptive Card template and returns as separate results.
**Example**
-Let's say you have the following JSON for a list of products and you want to create a card result for each entry.
+Given the following JSON for a list of products where each product maps to a card result:
```json
{
@@ -428,22 +423,22 @@ Let's say you have the following JSON for a list of products and you want to cre
}
```
-As you can see, the array of results is under "products", which is nested under "warehouse", so the JSON path would be "warehouse.products".
+Since the results array resides under "products" nested within "warehouse", the JSON path becomes "warehouse.products".
-Use [Adaptive Card Designer](https://adaptivecards.microsoft.com/designer.html) to preview an Adaptive Card by inserting the template into Card Payload Editor. Take a sample response entry from your array or for your object and insert it into Sample Data Editor. Ensure that the card renders properly and is to your liking.
+Developers use [Adaptive Card Designer](https://adaptivecards.microsoft.com/designer.html) to preview an Adaptive Card by inserting the template into the Card Payload Editor and sample response entry into the Sample Data Editor, ensuring the card renders properly.
## OpenAPI schema conversion
> [!NOTE]
-> We send an accept-language header in the HTTP request that is sent to the endpoint defined in the OpenAPI description document. The accept-language is based on the Teams client locale and can be used by the developer for returning back a localized response.
+> The process sends an accept-language header in the HTTP request to the endpoint defined in the OpenAPI description document. The accept-language header derives from the Teams client locale and allows the developer to return a localized response.
-The following data types in the OpenAPI description document are converted into elements within an Adaptive Card as follows:
+The following data types in the OpenAPI description document convert into Adaptive Card elements:
-* `string`, `number`, `integer`, `boolean` types are converted to a TextBlock.
+* string, number, integer, boolean types convert to a TextBlock.
Example
- * **Source Schema**: `string`, `number`, `integer`, and `boolean`
+ * **Source Schema**: string, number, integer, and boolean
```yml
name:
@@ -451,7 +446,7 @@ The following data types in the OpenAPI description document are converted into
example: doggie
```
- * **Target Schema**: `Textblock`
+ * **Target Schema**: TextBlock
```json
{
@@ -463,11 +458,11 @@ The following data types in the OpenAPI description document are converted into
Example
- * **Source schema**: `array`
+ * **Source schema**: array
```yml
type: array
@@ -485,7 +480,7 @@ The following data types in the OpenAPI description document are converted into
type: string
```
- * **Target Schema**: `Container`
+ * **Target Schema**: Container
```json
{
@@ -509,11 +504,11 @@ The following data types in the OpenAPI description document are converted into
Example
- * **Source Schema**: `object`
+ * **Source Schema**: object
```yml
components:
@@ -547,11 +542,11 @@ The following data types in the OpenAPI description document are converted into
Example
- * **Source schema**: `image`
+ * **Source schema**: image
```yml
image:
@@ -561,7 +556,7 @@ The following data types in the OpenAPI description document are converted into
```
- * **Target Schema**: `"Image"`
+ * **Target Schema**: Image
```json
{
@@ -574,8 +569,6 @@ The following data types in the OpenAPI description document are converted into