Respond to search command

Important

The code samples in this section are based on 4.6 and later versions of the Bot Framework SDK. If you're looking for documentation for earlier versions, see the Messaging Extensions - v3 SDK section in the Resources folder of the documentation.

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. This invoke is triggered with the following conditions:

  • As characters are entered into the search box.
  • initialRun is set to true in your app manifest, you receive the invoke message as soon as the search command is invoked. For more information, see 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.
queryOptions Pagination parameters:
skip: Skip count for this query
count: Number of elements to return.
protected override async Task<MessagingExtensionResponse> OnTeamsMessagingExtensionQueryAsync(ITurnContext<IInvokeActivity> turnContext, MessagingExtensionQuery query, CancellationToken cancellationToken)
{
  //code to handle the query
}

Respond to user requests

When the user performs a query, Microsoft Teams issues a synchronous HTTP request to your service. At that point, your code has 5 seconds to provide an HTTP response to the request. During this time, your service can perform additional lookup, or any other business logic needed to serve the request.

Your service must respond with the results matching the user query. The response must indicate an HTTP status code of 200 OK and a valid application or JSON object with the following properties:

Property name Purpose
composeExtension Top-level response envelope.
composeExtension.type Type of response. The following types are supported:
result: Displays a list of search results
auth: Asks the user to authenticate
config: Asks the user to set up the messaging extension
message: Displays a plain text message
composeExtension.attachmentLayout Specifies the layout of the attachments. Used for responses of type result.
Currently, the following types are supported:
list: A list of card objects containing thumbnail, title, and text fields
grid: A grid of thumbnail images
composeExtension.attachments Array of valid attachment objects. Used for responses of type result.
Currently, the following types are supported:
application/vnd.microsoft.card.thumbnail
application/vnd.microsoft.card.hero
application/vnd.microsoft.teams.card.o365connector
application/vnd.microsoft.card.adaptive
composeExtension.suggestedActions Suggested actions. Used for responses of type auth or config.
composeExtension.text Message to display. Used for responses of type message.

Response card types and previews

Teams supports the following card types:

To have a better understanding and overview on cards, see what are cards.

To learn how to use the thumbnail and hero card types, see add cards and card actions.

For additional information regarding the Office 365 Connector card, see Using Office 365 Connector cards.

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:

  • Using the preview property within the attachment object. The preview attachment can only be a Hero or Thumbnail card.
  • Extracted from the basic title, text, and image properties of the attachment. These are used only if the preview property is not set and these properties are available.
  • The Hero or Thumbnail card button and tap actions, except invoke, are not supported in the preview card.

You can display a preview of an Adaptive Card or Office 365 Connector card in the result list using its preview property. The preview property is not necessary if the results are already Hero or Thumbnail cards. If you use the preview attachment, it must be either a Hero or Thumbnail card. If no preview property is specified, the preview of the card fails and nothing is displayed.

Response example

protected override async Task<MessagingExtensionResponse> OnTeamsMessagingExtensionQueryAsync(ITurnContext<IInvokeActivity> turnContext, MessagingExtensionQuery query, CancellationToken cancellationToken) 
{
  var text = query?.Parameters?[0]?.Value as string ?? string.Empty;

  //searches NuGet for a package
  var obj = JObject.Parse(await (new HttpClient()).GetStringAsync($"https://azuresearch-usnc.nuget.org/query?q=id:{text}&prerelease=true"));
  var packages = obj["data"].Select(item => (item["id"].ToString(), item["version"].ToString(), item["description"].ToString()));

  // We take every row of the results and wrap them in cards wrapped in in MessagingExtensionAttachment objects.
  // The Preview is optional, if it includes a Tap, that will trigger the OnTeamsMessagingExtensionSelectItemAsync event back on this bot.
  var attachments = packages.Select(package => new MessagingExtensionAttachment
      {
          ContentType = HeroCard.ContentType,
          Content = new HeroCard { Title = package.Item1 },
          Preview = new HeroCard { Title = package.Item1, Tap = new CardAction { Type = "invoke", Value = package } }.ToAttachment()
      })
      .ToList();

  // The list of MessagingExtensionAttachments must we wrapped in a MessagingExtensionResult wrapped in a MessagingExtensionResponse.
  return new MessagingExtensionResponse
  {
      ComposeExtension = new MessagingExtensionResult
      {
          Type = "result",
          AttachmentLayout = "list",
          Attachments = attachments
      }
  };
}

Default query

If you set initialRun to true in the manifest, Microsoft Teams issues a default query when the user first opens the messaging extension. Your service can respond to this query with a set of pre-populated results. This is useful when your search command requires authentication or configuration, displaying recently viewed items, favorites, or any other information that is not 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:

{
  "type": "invoke",
  "name": "composeExtension/query",
  "value": {
    "commandId": "searchCmd",
    "parameters": [
      {
        "name": "initialRun",
        "value": "true"
      }
    ],
    "queryOptions": {
      "skip": 0,
      "count": 25
    }
  },
  ⋮
}

Code sample

Sample Name Description .NET Node.js
Teams messaging extension action Describes how to define action commands, create task module, and respond to task module submit action. View View
Teams messaging extension search Describes how to define search commands and respond to searches. View View

See also

Add configuration to a messaging extension

Next step