Create deep link to a Teams tab

  • 3 minutes

Deep links are a navigation mechanism that help users connect with features and information within Teams and Teams apps. In this unit, you learn how to create a deep link to a Teams tab.

For tabs, deep links can be useful to allow app users to browse through the contents within a tab. For instance, your app can have a bot that sends messages notifying the user of an important activity. When the user selects the notification, the deep link navigates to the tab where the user can view more details about the activity.

You can configure deep links in your app using the TeamsJS library. 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 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 */ }

The navigation behavior of a Teams app extended across Microsoft 365 Office is dependent on two factors:

  • The target that the deep link points to.
  • 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 will first open in the browser.

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.

To implement, add a copy link action to each item, in whatever way best suits your UI. When the user takes this action, call pages.shareDeepLink() to display a dialog containing a link that the user can copy to the clipboard. When you make this call, pass an ID for your item. You get it back in the context object when the link is followed and your tab is reloaded.

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

You need to replace the following parameters with the appropriate information:

  • subPageId: A unique identifier for the item within your page to which you're deep linking.
  • subPageLabel: A label for the item to use for displaying the deep link.
  • subPageWebUrl: A fallback URL to use if the client can't render the page.

For more information, review Pages Module.