Previous

Next

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

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": [
        "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 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.

Note

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

Continue