Deep link to an application

Deep links in Microsoft Teams are powerful tools that allow users to navigate directly to specific content or actions within an app. Deep links are configured to perform various actions such as opening a tab, initiating an app install dialog, or browsing within the app.

Deep link scenarios

Here are some of the scenarios where you can use a deep link:

• App installation: You can use deep links that allow users to know more about an app and install it in different scopes.
• Bots and connectors: You can use deep links in bots and connectors messages to inform users about changes to your tab or its items.
• Navigate to specific page: You can create deep links that allow users to navigate to specific pages within your app.
• Custom app: You can generate deep links for a custom app. However, if an app in the Microsoft Teams Store shares the same app ID as the custom app ID, the deep link opens the app from Teams Store instead of the custom app.
• For mobile: You can also create a deep link to an app for mobile after your app is approved for the Teams mobile client. For the deep link to work on Teams iOS, you need the Apple App Store Connect Team ID. For more information, see how to update Apple App Store Connect Team ID.

Deep link to open an app install dialog

Deep links allow app users to open an app install dialog to know any information about the app or install it in different contexts. You can create a deep link to an app in the following ways:

• Configure deep link manually using the app ID
• Configure deep link using TeamsJS

Configure deep link manually using the app ID

With deep link, you can open an app installation dialog directly from your Teams client using the app ID.

App ID for different types of apps

The following table lists the different types of app IDs used for different types of apps for deep links:

For more information, see how to find ID based on the app manifest ID.

Configure deep link using TeamsJS

Apps can use the Microsoft Teams JavaScript client library (TeamsJS) to initiate the app install dialog, eliminating the need for manual deep link generation. Here's an example of how to trigger the app install dialog using TeamsJS within your app:

// Open an app install dialog from your tab
if(appInstallDialog.isSupported()) {
    const dialogPromise = appInstallDialog.openAppInstallDialog({ appId: "<appId>" });
    dialogPromise.
      then((result) => {/*Successful operation*/}).
      catch((error) => {/*Unsuccessful operation*/});
}
else { /* handle case where capability isn't supported */ }

// Open an app install dialog from your tab
microsoftTeams.executeDeepLink("https://teams.microsoft.com/l/app/<appId>");

For more information, see appInstallDialog.

Deep link to browse within your app

App users can browse content in Teams from your tab using TeamsJS. You can use a deep link to browse within your app if your tab needs to connect users with other content in Teams, such as a channel, message, another tab, or to open a scheduling dialog. In a few instances, navigation can also be accomplished using TeamsJS, and we recommend using the typed capabilities of TeamsJS wherever possible.

You can configure deep links to browse within your app in the following ways:

• Configure deep link to browse within your app manually
• Configure deep link to a tab using TeamsJS
• Configure deep link to navigate between tabs

Configure deep link to browse within your app manually

Personal tabs have a personal scope, while channel and group tabs use team or group scopes. The two tab types have slightly different syntax since only the configurable tab has a channel property associated with its context object. For more information on tab scopes, see app manifest.

Query parameters

Configure deep link to a tab using TeamsJS

You can configure deep links in your app through TeamsJS to allow users to browse different pages within your app. The navigation behavior of a Teams app extended across Microsoft 365 Office is dependent on two factors:

1. The target that the deep link points to.
2. The host where the Teams app is running.

If the Teams app is running within the host where the deep link is targeted, your app opens directly within the host. However, if the Teams app is running in a different host from where the deep link is targeted, the app first opens in the browser.

The following code demonstrates how to navigate to a specific entity within your Teams app:

if (pages.isSupported()) {
  const navPromise = pages.navigateToApp({ appId: <appId>, pageId: <pageId>, webUrl: <webUrl>, subPageId: <subPageId>, channelId:<channelId>});
  navPromise.
     then((result) => {/*Successful navigation*/}).
     catch((error) => {/*Failed navigation*/});
}
else { /* handle case where capability isn't supported */ }

microsoftTeams.executeDeepLink(/*deepLink*/);

• For more information, see navigate within a tab app.
• For more information on the pages capability, see pages.navigateToApp() and the pages namespace for other navigation options.
• To directly open a deep link using app.openLink(), see app.openLink() function.

Configure deep link to navigate between tabs

The pages capability of the TeamsJS library provides support for navigation between tabs within an app. Specifically, the pages.currentApp namespace offers a function navigateTo(NavigateWithinAppParams) to allow navigation to a specific tab within the current app and a function navigateToDefaultPage() to navigate to the first tab defined in the app's manifest. The following code illustrates how to navigate to a specific and default tab:

