Define a search command

Completed

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 a search command.

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 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. The full-size card is inserted into the message area, when the user selects a card from the list.

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

When you build a message extension, define supported commands in the app manifest.

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": [
        "compose",
        "commandBox"
        ],
        "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 receives the invoke message as soon as the search command is invoked. Otherwise, your web service only receives a message when the search is executed. No. Defaults to: false.

Note

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