Extend a Teams message extension across Microsoft 365

Note

Extending a Teams message extension across Microsoft 365 is currently available only in public developer preview. Features included in preview may not be complete, and may undergo changes before becoming available in the public release. They are provided for testing and exploration purposes only. They should not be used in production applications.

Search-based messaging extensions allow users to search an external system and share results through the compose message area of the Microsoft Teams client. By extending your Teams apps across Microsoft 365 (preview), you can now bring your search-based Teams message extensions to Outlook for Windows desktop and web experiences.

The process to update your search-based Teams message extension to run Outlook involves these steps:

  • Update your app manifest
  • Add an Outlook channel for your bot
  • Sideload your updated app in Teams

The rest of this guide will walk you through these steps and show you how to preview your message extension in both Outlook for Windows desktop and web.

Prerequisites

To complete this tutorial, you'll need:

  • A Microsoft 365 Developer Program sandbox tenant
  • Your sandbox tenant enrolled in Office 365 Targeted Releases
  • A test environment with Office apps installed from the Microsoft 365 Apps beta channel
  • Visual Studio Code with the Teams Toolkit (Preview) extension (Optional)

Prepare your messaging extension for the upgrade

If you have an existing messaging extension, make a copy or a branch of your production project for testing and update your App ID in the app manifest to use a new identifier (distinct from the production App ID).

If you'd like to use sample code to complete this tutorial, follow the setup steps in Teams messaging extension search sample to quickly build and register a bot.

Update the app manifest

You'll need to use the Teams developer preview manifest schema and the m365DevPreview manifest version to enable your Teams messaging extension to run in Outlook.

You have two options for updating your app manifest:

  1. Open the Command palette: Ctrl+Shift+P
  2. Run the Teams: Upgrade Teams manifest to support Outlook and Office apps command and select your app manifest file. Changes will be made in place.

If you used Teams Toolkit to create your messaging extension app, you can use it to validate the changes to your manifest file and identify any errors. Open the command palette Ctrl+Shift+P and find Teams: Validate manifest file or select the option from the Deployment menu of the Teams Toolkit (look for the Teams icon on the left side of Visual Studio Code).

Teams Toolkit 'Validate manifest file' option under 'Deployment' menu

Add an Outlook channel for your bot

In Microsoft Teams, a messaging extension consists of a web service that you host and an app manifest, which defines where your web service is hosted. The web service takes advantage of the Bot Framework SDK messaging schema and secure communication protocol through a Teams channel registered for your bot.

For users to interact with your messaging extension from Outlook, you'll need to add an Outlook channel to your bot:

  1. From Azure portal (or Bot Framework portal if you previously registered there), navigate to your bot resource.

  2. From Settings, select Channels.

  3. Click on Outlook, select the Message extensions tab, then click Save.

    Add an Outlook 'Message Extensions' channel for your bot from the Azure Bot Channels pane

  4. Confirm that your Outlook channel is listed along with Microsoft Teams in your bot's Channels pane:

    Azure Bot Channels pane listing both Microsoft Teams and Outlook channels

Sideload your updated messaging extension in Teams

The final step is to sideload your updated messaging extension (app package) in Microsoft Teams. Once completed, your messaging extension will appear in your installed Apps from the compose message area.

  1. Package your Teams application (manifest and app icons) in a zip file. If you used Teams Toolkit to create your app, you can easily do this using the Zip Teams metadata package option in the Deployment menu of Teams Toolkit:

    'Zip Teams metadata package' option in Teams Toolkit extension for Visual Studio Code

  2. Log in to Teams with your sandbox tenant account, and verify you are on the Public Developer Preview by clicking on the ellipsis (...) menu by your user profile and opening About to check that the Developer preview option is toggled on.

    From Teams ellipses menu, open 'About' and verify 'Developer Preview' option is checked

  3. Open the Apps pane, and click Upload a custom app and then Upload for me or my teams.

    'Upload a custom app' button in the Teams 'Apps' pane

  4. Select your app package and click Open.

Once sideloaded through Teams, your messaging extension will be available in Outlook on the web.

Preview your message extension in Outlook

You're now ready to test your messaging extension running in Outlook on Windows desktop and the web. While your updated messaging extension will continue to run in Teams with full feature support for messaging extensions, there are limitations in this early preview of the Outlook-enabled experience to be aware of:

  • Messaging extensions in Outlook are limited to the mail compose context. Even if your Teams message extension includes commandBox as a context in its manifest, the current preview is limited to the mail composition (compose) option. Invoking a message extension from the global Outlook Search box is not supported.
  • Action-based messaging extension commands are not supported in Outlook. If your app has both search- and action-based commands, it will surface in Outlook but the action menu will not be available.
  • Single sign-on silent authentication is not supported for messaging extensions in Outlook.
  • Insertion of more than five Adaptive Cards in an email is not supported; Adaptive Cards v1.4 and later are not supported.
  • Card actions of type messageBack, imBack, invoke, and signin are not supported for inserted cards. Support is limited to openURL: on click, the user will be redirected to the specified URL in a new tab.

As you test your messaging extension, you can identify the source (originating from Teams versus Outlook) of bot requests by the channelId 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 will have the value of msteams or outlook, depending from where the bot request originates. For more, see Search based messaging extensions SDK.

Outlook

To preview your app running in Outlook on Windows desktop, open Outlook logged in with credentials for your test tenant. Click on New Email. Open the More apps flyout menu on the top ribbon. Your message extension will be listed. You can invoke it from there and use it just as you would while composing a message in Teams.

Outlook on the web

To preview your app running in Outlook on the web, log in to outlook.com using credentials for your test tenant. Click on New message. Open the More apps flyout menu on the bottom of the composition window. Your message extension will be listed. You can invoke it from there and use it just as you would while composing a message in Teams.

Next steps

Outlook-enabled Teams messaging extensions are in preview and not supported for production use. Here's how to distribute your Outlook-enabled messaging extension to preview audiences for testing purposes.

Single-tenant distribution

Outlook- and Office-enabled personal tabs can be distributed to a preview audience across a test (or production) tenant in one of three ways:

Teams client

From the Apps menu, select Manage your apps > Submit an app to your org. This requires approval from your IT admin.

Microsoft Teams Admin Center

As a Teams admin, you can upload and pre-install the app package for your organization's tenant from https://admin.teams.microsoft.com/. See Upload your custom apps in the Microsoft Teams admin center for details.

Microsoft Admin Center

As a global admin, you can upload and pre-install the app package from https://admin.microsoft.com/. See Test and deploy Microsoft 365 Apps by partners in the Integrated apps portal for details.

Multi-tenant distribution

Distribution to Microsoft AppSource is not yet supported during this early developer preview of Outlook-enabled Teams message extensions.