Define a search command


Search-based message extensions allow users to search an external system for information and insert the results of the search into a message in Teams. In this unit, you learn how search-based message extensions work and how to register your search command(s).

Plan your extension functionality

Here's a simple interaction flow for a search-based message extension:

  1. A user invokes the message extension, from the Compose message area or the command box, and enters a search string.
  2. Your app responds with a list of cards and card previews.
  3. The Teams client renders a list of card previews for the user.
  4. When the user selects a card from the list, the full-size card is inserted into the Compose message area.

The following image displays the message extension search command task module:

Screenshot of a channel in the Microsoft Teams client.  A list of card previews is displayed with a search box at the top of the list.

Register your command(s)

When you use Teams Toolkit to create a new app with a message extension, Teams Toolkit takes care of your app registration.

To register a search command manually, define a new command in the composeExtensions array property in the app manifest. The composeExtensions array property should be at the top level of your JSON file. Here's an example of a search command defined in an app manifest:

"composeExtensions": [
    "botId": "${{AAD_APP_CLIENT_ID}}",
    "canUpdateConfiguration": true,
    "commands": [
        "id": "searchQuery",
        "type": "query",
        "title": "Search",
        "description": "Test command to run query",
        "initialRun": false,
        "fetchTask": false,
        "context": [
        "parameters": [
            "name": "searchQuery",
            "title": "Search Query",
            "description": "Your search query",
            "inputType": "text"

Provide values for the following command properties:

Property Description Required?
id The ID for the command. Yes.
type Type of command. Set to query for search commands. No. Defaults to: query
context Defines where the command can be invoked from. Any combination of compose, commandBox, message. No. Defaults to: ["compose","commandBox"].
parameters The search queries. Defines the input fields displayed in the search experience when the message extension is invoked. Yes. Provide 1-5 parameters.
initialRun If you include this property set to true, your web service will receive the invoke message as soon as the search command is invoked. Otherwise, it will only receive a message when the search is executed. No. Defaults to: false.


Search-based message extensions can be invoked from the Compose message area or the command box. They cannot be invoked from a message.