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:

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.

Prerequisites

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

• Node.js. The supported versions are 16, 18.
• Microsoft 365 account for development
• Set up your dev environment for extending Teams apps across Microsoft 365. After you've enrolled your developer tenant in Office 365 Targeted Release, it might take a couple of days for the enrollment to take effect.
• Teams Toolkit Visual Studio Code Extension version 5.2.0 and higher or Teams Toolkit CLI.

Teams Toolkit

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.

   

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.

Developer Portal for Teams

1. Go to Developer Portal for Teams.

2. Go to Apps.

3. Select Create a new app.

4. Under Configure, select App features.

5. Select Messaging extension.

   

6. Under Message extension type, select Bot.

   1. If you get a disclaimer, which reads API Message extension is already in use by users. Would you like to change message extension type to bot?. Select Yes, change.

   

7. If you have an existing bot, select Existing bot or if you have a bot ID, select Enter Bot ID.

   1. If you don't have an existing bot ID, select Create a bot, to create a new bot and enter the bot ID of the new bot that you created.

8. Select Save.

9. Select the required scopes.

10. Under Command, select + Add a command.

    A command details page appears.

11. In the Command details page, select Search as the type of command and update the following fields:

    • Command ID
    • Command title
    • Command description
    • Context in which the command works
    • Parameter name
    • Parameter title
    • Parameter description
    • Select the type of input

12. Select Save. A search message extension using bot framework created.

13. At the upper-right corner, select Preview in Teams. The app opens in Teams desktop or web client.

Extend bot-based message extension as agent

Important

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

Microsoft 365 agents 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 agents allow Microsoft 365 Copilot 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 Microsoft 365 Copilot. For more information, see extend bot-based message extension as agent for Microsoft 365 Copilot.

Code snippets

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

C#

• SDK reference
• Sample code reference

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;
            }).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
                }
            };
        }

Node.js

Sample code reference

async handleTeamsMessagingExtensionQuery(context, query) {
        const searchQuery = query.parameters[0].value;     
        const attachments = [];
                const response = await axios.get(`http://registry.npmjs.com/-/v1/search?${ querystring.stringify({ text: searchQuery, size: 8 }) }`);
                
                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: { description: obj.package.description } };
                        const attachment = { ...heroCard, preview };
                        attachments.push(attachment);
                });
    
                return {
                    composeExtension:  {
                           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

Respond to search commands.

See also

• Developer Portal for Teams
• Message extensions