Edit

Extend a Teams message extension across Microsoft 365

  • Article
  • 7 minutes to read

Note

  • Microsoft 365 Extensions channel is available only in public developer preview.
  • If you've connected your message extension bot to an Outlook channel, you must to migrate to the Microsoft 365 Extensions channel.

Search-based message extensions allow users to search an external system and share results through the compose message area of the Microsoft Teams client. You can now bring production search-based Teams message extensions to preview audiences in Outlook for Windows desktop and outlook.com by extending your Teams apps across Microsoft 365.

The process to update your search-based Teams message extension involves the following steps:

  • Update your app manifest.
  • Add the Microsoft 365 Extensions channel for your bot.
  • Sideload your updated app in Teams.

The rest of this guide walks you through these steps and shows how to preview your message extension in Outlook for Windows desktop and web.

Prerequisites

To complete this tutorial, you need:

  • A Microsoft 365 Developer Program sandbox tenant.
  • Enrollment in Microsoft 365 Targeted Releases for your sandbox tenant.
  • A test environment with Microsoft 365 apps installed from the Microsoft 365 Apps Beta Channel.
  • (Optional) Microsoft Visual Studio Code with the Teams Toolkit extension.

Install prerequisites

If your search-based message extension supports link unfurling in Teams, completing the steps of this tutorial also enables link unfurling in Outlook on the web and Windows desktop environments. The Code samples section below provides a simple link unfurling app for testing.

Prepare your message extension for the upgrade

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

If you'd like to use sample code to complete the full tutorial on updating an existing Teams app, follow the setup steps in Teams message extension search sample to quickly build a Microsoft Teams search-based message extension.

Alternately, you can use the ready-made Outlook-enabled app in the following section and skip the Update the app manifest portion of this tutorial.

Quickstart

To start with a sample message extension that's already enabled to run in Outlook, use Teams Toolkit extension for Visual Studio Code.

  1. From Visual Studio Code, open the command palette (Ctrl+Shift+P), type Teams: Create a new app.

  2. Select Create a new Teams app option.

  3. Select Search-based message extension to download the sample code for a Teams message extension using the latest Teams app manifest. For more information, see Teams developer manifest.

    The screenshot is an example that shows the Type 'Create a new Teams app' VS Code command palette to list Teams sample options.

    The sample is also available as NPM Search Connector in the Teams Toolkit Samples gallery. From the Teams Toolkit pane, select Development > View samples > NPM Search Connector.

    The screenshot is an example that shows the NPM Search Connector sample in Teams Toolkit Samples gallery.

  4. Select preferred programming language.

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

  6. Open the command palette (Ctrl+Shift+P) and type Teams: Provision in the cloud to create the required app resources (Azure App Service, App Service plan, Azure Bot, and Managed Identity) in your Azure account.

  7. Select a subscription and a resource group.

  8. Select Provision.

  9. Open the command palette (Ctrl+Shift+P) and type Teams: Deploy to the cloud to deploy the sample code to the provisioned resources in Azure and start the app.

  10. Select Deploy.

From here, you can skip ahead to Add Microsoft 365 Extensions channel for your bot to complete the final step of enabling the Teams message extension to work in Outlook. (The app manifest is already referencing the correct version, so no updates are necessary).

Update the app manifest

You need to use the Teams developer manifest schema version 1.13 (or higher) to enable your Teams message extension to run in Outlook. For more information on schema version, see Teams developer manifest.

You have two options for updating your app manifest:

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

If you used Teams Toolkit to create your message 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.

Add Microsoft 365 extensions channel for your bot

In Microsoft Teams, a message 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 message extension from Outlook, you need to add Microsoft 365 Extensions channel to your bot:

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

  2. From Settings, select Channels.

  3. Under Available channels, select Microsoft 365 Extensions (Preview) channel.

    The screenshot is an example that shows the Microsoft 365 Extensions (Preview) channel for your bot from the Azure Bot Channels pane.

  4. Select Apply.

    The screenshot is an example that shows the Microsoft 365 'Message Extensions' channel for your bot from the Azure Bot Channels pane.

  5. Confirm that your Microsoft 365 Extensions channel is listed along with Teams in your bot's Channels pane.

