Extend a Teams message extension across Microsoft 365

Message extensions allow users to interact with your web service using buttons and forms. Users can search or initiate actions in an external system from Microsoft Teams and Outlook by extending your Teams apps across Microsoft 365. There are two types of message extensions:

  • Search-based message extensions: Allow users to search an external system and share results through the compose message area of the client.

  • Action-based message extensions: Allow users with a modal pop-up to collect or display information, process the interaction, and send the information back to the client as a rich card.

Note

Teams search-based message extensions are generally available for Outlook and action-based message extensions are available in preview for Outlook.

Outlook mobile users on Android and iOS can receive and take actions on cards from your apps that were sent to them by users on Outlook on the web and Outlook for Windows.

Teams message extension across Microsoft 365 also supports link unfurling that display cards to launch Stageview and dialogs.

Prerequisites

To extend your Teams message extension to Outlook, ensure the following:

Build or extend a message extension

To extend your Teams message extension to Outlook, you can either build a new message extension app with Teams Toolkit or extend an existing Teams message extension app to Outlook.

You can build a Teams message extension app for Outlook through Teams Toolkit extension for Visual Studio Code. To build a message extension app for Outlook, ensure the following:

You can build either a search-based or an action-based message extension.

  1. Open Visual Studio Code.

  2. Select Command Palette... under the View option or Ctrl+Shift+P.

  3. Select Teams: Create a New App.

  4. Select Message Extension from the dropdown list.

  5. Select Custom Search Results to download the sample code for a Teams search-based message extension using the latest app manifest (previously called Teams app manifest).

    Screenshot shows the Create a new Teams app VS Code command palette to list Teams sample options.

    You can also download the sample code from the left pane, under DEVELOPMENT, select View Samples. A Samples tab appears, in the search field enter NPM Search Connector.

    Screenshot shows the NPM Search Connector sample in Teams Toolkit Samples gallery.

  6. Select a preferred programming language.

  7. Select a location on your local machine for the workspace folder and enter your application name.

  8. Select Command Palette... under the View option or Ctrl+Shift+P.

  9. Enter Teams: Provision to create the relevant app resources, such as Azure App Service, App Service plan, Azure Bot, and Managed Identity, in your Azure account.

  10. Select a subscription and a resource group.

  11. Select Provision. Alternatively, you can select Provision under the LIFECYCLE section of the extension.

  12. Select Command Palette... under the View option or Ctrl+Shift+P.

  13. Enter Teams: Deploy to deploy the sample code to the provisioned resources in Azure and start the app. Alternatively, you can select Deploy under LIFECYCLE section of the extension.

  14. Select Deploy.

Now, you can upload your app in Teams and preview your message extension in Outlook. To build your app package through Teams Toolkit, see build app package.

Upload your custom app in Teams

Upload your updated message extension (app package) into Teams. After you complete, message extension appears in your installed Apps from the compose message area.

  1. Create a .zip file with app manifest and app icons.

  2. Go to Microsoft Teams and sign in using your sandbox tenant account.

  3. Select Apps > Manage your apps > Upload an app.

    Screenshot shows the Upload an app option under Manage your apps.

  4. Select the Upload a custom app option, select your .zip file, and install (Add) it to your Teams client.

    Screenshot shows the Upload a custom app option in Teams.

After it's uploaded through Teams, your message extension is available in Outlook for Windows desktop and web.

Preview your message extension in Outlook

Here's how to test your message extension running in Outlook on the web. To preview your app running in Outlook on the web, follow these steps:

  1. Sign in to outlook.com using your test tenant credentials.

  2. Select New message.

  3. Select Apps on the ribbon.

    Screenshot shows the preview your message extension in Outlook on the web.

Your message extension is listed. You can invoke it from there and use it just as you would while composing a message in Teams.

Debugging

As you debug your message extension, you can identify the source (originating from Teams versus Outlook) of bot requests by the channelId field of the Activity object. When a user performs a query, your service receives a standard Bot Framework Activity object. One of the properties in the Activity object is channelId, which has the value of msteams or m365extensions, depending on where the bot request originates. For more information, see search based message extensions SDK and action based messaging extensions SDK.

Limitations

While your updated message extension continues to run in Teams, you must be aware of the following limitations:

  • Message extensions in Outlook are supported only in the compose context. In Teams app manifest, message extension contexts such as commandBox and message aren't supported in Outlook.

  • Action-based message extensions that send cards into the compose box are supported in Outlook. However, using bots to deliver cards isn't supported. In this scenario, you can convert your message extension to send cards into the compose box in Outlook.

  • You can't insert more than five Adaptive Cards in an email.

  • Card actions of type messageBack, imBack, invoke, and signin aren't supported. openURL is the only supported card action.

  • Adaptive Card actions are supported. For Action.Submit only stageview and taskmodule launching is supported.

Note

When you test an app with link unfurling, ensure that you remove the app manually after testing. If multiple apps are monitoring the same domain, the app installed most recently might not be invoked to unfurl the link in Outlook, as it would in Teams.

Use the Microsoft Teams developer community channels to report issues and provide feedback.

Code sample

Sample Name Description Node.js
NPM Search Connector Teams Toolkit sample app to build a message extension app. Works in Teams and Outlook. View
Teams Link Unfurling Simple Teams app to demonstrate link unfurling. Works in Teams, Outlook. View
Tab in Stageview Microsoft Teams tab sample app for demonstrating a tab in Stageview. Works in Teams, Outlook, Microsoft 365 app. View
Teams action-based message extension for Microsoft 365 Teams Toolkit sample app to build a message extension app. Works in Teams and Outlook. View

Next step