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: Users can search an external system and share results through the compose message area of the client.
Action-based message extensions: Users can use 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 act on cards sent from Outlook on the web or Outlook for Windows.

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

Channel requirements for Copilot plugins

Copilot plugins that use a bot must have the Microsoft 365 channel enabled in Azure portal (Bot Channels Registration). If this channel is missing, disabled, or misconfigured, Microsoft 365 Copilot can’t route requests to your bot. This issue can result in HTTP 500 errors, missing responses, or other runtime failures.

Important

Message extensions in Outlook require the Microsoft 365 channel. If you enabled the Outlook channel previously, enable the Microsoft 365 channel instead and disable the Outlook channel.

If you see an HTTP 500 error, the following checks may help you troubleshoot the issue before reaching out to Azure support:

Go to the Azure portal > Bot Channels Registration > Channels and verify that the Microsoft 365 channel is enabled.
Confirm that Teams channel is enabled and not in an error state.
Verify that the Message Endpoint is correct and up-to-date in Bot Channels Registration > Settings.
Ensure that your plugin or Teams app manifest uses manifestVersion 1.16 or later and includes runtime configuration with Microsoft 365 as a supported host.
Test the bot outside of Copilot by calling the bot API directly or by using the Agents Playground. If the bot fails outside Copilot, the issue is likely in the bot code or backend service.

For more information, see Add Microsoft 365 channel for your app.

Prerequisites

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

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 Microsoft 365 Agents 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 Microsoft 365 Agents Toolkit (previously known as Teams Toolkit) or extend an existing Teams message extension app to Outlook.

Build a message extension app for Outlook
Extend an existing Teams message extension app to Outlook

You can build a Teams message extension app for Outlook through Agents 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
Action-based message extension

Open Visual Studio Code.
Select Command Palette... under the View option or Ctrl+Shift+P.
Select Microsoft 365 Agents: Create New Agent/App.
Select Teams Agents and Apps.
Select Other Teams Capabilities.
Select Message Extension from the dropdown list.
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.
Select a preferred programming language.
Select a location on your local machine for the workspace folder and enter your application name.
Select Command Palette... under the View option or Ctrl+Shift+P.
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.
Select a subscription and a resource group.
Select Provision. Alternatively, you can select Provision under the LIFECYCLE section of the extension.
Select Command Palette... under the View option or Ctrl+Shift+P.
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.
Select Deploy.

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

I ran into an issue

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 values:

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

Use Agents Toolkit to validate your app manifest and identify any errors.

Specify host runtime requirements

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

Note

If your bot previously used the Outlook channel, enable the Microsoft 365 channel to ensure your message extension works in Outlook.
An HTTP 500 error can occur if required channels aren't enabled.
Copilot in Teams also requires the Microsoft 365 channel.
Verify that both Teams and Microsoft 365 channels are active under Azure Bot > Channels.

Go to Microsoft Azure portal or Bot Framework portal (if you've previously registered there), go to your bot resource.
From Settings > Channels.
Under Available channels, select Microsoft 365 channel.
Select Apply.
Confirm that your Microsoft 365 channel is listed along with 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 Agents 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.

Sign in to Azure portal with your sandbox tenant account.
Select App registrations.
Select the name of your application to open its app registration.
Select Manage > Expose an API.

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

I ran into an issue

Upload your custom app in Teams

Upload your updated message extension as an app package into Teams. After you finish, the message extension appears in your installed Apps from the compose message area.

Create a .zip file with app manifest and app icons.
Go to Teams and sign in by using your sandbox tenant account.
Select Apps > Manage your apps > Upload an app.
Select the Upload a custom app option, select your .zip file, and install (Add) it to your Teams client.

After you upload the app 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:

Sign in to outlook.com by using your test tenant credentials.
Select New message.
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, 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.
Outlook supports action-based message extensions that send cards into the compose box. 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 be in Teams.

Use the 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	This sample app showcases a Node.js bot that implements link unfurling within Teams messaging extensions.	View
Tab in Stageview	This sample app demonstrates the use of Teams tab in stage view using Node.js, featuring collaborative elements and interactive capabilities.	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

Feedback

Was this page helpful?

Last updated on 2026-02-06

Share via

Extend a Teams message extension across Microsoft 365

Channel requirements for Copilot plugins

Prerequisites

Build or extend a message extension

Upload your custom app in Teams

Preview your message extension in Outlook

Debugging

Limitations

Code sample

Next step

Feedback

Additional resources