Message extensions built using Bot Framework (Bot-based) use a web service as a bot. You can use message extensions to enable users to interact with your web service from different locations in the Teams client, such as the compose message area, the command box, or directly from a message and send back structured data, such as cards.
Bot-based message extension takes advantage of the Bot Framework's messaging schema and secure communication protocol. The bot is defined in the app manifest for the Teams app and you can also define different types of commands for your message extension, such as action commands or search commands.
There are two types of message extension commands, action command and search command. The message extension command type defines the UI elements and interaction flows available to your web service. You can use a search command or an action command to interact with your web service through a bot in Teams.
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 isn't sent if its size exceeds 28 KB.
See the following video to learn how to define message extension search commands:
The search command in a message extension is configured using the composeExtensions.commands property and the query type in the app manifest (previously called as Teams app manifest). Command and parameter descriptions enhance the usability and effectiveness of a message extension. A good command description offers a clear and concise summary of the app’s features.
The following code is an example of the composeExtensions property defining a search command:
You must add the following parameters to your composeExtensions.commands array of objects:
Property name
Purpose
Required?
Manifest version
id
Unique ID that you assign to search command. The user request includes this ID.
Yes
1.0
title
Command name. This value appears in the user interface (UI).
Yes
1.0
description
Help text indicating what this command does. This value appears in the UI.
Yes
1.0
semanticDescription
Semantic description of the command for consumption by the Large Language Models (LLMs).
No
1.17
type
Type of command. Default is 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
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 following search parameter details that define the text visible to your user in the Teams client:
Property name
Purpose
Is required?
Minimum manifest version
parameters
Defines a static list of parameters for the command.
No
1.0
parameter.name
Describes the name of the parameter. The parameter.name is sent to your service in the user request.
Yes
1.0
parameter.description
Describes the parameter’s purposes or example of the value that must be provided. This value appears in the UI.
Yes
1.0
parameter.semanticDescription
Semantic description of the parameter for consumption by the Large Language Models (LLMs).
No
1.17
parameter.title
Short user-friendly parameter title or label.
Yes
1.0
parameter.inputType
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. The value isn't supported
Message extension as plugin for Copilot for Teams meetings
Message extension plugins are supported in Copilot for Teams meetings. Extending bot-based message extension plugins to meetings allows you to enhance the Copilot for Teams meetings. Copilot for Teams meetings can utilize various app capabilities during meetings, such as task modules, app sharing, and more, to improve user engagement and productivity. For example, a plugin can be used in Copilot for Teams meetings to summarize discussions, generate notes, and list tasks. It also extends the benefits of traditional plugins by enabling real-time interaction with external data and custom functionality.
Copilot for Teams meetings is interactive and efficient, it can assist with summarizing discussions, suggesting action items, and providing prompt-less assistance in real-time. Users can ask natural language questions to Copilot for Teams meetings and get responses from your plugin that are relevant to the meeting context. Plugins are available for users to enable in both Microsoft 365 Copilot and Copilot for Teams meetings.
Benefits
Description
User Empowerment
Extending Copilot for Teams meetings empowers users with various actions to enhance their meeting experience.
UI Commands
Users can easily access features like opening a task module or sharing an app to the stage.
Search Commands
Efficient data retrieval from app databases is made possible, streamlining the search process.
Scenarios
Description
Reactive Commands
Users can directly command Copilot for Teams meetings to perform specific actions or provide information.
- Natural Language Prompts: Users can instruct Copilot for Teams meetings to carry out search commands.
- Prompt Suggestions: Apps can offer static or enriched prompts for Copilot for Teams meetings to execute.
Proactive Assistance
Copilot for Teams meetings proactively listens to meeting signals and assists users by:
- Suggesting prompts from apps: Contextually relevant suggestions based on the discussion topics.
- Providing assistance without explicit prompts: Copilot for Teams meetings can automatically suggest actions based on the discussion.
When a message action is initiated, attachment details aren't sent as part of the turncontext invoke activity.
Action commands allow you to present your users with a modal pop-up called a task module in Teams. The task module collects or displays information, processes the interaction, and sends the information back to Teams. This document guides you on how to select action command invoke locations, create your task module, send final message, or card, create action command using app studio, or create it manually.
The action command in a message extension is configured using the composeExtensions.commands property and action type in the app manifest.
The following code is an example of the composeExtensions property defining an action command:
"composeExtensions": [
{
"botId": "xxxxxx-xxx-bot-ID-xxxxxxxx}",
"commands": [
{
"id": "createCard",
"context": [
"compose",
"message",
"commandBox"
],
"description": "Command to run action to create a Card from Compose Box",
"title": "Create Card",
"type": "action",
"parameters": [
{
"name": "title",
"title": "Card title",
"description": "Title for the card",
"inputType": "text"
},
{
"name": "subTitle",
"title": "Subtitle",
"description": "Subtitle for the card",
"inputType": "text"
},
{
"name": "text",
"title": "Text",
"description": "Text for the card",
"inputType": "textarea"
}
]
}
]
}
]
Parameters
You must add the following parameters to your composeExtensions.commands array of objects:
Property name
Purpose
Required?
Manifest version
id
Unique ID that you assign to this command. The user request includes this ID.
Yes
1.0
title
Command name. This value appears in the UI.
Yes
1.0
type
Message extension type. Default is action.
No
1.4
fetchTask
Set to true for an Adaptive Card or embedded web view for your task module, andfalse for a static list of parameters or when loading the web view by a taskInfo.
No
1.4
context
Optional array of values that defines where the message extension is invoked from. The possible values are message, compose, or commandBox. The default value is ["compose", "commandBox"].
No
1.5
If you're using a static list of parameters, you must also add the following parameters:
Property name
Purpose
Is required?
Minimum manifest version
parameters
Describes the static list of parameters for the command. Only use when fetchTask is false.
No
1.0
parameter.name
Describes the name of the parameter. This is sent to your service in the user request.
Yes
1.0
parameter.description
Describes the parameter’s purposes or example of the value that should be provided. This value appears in the UI.
Yes
1.0
parameter.title
Short user-friendly parameter title or label.
Yes
1.0
parameter.inputType
Set to the type of input required. The possible values include text, textarea, number, date, time, toggle. The default value is set to text.
No
1.4
If you're using an embedded web view, you can optionally add the taskInfo object to fetch your web view without calling your bot directly. If you select this option, the behavior is similar to that of using a static list of parameters. In that the first interaction with your bot is responding to the task module submit action. If you're using a taskInfo object, you must set the fetchTask parameter to false.
Property name
Purpose
Is required?
Minimum manifest version
taskInfo
Specify the task module to preload when using a message extension command.
No
1.4
taskInfo.title
Initial task module title.
No
1.4
taskInfo.width
Task module width, either a number in pixels or default layout such as large, medium, or small.
No
1.4
taskInfo.height
Task module height, either a number in pixels or default layout such as large, medium, or small.
The source for this content can be found on GitHub, where you can also create and review issues and pull requests. For more information, see our contributor guide.
Platform Docs feedback
Platform Docs is an open source project. Select a link to provide feedback:
Learn how to build message extensions that allow users to interact with external services within their flow of work in Microsoft Teams and Microsoft 365 Copilot.