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:

• Check for message extensions support within Outlook for Windows desktop, web, and mobile, see the support table in extend Teams apps across Microsoft 365.
• A Microsoft 365 Developer Program sandbox tenant. For action based message extension, enroll your developer tenant for Microsoft 365 Targeted Releases.
• A test environment with Microsoft 365 apps installed from the Microsoft 365 Apps Current Channel.
• (Optional) Microsoft Visual Studio Code with the Teams Toolkit extension.

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.

Build a message extension app for 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:

• Upload your app in Teams
• Preview your message extension in Outlook

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

Search-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).

   

   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.

   

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.

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 Collect Form Input and Process Data to download the sample code for a Teams action-based message extension using the latest app manifest (previously called Teams app manifest).

   

6. Select 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.

Extend an existing Teams message extension app to Outlook

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

• Update your app manifest.
• Add the Microsoft 365 channel for your app.
• Update Microsoft Entra app registration for SSO.
• Upload your updated app in Teams.
• Preview your message extension in Outlook

Update your app manifest

Update the app manifest (previously called Teams app manifest) schema version 1.13 or later to enable your Teams message extension to run in Outlook.

Open your app manifest and update the $schema and manifestVersion with the following values:

{
"$schema" : "https://developer.microsoft.com/json-schemas/teams/v1.16/MicrosoftTeams.schema.json",
"manifestVersion" : "1.16"
}

You can use Teams Toolkit to validate your app manifest and identify any errors.

Specify host runtime requirements (developer preview)

To ensure your app always provides customers with high-quality experiences, you can tailor your app's behavior in applicable Microsoft 365 hosts, or omit it from surfacing in contexts that you're not ready to support. Use app manifest to specify any dependency relationships across capabilities of your app, and specific runtime requirements of your static tabs, message extensions, and bots.

For more information, see how to specify Microsoft 365 host runtime requirements in your app manifest.

Add Microsoft 365 channel for your app

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 the advantage of 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 enable the Microsoft 365 channel for your Azure bot resource of the message extension app.

Note

If you've previously enabled the Outlook channel for your bot, you'll need to enable the Microsoft 365 channel for your message extension to function correctly in Microsoft Outlook. The Outlook channel is no longer used for message extensions running in Outlook and can be disabled.

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

2. From Settings > Channels.

3. Under Available channels, select Microsoft 365 channel.

   

4. Select Apply.

   

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

Update Microsoft Entra app registration for SSO

Note

You can skip this step if you're building an app for Outlook using Teams Toolkit, as the scenario doesn't involve Microsoft Entra single sign-on authentication.

Microsoft Entra 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 Microsoft Entra app registration of your bot in your tenant's App registrations portal.

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

2. Select App registrations.

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

4. Select Manage > Expose an API.

5. In the Authorized client applications section, ensure all 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
   Microsoft 365 web	4765445b-32c6-49b0-83e6-1d93765276ca
   Microsoft 365 desktop	0ec893e0-5785-4de6-99da-4ed124e5296c
   Microsoft 365 mobile	d3590ed6-52b3-4102-aeff-aad2292ab01c
   Outlook desktop	d3590ed6-52b3-4102-aeff-aad2292ab01c
   Outlook Web Access	bc59ab01-8403-45c6-8796-ac3ef710b3e3
   Outlook mobile	27922004-5251-4030-b22d-91ecd9a37ea4

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.

   

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

   

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.

   

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

Publish Teams apps for Outlook and Microsoft 365 app