Define message extension search commands

The search command is invoked from any one or both of the following locations:

  • Compose message area: The buttons at the bottom of the compose message area.
  • Command box: By using / in the command box. For example, /your-app-name. If you're using the classic Teams, search command is invoked by @mentioning in the command box. For example, @your-app-name.

When a search command is invoked from the compose message area, the user sends the results to the conversation. When a search command invoked from the command box, the user interacts with the resulting card, or copies it for use elsewhere.

The following image displays the invoke locations of the search command:

Screenshot shows the invoke locations of a search command in a Teams channel.

Add the search command to your app manifest

To add the search command to your app manifest (previously called Teams app manifest), you must add a new composeExtensions object to the top level of your app manifest JSON. You can add the search command either with the help of Developer Portal or manually.

Create search message extension using Bot Framework

You can create a search message extension using Teams Toolkit and Developer Portal for Teams.


Before you get started, ensure that you meet the following requirements:

To create a search-based message extension using Teams Toolkit, 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 a programming language.

  7. Select Default folder.

  8. Enter the name of your app and select Enter.

    Teams Toolkit scaffolds your project and creates a search message extension.

To run the message extension in Teams, follow these steps:

  1. From the left pane, select Teams Toolkit.

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

    Screenshot shows the Microsoft 365 and Azure sign in option in Teams Toolkit.

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

  4. 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.

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

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

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

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

Extend bot-based message extension as plugin


Plugins for Microsoft Copilot for Microsoft 365 are in preview and only work in Microsoft 365 Chat in Teams.

Microsoft 365 plugins provide integration with various Microsoft 365 products, such as Teams and Outlook. The integration helps users to search or create content in external systems. Message extension plugins allow Microsoft Copilot for Microsoft 365 to interact with APIs from other software and services through a bot. We recommend that you build or upgrade your existing message extensions to maximize their usefulness and usability in Copilot for Microsoft 365. For more information, see extend bot-based message extension as plugin for Copilot for Microsoft 365.

Code snippets

The following code provides an example of search-based for message extensions:

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

            var packages = new[] {
            new { title = "A very extensive set of extension methods", value = "FluentAssertions" },
            new { title = "Fluent UI Library", value = "FluentUI" }};

            // We take every row of the results and wrap them in cards wrapped 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 =>
                var previewCard = new ThumbnailCard { Title = package.title, Tap = new CardAction { Type = "invoke", Value = package } };
                if (!string.IsNullOrEmpty(package.title))
                    previewCard.Images = new List<CardImage>() { new CardImage(package.title, "Icon") };

                var attachment = new MessagingExtensionAttachment
                    ContentType = HeroCard.ContentType,
                    Content = new HeroCard { Title = package.title },
                    Preview = previewCard.ToAttachment()

                return attachment;

            // 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

Code sample

Sample name Description .NET Node.js Manifest
Teams message extension search This sample shows how to build a search-based message extension. It searches NuGet packages and displays the results in search-based messaging extension. View View View

Step-by-step guide

Follow the step-by-step guide to build a search-based message extension.

Next step

See also