Define message extension search commands

Article
03/21/2023

Important

The code samples in this section are based on v4.6 and later versions of the Bot Framework SDK. If you're looking for documentation for earlier versions, see the Message Extensions - v3 SDK section in the Resources folder of the documentation.

Message extension search commands allow users to search external systems and insert the results of that search into a message in the form of a card. This document guides you on how to select search command invoke locations, and add the search command to your app manifest.

Note

The result card size limit is 28 KB. The card is not sent if its size exceeds 28 KB.

See the following video to learn how to define message extension search commands:

Select search command invoke locations

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 @mentioning in the command box.

When a search command is invoked from the compose message area, the user sends the results to the conversation. When it's 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, 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 a search command using Developer Portal

The prerequisite to create a search command is that you must already have created a message extension. For information on how to create a message extension, see create a message extension.

To create a search command

Open Developer Portal from the Microsoft Teams client and select the Apps tab. If you already created your app package in Developer Portal, select from the list. If you haven't created an app package, import an existing one.
After importing an app package, select Message extensions under App features.
To create a message extension, you need a Microsoft registered bot. You can either use an existing bot or create a new bot. Select Create new bot option, give a name to the new bot, and then select Create.
To use an existing bot, select Select an existing bot and choose the existing bots from the dropdown list, or select Enter a bot ID if you have a bot ID created already.
Select the scope of the messaging extension and select Save.
Select Add a command in the Command section to include the commands, which decide the behavior of message extension. The following image displays command addition for message extension:
Select Search and enter Command ID, Command title, and Command description.
Enter all the parameters and select the type of input from the dropdown list.
Select Add a domain under Preview links.
Enter valid domain and then select Add.
Select Save.

Create a search command manually

To manually add your message extension search command to your app manifest, you must add the following parameters to your composeExtensions.commands array of objects:

Property name	Purpose	Required?	Minimum manifest version
`id`	This property is a unique ID that you assign to search command. The user request includes this ID.	Yes	1.0
`title`	This property is a command name. This value appears in the user interface (UI).	Yes	1.0
`description`	This property is a help text indicating what this command does. This value appears in the UI.	Yes	1.0
`type`	This property must be a `query`.	No	1.4
`initialRun`	If this property is set to true, it indicates this command should be executed as soon as the user selects this command in the UI.	No	1.0
`context`	This property is an optional array of values that defines the context the search action is available in. The possible values are `message`, `compose`, or `commandBox`. The default is `["compose", "commandBox"]`.	No	1.5

You must add the details of the search parameter that defines the text visible to your user in the Teams client.

Property name	Purpose	Is required?	Minimum manifest version
`parameters`	This property defines a static list of parameters for the command.	No	1.0
`parameter.name`	This property describes the name of the parameter. The `parameter.name` is sent to your service in the user request.	Yes	1.0
`parameter.description`	This property describes the parameter’s purposes or example of the value that must be provided. This value appears in the UI.	Yes	1.0
`parameter.title`	This property is a short user-friendly parameter title or label.	Yes	1.0
`parameter.inputType`	This property is set to the type of the input required. Possible values include `text`, `textarea`, `number`, `date`, `time`, `toggle`. Default is set to `text`.	No	1.4
`parameters.value`	Initial value for the parameter. Currently the value isn't supported	No	1.5

Example

Following section is an example of the simple app manifest of the composeExtensions object defining a search command:

{
...
  "composeExtensions": [
    {
      "botId": "57a3c29f-1fc5-4d97-a142-35bb662b7b23",
      "canUpdateConfiguration": true,
      "commands": [{
          "id": "searchCmd",
          "description": "Search Bing for information on the web",
          "title": "Search",
          "initialRun": true,
          "parameters": [{
            "name": "searchKeyword",
            "description": "Enter your search keywords",
            "title": "Keywords"
          }]
        }
      ]
    }
  ],
...
}

For more information, see app manifest schema.

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 nudget 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 the search commands.