Open content in multi-window

Microsoft Teams provides multiple methods to open your app content in immersive canvas experiences. Stageview allows users to adopt multitasking inside Teams, for example, you can open your app content in a new Teams window with a specific chat in the side panel. Stageview is designed to:

• Facilitate multitasking within Teams.
• Support collaboration in a Teams multi-window.
• Focus on specific tasks in a large modal experience.

Types of Stageview

Based on the UI and functionality, Stageview offers three ways to open your app content:

• Collaborative Stageview
• Stageview Multi-window
• Stageview Modal

Collaborative Stageview

Collaborative Stageview enables multitasking scenarios for your app content in Teams. Users can open and view your app content inside a new Teams window while accompanied by a side panel conversation. This view enables meaningful content engagement and collaboration from within the same window.

Best usage: When the content is opened from a conversation such as chat, channel, or channel tab.

👁 The screenshot shows the Collaborative Stageview in Teams.

Stageview Multi-window

Stageview Multi-window is useful for scenarios that require a user to multitask in Teams without the need for collaboration. This view opens the app content in a new Teams window without a side panel conversation allowing users to focus on their task.

Best usage: When the content is opened from a nonconversational surface such as a personal app.

👁 The screenshot shows the Stageview Multi-window in Teams.

Stageview Modal

Stageview Modal is a full-screen UI component used to render your app content inside the Teams main window. This view provides users with a focused experience to engage with the app content. Stageview Modal is useful for displaying rich content that doesn't require a user to multitask. It’s the default view when Collaborative Stageview and Stageview Multi-window aren't supported.

👁 The screenshot shows the Stageview Modal in Teams.

Invoke Stageview

You can invoke Stageview in Teams through one of the following methods and configure the expected Stageview response. The following table provides the default and defined response for each Stageview invoke method:

Invoke Collaborative Stageview from Adaptive Card

Collaborative Stageview from an Adaptive Card allows users to engage with your content while continuing the conversation flow. If Collaborative Stageview is invoked from an Adaptive Card JSON in Teams web client, it opens in a Stageview Modal.

The following steps help you to understand how Collaborative Stageview is invoked from an Adaptive Card:

1. When the user shares a URL for an app content in a Teams chat, the bot receives a composeExtensions/queryLink invoke request. The bot returns an Adaptive Card with the type tab/tabInfoAction.

2. After the user selects the action button on the Adaptive Card, Collaborative Stageview opens based on the content in the Adaptive Card.

👁 The graphical representation shows how Collaborative Stageview response from Adaptive Card.

The following JSON code is an example to create an action button in an Adaptive Card:

{
 "type": "Action.Submit",
 "title": "Open",
 "data": {
 "msteams": {
 "type": "invoke",
 "value": {
 "type": "tab/tabInfoAction",
 "tabInfo": {
 "contentUrl": "contentUrl",
 "websiteUrl": "websiteUrl",
 "name": "Sales Report",
 "entityId": "entityId"
 }
 }
 }
 }
}

Best practices to create an Adaptive Card

• The content URL must be within the list of validDomains in your app manifest.
• The invoke request type must be composeExtensions/queryLink.
• The invoke workflow must be similar to the appLinking workflow.
• The Action.Submit must be configured as Open to maintain consistency.

If your app isn't optimized to work in Teams mobile client, Stageview for apps published through the Microsoft Teams Store opens in a default web browser.

Invoke from stageView API

The stageView API from TeamsJS allows you to open the Teams window in a Stageview experience based on the openMode defined. If the openMode property isn't defined, the default response is a Collaborative Stageview with an associated side panel conversation. In a Collaborative Stageview experience, the side panel conversation is the same thread from where the Stageview was invoked such as chat or group chat.

The following codes are the samples for each openMode value in stageView API:

 {
 "appId": "2c19df50-1c3c-11ea-9327-cd28e4b6f7ba",
 "contentUrl": "https://teams-test-tab.azurewebsites.net",
 "title": "Test tab ordering",
 "websiteUrl": "https://teams-test-tab.azurewebsites.net",
 "openMode": "popoutWithChat"
 }

 {
 "appId": "2c19df50-1c3c-11ea-9327-cd28e4b6f7ba",
 "contentUrl": "https://teams-test-tab.azurewebsites.net",
 "title": "Test tab ordering",
 "websiteUrl": "https://teams-test-tab.azurewebsites.net",
 "openMode": "popout"
 }

 {
 "appId": "2c19df50-1c3c-11ea-9327-cd28e4b6f7ba",
 "contentUrl": "https://teams-test-tab.azurewebsites.net",
 "title": "Test tab ordering",
 "websiteUrl": "https://teams-test-tab.azurewebsites.net",
 "openMode": "modal"
 }

When openMode isn't defined in StageViewParams, the default response is Collaborative Stageview.

 {
 "appId": "2c19df50-1c3c-11ea-9327-cd28e4b6f7ba",
 "contentUrl": "https://teams-test-tab.azurewebsites.net",
 "title": "Test tab ordering",
 "websiteUrl": "https://teams-test-tab.azurewebsites.net"
 }

For more information on stageView API, see stageView module.

stageView API parameters

Invoke from deep link

To invoke Stageview through deep link from your tab or personal app, wrap the deep link URL in the app.openLink(url) API and define the openMode property for the chat content to open. When the openMode property isn't specified, Stageview response from a deep link defaults to Collaborative Stageview.

To display a specific chat in the side panel, you must specify a threadId. Otherwise, the side panel conversation brings the group chat or channel thread from which the deep link is invoked.

Syntax

Deep link syntax for Collaborative Stageview:

https://teams.microsoft.com/l/stage/{appId}/0?context={"contentUrl":"contentUrl","websiteUrl":"websiteUrl","name":"Contoso","openMode":"popoutWithChat","threadId":"threadId"}

Encoded deep link syntax for Collaborative Stageview:

https://teams.microsoft.com/l/stage/%7BappId%7D/0?context=%7B%22contentUrl%22:%22contentUrl%22,%22websiteUrl%22:%22websiteUrl%22,%22name%22:%22Contoso%22,%22openMode%22:%22popoutWithChat%22,%22threadId%22:%22threadId%22%7D

Deep link query parameters

Whether you want to facilitate multitasking, enhance collaboration, or provide focused user experience, Stageview has a mode to suit your requirements.

FAQs

Code sample

See also

Create deep links