if (pages.currentApp.isSupported()) {
    const navPromise = pages.currentApp.navigateTo({pageId: <pageId>, subPageId: <subPageId>});
    navPromise.
        then((result) => {/*Successful navigation*/}).
        catch((error) => {/*Failed navigation*/});
}
else {/*Handle situation where capability isn't supported*/
    const navPromise = pages.navigateToApp({appId: <appId>, pageId: <pageId>});
    navPromise.
        then((result) => {/*Successful navigation*/}).
        catch((error) => {/*Failed navigation*/});
}

if (pages.currentApp.isSupported()) {
    const navPromise = pages.currentApp.navigateToDefaultPage();
    navPromise.
        then((result) => {/*Successful navigation*/}).
        catch((error) => {/*Failed navigation*/});
}
else {/*Handle situation where capability isn't supported*/}

Configure back button navigation

When an app has multiple tabs, a user can use the Microsoft 365 host app's back button to go backwards through the navigational history. However, the history doesn't include the actions a user performs within a tab. If you want to enhance the back button experience, you can maintain your own internal navigation stack and configure a custom handler for back button selections. This can be accomplished through the registerBackButtonHandler() function in the pages.backStack namespace.

After you register the handler, it helps you to address the navigational request before the system takes action. If the handler is able to manage the request, it should return true so that the system knows no further action is necessary. If the internal stack is empty, it should return false so that the system can call the navigateBack() function instead and take the appropriate action.

Return focus to host app

After the user starts using elements within a tab, by default, the focus remains with the elements of your iFrame until the user selects outside of it. If the iFrame is a part of the user navigating with keyboard shortcuts (the Tab key or the F6 key), you can focus on the host app. You can focus on the host app by using the pages.returnFocus() function. The returnFocus() function accepts a Boolean indicating the direction to advance focus within the host app; true for forward and false for backwards. Generally, forward highlights the search bar and backwards highlights the app bar.

Deep link to a chat with the application

You can allow app users to browse to a personal chat with the application by configuring the deep link manually.

Share a deep link for a tab

You can share deep links to entities in Teams apps to navigate to the content and information within your tab app. For example, if your tab app contains a task list, team members can create and share links to individual tasks. When the app user selects the link, it navigates to your tab that focuses on the specific item.

pages.shareDeepLink({ subPageId: <subPageId>, subPageLabel: <subPageLabel>, subPageWebUrl: <subPageWebUrl> })

microsoftTeams.shareDeepLink({ subEntityId: <subEntityId>, subEntityLabel: <subEntityLabel>, subEntityWebUrl: <subEntityWebUrl> })

Deep link for SharePoint Framework tabs

Deep links for SharePoint Framework (SPFx) tabs allow users to navigate directly to specific tabs within a SharePoint site or Teams app. This enhances user experience by providing quick access to relevant content and functionality.

Query parameters

Deep link to open a dialog

A dialog deep link is a serialization of the TaskInfo object with two other details, the APP_ID and optionally the BOT_APP_ID.

For the data types and allowable values for <TaskInfo.url>, <TaskInfo.card>, <TaskInfo.height>, <TaskInfo.width>, and <TaskInfo.title>, see TaskInfo object.

The following table provides information on APP_ID and BOT_APP_ID:

Deep link to share content in meeting stage

You can also generate a deep link to share the app to stage and start or join a meeting.

For deep links to share content to stage, see deep link to share content to stage in meetings.

Deep link to meeting side panel

You can generate a deep link to the meeting side panel in a meeting.

By default, a deep link opens in a meeting side panel. To open a deep link directly in an app rather than the meeting side panel, add openInMeeting=false as shown in the following deep link format:

https://teams.microsoft.com/l/entity/<appId>/<entityId>?webUrl=<entityWebUrl>&label=<entityLabel>&context=<context>&openInMeeting=false

For more information, see deep link to a tab.

A deep link doesn't open in the meeting side panel in the following scenarios:

• There's no active meeting.
• The app doesn't have sidePanel context declared in the app manifest.
• openInMeeting is set to false in the deep link.
• The deep link is selected outside of the meeting window or component.
• The deep link doesn't match the current meeting, for example, if the deep link is created from another meeting.

Deep link to invoke Stageview

You can invoke Stageview through a deep link from your tab by wrapping the deep link URL in the app.openLink(url) API. The deep link can also be passed through an OpenURL action in the card. The openMode property defined in the API determines the Stageview response. For more information, see invoke Stageview through deep link.

Best practices

• Deep links work properly only if the tab was configured using the library v0.4 or later, as it has an entity ID. Deep links to tabs without entity IDs still go to the tab but can't provide the sub`EntityId to the tab.
• In Microsoft Windows, Teams can't handle deep links exceeding 2048 characters due to the INTERNET_MAX_URL_LENGTH limit in Windows ShellExecuteEx API.
• When creating a deep link, ensure that the path to the Teams client and other metadata fit within this limit.
• If your deep link contains large data, include a unique identifier in the link that your app can use to fetch the necessary data from your backend service.

Code sample