Implement a search-based message extension

  • 3 minutes

To implement a search-based message extension, you need to modify your source code to return and render the appropriate results in response to search commands. The Teams Toolkit scaffolds this code for you, but you'll need to modify the code as needed and implement your app logic. In this unit, you'll explore the methods and functionality required to implement a search-based message extension.

Respond to the search command

When your search command is invoked, Microsoft Teams sends a message of type composeExtension/query to the Bot Framework. The Bot Framework SDK will call the method handleTeamsMessagingExtensionQuery() and pass in an Activity object of type composeExtension/query with the command ID. This function is scaffolded when you use Teams Toolkit to create your message extension.

You need to respond with an object containing a composeExtension object within five seconds of receiving the request.

Here's an example:

public async handleTeamsMessagingExtensionQuery(
    context: TurnContext,
    query: MessagingExtensionQuery
  ): Promise<MessagingExtensionResponse> {
    // get the search query
    const searchQuery = query.parameters[0].value;

    // execute search logic
    const response = await axios.get(
      `http://registry.npmjs.com/-/v1/search?${querystring.stringify({
        text: searchQuery,
        size: 8,
      })}`
    );
    // populate result attachment with adaptive cards
    const attachments = [];
    response.data.objects.forEach((obj) => {
      const heroCard = CardFactory.heroCard(obj.package.name);
      const preview = CardFactory.heroCard(obj.package.name);
      preview.content.tap = {
        type: "invoke",
        value: { name: obj.package.name, description: obj.package.description },
      };
      const attachment = { ...heroCard, preview };
      attachments.push(attachment);
    });
    // return the results
    return {
      composeExtension: {
        type: "result",
        attachmentLayout: "list",
        attachments: attachments,
      },
    };
  }

In the example, there is a single search parameter (query.parameters[0]) being accessed and used as the search query.

Response options

Notice the properties within the response in the example. The response must indicate an HTTP status code of 200 OK and a valid application or JSON object with the following properties:

The type property for your response can be one of the following options:

  • result: displays a list of the search results
  • message: displays a plain text message
  • auth: prompts the user to authenticate
  • config: prompts the user to set up the messaging extension

If you respond with a result (type: result):

  • The attachments property contains an array of supported cards.
  • The attachmentLayout property defines the layout as one of the following:
    • a list of results containing thumbnails, titles and text fields
    • a grid of thumbnail images.

If type is set to message, an extra property text can be used to set the plain text message displayed.

When type is set to auth or config, use the suggestedActions property to suggest extra actions to perform.

To learn more about working with cards in Microsoft Teams, review this article.