Update Microsoft Azure Active Directory (Azure AD) app registration for SSO

Note

You can skip this step if you're using the sample app provided in this tutorial, as the scenario doesn't involve Azure Active Directory (AAD) single sign-on authentication.

Azure Active Directory (AD) single sign-on (SSO) for message extensions works the same way in Outlook as it does in Teams. However, you need to add several client application identifiers to the Azure AD app registration of your bot in your tenant's App registrations portal.

  1. Sign in to Azure portal with your sandbox tenant account.

  2. Open App registrations.

  3. Select the name of your application to open its app registration.

  4. Select Expose an API (under Manage).

  5. In the Authorized client applications section, ensure all of the following Client Id values are listed:

    Microsoft 365 client application Client ID
    Teams desktop and mobile 1fec8e78-bce4-4aaf-ab1b-5451cc387264
    Teams web 5e3ce6c0-2b1f-4285-8d4b-75ee78787346
    Outlook desktop d3590ed6-52b3-4102-aeff-aad2292ab01c
    Outlook Web Access 00000002-0000-0ff1-ce00-000000000000
    Outlook Web Access bc59ab01-8403-45c6-8796-ac3ef710b3e3

Sideload your updated message extension in Teams

The final step is to sideload your updated message extension (app package) into Teams. After you complete, message extension appears 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.

    The screenshot is an example that shows 'Zip Teams metadata package' option in Teams Toolkit extension for Visual Studio Code.

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

  3. Select Apps to open the Manage your apps pane. Then select Upload an app.

    The screenshot is an example that shows the 'Upload an app' option.

  4. Choose Upload a customized app option, select your app package, and install (Add) it to your Teams client.

    The screenshot is an example that shows the 'Upload a customized app' option in Teams.

After it's sideloaded 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 Windows desktop and the web.

Outlook on the web

To preview your app running in Outlook on the web:

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

  2. Select New message.

  3. Open More apps flyout menu on the bottom of the composition window.

    The screenshot is an example that shows the 'More apps' menu on the bottom of the mail composition window to use your message extension.

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

Outlook

To preview your app running in Outlook on Windows desktop:

  1. Launch Outlook and sign in with your test tenant credentials.

  2. Select New Email.

  3. Open the More Apps flyout menu on the top ribbon.

    The screenshot is an example that shows the 'More Apps' on the composition window ribbon to use your message extension.

Your message extension is listed, it opens an adjacent pane to display search results.

Troubleshooting

While your updated message extension will continue to run in Teams with full feature support for message extensions, there are limitations in this early preview of the Outlook-enabled experience to be aware of:

  • Message 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 isn't supported.
  • Action-based message extension commands aren't supported in Outlook. If your app has both search- and action-based commands, it will surface in Outlook, but the action menu won't be available.
  • Insertion of more than five Adaptive Cards in an email isn't supported; Adaptive Cards v1.5 and later aren't supported.
  • Card actions of type messageBack, imBack, invoke, and signin aren't supported for inserted cards. Support is limited to openURL: when selected, the user is redirected to the specified URL in a new tab.

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

Debugging

As you test your message 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 on where the bot request originates. For more information, see search based message extensions SDK.

Code sample

Sample Name Description Node.js
NPM Search Connector Use Teams Toolkit to build a message extension app. Works in Teams, Outlook. View
Teams Link Unfurling Simple Teams app to demonstrate link unfurling. Works in Teams, Outlook. View

Next step

Publish your app to be discoverable in Teams, Outlook, and Microsoft 365 app:

Publish Teams apps for Outlook and Microsoft 365 app