Note
Access to this page requires authorization. You can try signing in or .
Access to this page requires authorization. You can try .
Designing your Microsoft Teams message extension
Message 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 message extensions in Teams.
Microsoft Teams UI Kit
You can find comprehensive message extension design guidelines, including elements that you can grab and modify as needed, in the Microsoft Teams UI Kit.
Add a message extension
You can add a message extension in the following Teams contexts:
- From the Microsoft Teams Store.
- In a channel, chat, or meeting (before, during, and after) near the compose box. It's worth noting if you add a message extension in one of these places, only you can use it in that context.
The following examples show how to add a message extension in a channel.
Mobile
👁 Example shows how to add a message extension near the compose box in a channel on mobile.
Desktop
👁 Example shows how to add a message extension near the compose box in a channel.
Set up a message 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 message 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.
Mobile
👁 Example shows message extension setup screen with a sign-in button on mobile.
Desktop
👁 Example shows message extension setup screen with a sign-in button.
Types of message extensions
Message extensions can have search commands, action commands, or both. Your commands depend on your app's features and how those fits within Teams use cases.
Search commands
With search commands, people can use your message 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.
Mobile
👁 Example shows a search-based message extension launched from the compose box on mobile.
Desktop
👁 Example shows a search-based message extension launched from the compose box.
Compose box layout options
You have some options for displaying message extension search results, including list and grid views.
👁 Illustrations showing layout options for message extension search results.
Action commands
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 message extensions frequently require users to complete a form or some other kind of configuration within a modal. You can create these experiences with dialogs(referred as task modules in TeamsJS v1.x).
Open a message extension
The compose box and messages or posts are the primary contexts where people use message extensions.
From the compose box
Once added, users can open your message extension by selecting your app icon below the compose box. In these examples, the extension has search and action commands.
Mobile
👁 Example shows how to open a message extension from the compose box on mobile.
Desktop
👁 Example shows how to open a message extension from the compose box.
From a chat message or channel post
Once added, users can select the More 👁 Image
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.
Chat message
👁 Example shows how to open a message extension from a chat message.
Channel post
👁 Example shows how to open a message extension from a channel post on mobile.
Use a message extension
The following scenarios show the primary ways people use message extensions.
Insert content into a message
1. Select a message extension. Users can search for the content they want to share from the compose box.
Mobile
👁 Example shows a user searching for content to insert from the compose box on mobile.
Desktop
👁 Example shows a user searching for content to insert from the compose box.
2. Insert content. Once posted, others can reply or select the content to see more information in your app.
Mobile
👁 Example shows a user posting content into a channel conversation on mobile.
Desktop
👁 Example shows a user posting content into a channel conversation.
Take action on a message
1. Select a message extension. Your app can include one or more action commands.
👁 Example shows a user selecting a message extension action command.
2. Complete the action. Your app can receive and process any content or data sent by the message action. Users complete the action in your app while remaining in their conversation.
👁 Example on how to take action on a message.
Preview links
Message 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.
Mobile
👁 Example shows a user pasting a link in the compost box on mobile.
Desktop
👁 Example shows a user pasting a link in the compost 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.)
Mobile
Desktop
👁 Example shows how the URL, since it's recognized by your app, includes some rich content in the compose box.
Manage a message extension
By right-clicking your icon, users can pin, remove, or configure your message extension.
Anatomy
Message extension in the compose box
The following examples show a message extension opened from the compose box.
Mobile
👁 Illustration showing the UI anatomy of a message extension in the compose box on mobile.
| Counter | Description |
|---|---|
| 1 | App name: Full name of your app. |
| 2 | Action commands menu icon (optional): Opens a list of action commands for your message extension (if you specify any). |
| 3 | Search box: Allows users to find app content they want to insert. |
| 4 | Tab menu (optional): Provides multiple content categories. |
| 5 | Action commands menu (optional): Displays list of action commands (if you specify any). |
| 6 | App content: Primarily to display search results. |
Desktop
👁 Illustration showing the UI anatomy of a message extension in the compose box.
| Counter | Description |
|---|---|
| 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 message 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. |
Message extension management menu
👁 Illustration showing the UI anatomy of a message extension management menu.
| Counter | Description |
|---|---|
| 1 | Unpin: Available if the user has pinned your app. |
| 2 | Remove: Removes the message extension from the channel, chat, or meeting. |
Best practices
Use these recommendations to create a quality app experience.
Setup and general usage
👁 Example of 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 message extension.
👁 Example of integrating with single-sign on.
Don't: Take users away from the conversation
Message 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 message extension
Message 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 message extension help documentation in a bot welcome tour.
Templating
Do: Let Teams handle some of the design work if possible
If it makes sense for your use cases, consider creating a search-based message extension. Teams renders these types of extensions with built-in theming and accessibility.
👁 Example of handling design work.
Don't: Embed your entire app in a dialog
If your message extension requires action commands, keep the dialog simple and display only the components required to complete the action.
Theming
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 time to manage.
Actions
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.
Searches
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.
Platform Docs
Feedback
Was this page helpful?