Designing your Microsoft Teams messaging extension
Messaging extensions are shortcuts for inserting app content or acting on a message without navigating away from the conversation. To guide your app design, the following information describes and illustrates how people can add, use, and manage messaging extensions in Teams.
Microsoft Teams UI Kit
You can find comprehensive messaging extension design guidelines, including elements that you can grab and modify as needed, in the Microsoft Teams UI Kit.
Add a messaging extension
You can add a messaging extension in the following Teams contexts:
- From the Teams store.
- In a channel, chat, or meeting (before, during, and after) near the compose box. It's worth noting if you add a messaging extension in one of these places, only you can use it in that context.
The following example shows how you add a messaging extension in a channel:
Set up a messaging extension
Authentication isn't mandatory, but if your app is something like a ticket tracking tool, you may need people to sign in to use the messaging extension.
For consistency across Teams apps, you can't customize the sign-in screen. If you use single sign-on (SSO) authentication, users are signed in automatically.
Types of messaging extensions
Messaging extensions can have search commands, action commands, or both. Your commands depend on your app's features and how those fit within Teams use cases.
With search commands, people can use your messaging extension to quickly find external content and insert into a message. Search commands are commonly made available in the compose box. For example, you can start or add to a discussion by sharing a piece of content—without ever leaving Teams.
Compose box layout options
You have some options for displaying messaging extension search results, including list and grid views.
Action commands allow people to trigger actions and process requests in external services within Teams. For example, if your app tracks orders, a user could create a new order using the contents of a colleague’s message from right inside their chat.
Action-based messaging extensions frequently require users to complete a form or some other kind of configuration within a modal. You can create these experiences with task modules.
Open a messaging extension
The compose box and messages or posts are the primary contexts where people use messaging extensions.
From the compose box
Once added, users can open your messaging extension by selecting your app icon below the compose box. In these examples, the extension has search and action commands.
From a chat message or channel post
Once added, users can select the More icon on the chat message or channel post to find your extension’s action commands. Your extension may be listed under More actions based on usage.
Support for more actions from a chat message or channel post is not available on Microsoft Teams mobile platform.
Use a messaging extension
The following scenarios show the primary ways people use messaging extensions.
Insert content into a message
1. Select a messaging extension. Users can search for the content they want to share from the compose box.
2. Insert content. Once posted, others can reply or select the content to see more information in your app.
Take action on a message
1. Select a messaging extension. Your app can include one or more action commands.
2. Complete the action. Your app can receive and process any content or data sent by the message action. This allows users to remain in their conversation and, the following example, not worry about entering information directly in your app.
Messaging extensions also allow you to insert rich links from a recognized URL into a message (this capability is called link unfurling.)
1. Paste a recognized link in the compose box.
2. Insert content. If your app recognizes the URL in the compose box, it renders the link as a card that provides a content-rich preview of the web content. (See Adaptive Cards design guidelines for more information.)
Manage a messaging extension
By right clicking your icon, users can pin, remove, or configure your messaging extension.
Messaging extension in the compose box
The following example is a messaging extension opened from the compose box.
|1||App logo: Color icon of your app logo.|
|2||App name: Full name of your app.|
|3||Action commands menu icon (optional): Opens a list of action commands for your messaging extension (if you specify any).|
|4||Search box: Allows users to find app content they want to insert.|
|5||Tab menu (optional): Provides multiple content categories.|
|6||Action commands menu (optional): Displays list of action commands (if you specify any).|
|7||App content: Primarily to display search results. The example here is using the list layout (grid layout is another option).|
|8||App logo: Outline icon of your app logo.|
Messaging extension management menu
|1||Unpin: Available if the user has pinned your app.|
|2||Remove: Removes the messaging extension from the channel, chat, or meeting.|
Use these recommendations to create a quality app experience.
Setup and general usage
Do: Integrate with single-sign on
SSO makes the sign-in process easier, faster, and secure. Also, if a user has already signed in to your personal app, they don’t have to also sign in again to access the messaging extension.
Don't: Take users away from the conversation
Messaging extensions are shortcuts that are supposed reduce context switching. Your extension should not, for example, direct users to a webpage outside Teams.
Do: Highlight your messaging extension
Messaging extensions aren't always easy to find. Include screenshots of how to use it in your app details page. If your app also includes a bot, you can include messaging extension help documentation in a bot welcome tour.
Do: Let Teams handle some of the design work if possible
If it makes sense for your use cases, consider creating a search-based messaging extension. Teams renders these types of extensions with built-in theming and accessibility.
Don't: Embed your entire app in a task module
If your messaging extension requires action commands, keep the task module simple and display only the components required to complete the action.
Do: Take advantage of Teams color tokens
Each Teams theme has its own color scheme. To handle theme changes automatically, use color tokens (Fluent UI) in your design.
Don't: Hard code color values
If you don't use Teams color tokens, your designs will be less scalable and take more time to manage.
Do: Include action commands that make sense in context
Message actions should relate to what a user is looking at. For example, provide users a shortcut for creating an issue or work item using the text in someone’s post.
Don't: Include actions commands that aren't contextual
A message action to View your dashboard would probably seem disconnected from most conversations.
Do: Show search results while typing
Provide suggested search results while users type. They may find the content they need faster with minimal amount of characters.
Don't: Require users to submit a query
You can make users press a key or select a button to send queries to your app. While that may be easier on your app services service, people may be confused that they're not seeing real-time search results as they type.
Do: Consider zero-term queries
For example, before a user writes anything in the search box, display what they last viewed on your app. It's possible that they want to insert that content into their conversation.