diff --git a/msteams-platform/assets/images/configuration-response-me.png b/msteams-platform/assets/images/configuration-response-me.png index e91eb95c579..a4dc167fe43 100644 Binary files a/msteams-platform/assets/images/configuration-response-me.png and b/msteams-platform/assets/images/configuration-response-me.png differ diff --git a/msteams-platform/assets/images/messaging-extension/message-response-type.png b/msteams-platform/assets/images/messaging-extension/message-response-type.png new file mode 100644 index 00000000000..1065e0ee4a3 Binary files /dev/null and b/msteams-platform/assets/images/messaging-extension/message-response-type.png differ diff --git a/msteams-platform/assets/images/messaging-extension/respond-to-search.png b/msteams-platform/assets/images/messaging-extension/respond-to-search.png new file mode 100644 index 00000000000..e9b206d68da Binary files /dev/null and b/msteams-platform/assets/images/messaging-extension/respond-to-search.png differ diff --git a/msteams-platform/assets/images/messaging-extension/result-response-search-cmd.png b/msteams-platform/assets/images/messaging-extension/result-response-search-cmd.png new file mode 100644 index 00000000000..a61c013abdf Binary files /dev/null and b/msteams-platform/assets/images/messaging-extension/result-response-search-cmd.png differ diff --git a/msteams-platform/messaging-extensions/how-to/search-commands/respond-to-search.md b/msteams-platform/messaging-extensions/how-to/search-commands/respond-to-search.md index b41374f86b2..15d9b716509 100644 --- a/msteams-platform/messaging-extensions/how-to/search-commands/respond-to-search.md +++ b/msteams-platform/messaging-extensions/how-to/search-commands/respond-to-search.md @@ -11,19 +11,19 @@ ms.localizationpriority: medium [!include[v4-to-v3-SDK-pointer](~/includes/v4-to-v3-pointer-me.md)] -After the user submits the search command, your web service receives a `composeExtension/query` invoke message that contains a `value` object with the search parameters. The invoke is triggered with the following conditions: +After the user submits the search command, your web service receives a `composeExtension/query` invoke message that contains a `value` object with the search parameters. The invoke is triggered by the following conditions: * As characters are entered into the search box. -* `initialRun` is set to true in your [app manifest](../../../resources/schema/manifest-schema.md#composeextensions) and you receive the invoke message as soon as the search command is invoked. For more information, see [default query](#default-query). +* `initialRun` is set to true in your [app manifest](../../../resources/schema/manifest-schema.md#composeextensions). For more information, see [default query](#default-query). -This document guides you on how to respond to user requests in the form of cards and previews, and the conditions under which Microsoft Teams issues a default query. +This document guides you on how to respond to user requests in the form of cards and previews and the conditions under which Microsoft Teams issues a default query. The request parameters are found in the `value` object in the request, which includes the following properties: | Property name | Purpose | |---|---| | `commandId` | The name of the command invoked by the user, matching one of the commands declared in the app manifest. | -| `parameters` | Array of parameters. Each parameter object contains the parameter name, along with the parameter value provided by the user. | +| `parameters` | Array of parameters. Each parameter object contains the parameter name along with the parameter value provided by the user. | | `queryOptions` | Pagination parameters:
`skip`: Skip count for this query
`count`: Number of elements to return. | # [C#/.NET](#tab/dotnet1) @@ -105,8 +105,8 @@ The following code snippet shows the `config` response that appears when the use "actions": [ { "type": "openUrl", - "title": "Open URL", - "value": "https://" + "title": "Open url", + "value": "https:///searchSettings.html?settings=" } ] }, @@ -149,6 +149,31 @@ To complete the message extension configuration flow: 4. Once `notifySuccess()` is executed, the configuration window automatically closes and the message extension is set up successfully. +### `auth` response type + +If your service requires user authentication, the users must sign in before they use the message extension. For more information, see [authentication](~/messaging-extensions/how-to/add-authentication.md#authentication). + +### `message` response type + +A `message` response is used when your extension needs to display a plain text message. The `message` response type doesn't support formatting. + +The following code snippet is an example of a `message` response returned by the app: + +```csharp + +return new MessagingExtensionResponse + { + ComposeExtension = new MessagingExtensionResult + { + Type = "message", + Text = "Here is the message you want to show!" + } + }; + +``` + +:::image type="content" source="../../../assets/images/messaging-extension/message-response-type.png" alt-text="Screenshot shows the message response type."::: + ### `result` response type The result list is displayed in the Microsoft Teams UI with a preview of each item. The preview is generated in one of the two ways: @@ -166,11 +191,9 @@ Teams supports the following card types: * [Connector card for Microsoft 365 Groups](~/task-modules-and-cards/cards/cards-reference.md#connector-card-for-microsoft-365-groups) * [Adaptive Card](~/task-modules-and-cards/cards/cards-reference.md#adaptive-card) -**Hero or Thumbnail card** +:::image type="content" source="../../../assets/images/messaging-extension/result-response-search-cmd.png" alt-text="Screenshot shows the result response type."::: -For the hero or thumbnail card, except for the invoke action, other actions such as button and tap aren't supported in the preview card. For hero and thumbnail cards, a preview is generated by default and you don't need to specify a `preview` property. To know about cards and learn how to use the thumbnail and hero card types, see [what are cards](~/task-modules-and-cards/what-are-cards.md) and [add cards and card actions](~/task-modules-and-cards/cards/cards-actions.md). - -**Adaptive Card or connector card** +For the hero or thumbnail card, except for the invoke action, other actions such as button and tap aren't supported in the preview card. For hero and thumbnail cards, you don't need to specify a preview property, a preview is generated by default. To know about cards and learn how to use the thumbnail and hero card types, see [what are cards](~/task-modules-and-cards/what-are-cards.md) and [add cards and card actions](~/task-modules-and-cards/cards/cards-actions.md). To send an Adaptive Card or connector card for Microsoft 365 Groups, you must include a preview. The `preview` property must be a hero or thumbnail card and the respective card is generated as preview. If a `preview` property isn't specified in the `attachment` object, a preview isn't generated. For more information, see [using connector cards for Microsoft 365 Groups](~/task-modules-and-cards/cards/cards-reference.md#connector-card-for-microsoft-365-groups). @@ -449,6 +472,8 @@ async def on_teams_messaging_extension_query(self, context, query): ### Enable and handle tap actions +When a user selects a result from the message extension search query, the preview card displays the description and the Tap actions that were defined. The Tap action must have the required value property assigned that displays as a Tap button in the card sent. + # [.NET](#tab/csharp3) * [Sample code reference](https://github.com/OfficeDev/Microsoft-Teams-Samples/blob/main/samples/msgext-search/csharp/Bots/TeamsMessagingExtensionsSearchBot.cs#L80) @@ -548,7 +573,7 @@ async def on_teams_messaging_extension_select_item( If you set `initialRun` to `true` in the manifest, Microsoft Teams issues a **default** query when the user first opens the message extension. Your service can respond to this query with a set of prepopulated results. This is useful when your search command requires authentication or configuration, displaying recently viewed items, favorites, or any other information that isn't dependent on user input. -The default query has the same structure as any regular user query, with the `name` field set to `initialRun` and `value` set to `true` as shown in the following object: +The default query has the same structure as any regular user query, except it has a parameter named `initialRun` that's set to a string value of `true`, as shown in the following object: ```json { @@ -573,7 +598,7 @@ The default query has the same structure as any regular user query, with the `na ## Code sample -| Sample name | Description | .NET | Node.js | Manifest| +| Sample name | Description | .NET | Node.js | Manifest | |:---------------------|:--------------|:---------|:--------|:--------| | Teams message extension search | This sample demonstrates how to create a message extension in Teams that allows users searches for NuGet packages and retrieve the results as a card. |[View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/msgext-search/csharp)|[View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/msgext-search/nodejs)|[View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/msgext-search/csharp/demo-manifest/msgext-search.zip) |Teams message extension auth and config | This sample demonstrates how to implement authentication in a message extension for Teams, enabling secure access and user-specific interactions. |[View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/msgext-search-auth-config/csharp)|[View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/msgext-search-sso-config/nodejs)|[View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/msgext-search-auth-config/csharp/demo-manifest/msgext-search-auth-config.zip) diff --git a/msteams-platform/resources/messaging-extension-v3/search-extensions.md b/msteams-platform/resources/messaging-extension-v3/search-extensions.md index a5c30317669..018013e2127 100644 --- a/msteams-platform/resources/messaging-extension-v3/search-extensions.md +++ b/msteams-platform/resources/messaging-extension-v3/search-extensions.md @@ -108,7 +108,69 @@ The `onQuerySettingsUrl` and `onSettingsUpdate` events work together to enable t :::image type="content" source="../../assets/images/compose-extensions/compose-extension-settings-menu-item.png" alt-text="Screenshot shows the locations of Settings menu item."::: -Your handler for `onQuerySettingsUrl` returns the URL for the configuration page; after the configuration page closes, your handler for `onSettingsUpdate` accepts and saves the returned state. This is the one case in which `onQuery` *doesn't* receive the response from the configuration page. +The [`onQuerySettingsUrl`](/dotnet/api/microsoft.teams.ai.messageextensions-1.onquery) handler returns the URL for the configuration page when a user clicks on the settings button. After the configuration page is closed, the `onSettingsUpdate` method is called to accept and save the returned state. The `onQuery` handler then retrieves the updated settings and uses them to update the behavior of the message extension. This is the one case in which `onQuery` *doesn't* receive the response from the configuration page. + +If a message extension uses a configuration page, the `onQuery` handler should first verify for any stored configuration data. If the message extension isn't configured, a `config` response must be returned, which includes a link to your configuration. + +The following image shows the `config` command workflow: + +:::image type="content" source="~/assets/images/messaging-extension/respond-to-search.png" alt-text="Screenshot shows the config command workflow and how it works."::: + +The following code handles a user request for the configuration page of a message extension. It fetches the user's existing configuration settings, escapes them, and builds a response. This response includes the configuration page's URL with the escaped settings added as a query parameter. + +```csharp + +protected override async Task OnTeamsMessagingExtensionConfigurationQuerySettingUrlAsync(ITurnContext turnContext, MessagingExtensionQuery query, CancellationToken cancellationToken) +{ + // The user has requested the Messaging Extension Configuration page. + var escapedSettings = string.Empty; + var userConfigSettings = await _userConfigProperty.GetAsync(turnContext, () => string.Empty); + if (!string.IsNullOrEmpty(userConfigSettings)) + { + escapedSettings = Uri.EscapeDataString(userConfigSettings); + } + + return new MessagingExtensionResponse + { + ComposeExtension = new MessagingExtensionResult + { + Type = "config", + SuggestedActions = new MessagingExtensionSuggestedAction + { + Actions = new List + { + new CardAction + { + Type = ActionTypes.OpenUrl, + Value = "https:///searchSettings.html?settings={escapedSettings}", + }, + }, + }, + }, + }; +} + +``` + +The following response is the configuration response that appears when the user interacts with the compose extension: + +```json +{ + "composeExtension": { + "type": "config", + "suggestedActions": { + "actions": [ + { + "type": "openUrl", + "value": "https:///searchSettings.html?settings=" + } + ] + } + } +} +``` + +:::image type="content" source="~/assets/images/configuration-response-me.png" alt-text="Screenshot shows the configuration response for message extension."::: ## Receive and respond to queries