Edit

Deep link to an application

  • Article

Application can open the profile dialog through deep links and help users to learn more about the application, permissions, and more. You can create a deep link for the app after the app is listed in the Teams store. To create a link to launch Teams, append the app ID to the URL, https://teams.microsoft.com/l/app/<appId>. A dialog appears to install or open the app.

If your app is approved for mobile platform, you can deep link to an app on mobile. Apple App Store Connect Team ID is required additionally for the deep link to work on Teams-iOS. For more information, see how to update Apple App Store Connect Team ID.

Deep link to an app isn't supported for custom apps.

Note

This topic reflects version 2.0.x of the Microsoft Teams JavaScript client library (TeamsJS). If you are using an earlier version, refer to the TeamsJS library overview for guidance on the differences between the latest TeamsJS and earlier versions.

Open the application profile dialog

You can open an app install dialog from your Teams app and also can install the app in other contexts. Use the following deep link format to open an app install dialog from your Teams:

https://teams.microsoft.com/l/app/<appId>, where <appId> is the application ID.

Applications can use the TeamsJS library to open the dialog without manually generating the deep link. Following is an example to open the app install dialog using TeamsJS:

// 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 */ }

For more information about the install dialog, see the appInstallDialog.openAppInstallDialog() function in the API reference documentation.

It's possible to navigate within an app using TeamsJS. The following code demonstrates how to navigate to a specific entity within your Teams app.

You can trigger navigation from your tab using the pages.navigateToApp() function as shown in the following code:

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 */ }

For more information about using the pages capability, see pages.navigateToApp() and the pages namespace for other navigation options. If needed, it's also possible to directly open a deep link using the app.openLink() function.

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 will open 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 navigate a user to a personal chat with the application by preparing the link manually using the following format:

https://teams.microsoft.com/l/entity/<appId>/conversations, where appId is your application ID and following lists appId for different apps:

  • Side loaded apps: Manifest ID
  • Apps submitted to org catalog: Org catalog ID
  • Apps submitted to Teams app store: Store ID

You can create deep links to entities in Teams apps. This method is used to create links that navigate to content and information within your tab. For example, if your tab contains a task list, team members can create and share links to individual tasks. When you select 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 context when the link is followed and your tab is reloaded.

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

You'll need to replace the fields 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, see pages.shareDeepLink().

Alternatively, you can also generate deep links programmatically using the format specified later in this article. You can use deep links in bot and connector messages that inform users about changes to your tab, or to items within it.

Note

  • This deep link is different from the links provided by the Copy link to tab menu item, which just generates a deep link that points to this tab.
  • Currently, shareDeepLink doesn't work on mobile platforms.

While it's recommended to use shareDeepLink() to generate a deep link to your tab, it's also possible to create one manually.

Note

  • Personal tabs have a personal scope, while channel and group tabs use team or group scopes. The two tab types have a slightly different syntax since only the configurable tab has a channel property associated with its context object. For more information on tab scopes, see the manifest reference.
  • Deep links work properly only if the tab was configured using the v0.4 or later library as it has an entity ID. Deep links to tabs without entity IDs still go to the tab but can't provide the subentity ID to the tab.

Use the following format for a deep link that you can use in a bot, connector, or message extension card:

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

Note

  • If the bot sends a message containing a TextBlock with a deep link, then a new browser tab is opened when the user selects the link. This happens in Chrome and in the Teams desktop app, both running on Linux.
  • If the bot sends the same deep link URL into an Action.OpenUrl, then the Teams tab opens in the current browser tab when the user selects the link.

The query parameters are:

Parameter name Description Example
appId  The ID from Teams Admin Center. fe4a8eba-2a31-4737-8e33-e5fae6fee194
entityId  The ID for the item in the tab, which you provided when configuring the tab. When generating a URL for deep linking, continue to use entity ID as a parameter name in the URL. When configuring the tab, the context object refers to the entityID as {page.id}. Tasklist123
entityWebUrl or subEntityWebUrl  An optional field with a fallback URL to use if the client doesn't support rendering the tab. https://tasklist.example.com/123 or https://tasklist.example.com/list123/task456
entityLabel or subEntityLabel  A label for the item in your tab to use when displaying the deep link. Task List 123 or Task 456
context.subEntityId  An ID for the item within the tab. When generating a URL for deep linking, continue to use subEntityId as the parameter name in the URL. When configuring the tab, the context object refers to the subEntityID as subPageID. Task456
context.channelId  Microsoft Teams channel ID that is available from the tab context. This property is only available in configurable tabs with a scope of team. It isn't available in static tabs, which have a scope of personal. 19:cbe3683f25094106b826c9cada3afbe0@thread.skype
context.chatId  Chat ID that is available from the tab context for group and meeting chat. 17:b42de192376346a7906a7dd5cb84b673@thread.v2
context.contextType  Chat is the only supported contextType for meetings. chat
openInMeeting  openInMeeting is used to control the user experience when the target tab is associated with a meeting. If user interacts with the deep link in an ongoing meeting experience, by default Teams opens the app in the in-meeting side panel. Set this value to false to always open the app in the meeting chat tab rather than the side panel, regardless of the meeting status. Teams ignore any value other than false. false

Examples:

  • Link to a static (personal) tab itself:

    https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123&label=Task List 123

  • Link to a task item within the static (personal) tab:

    https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123/456&label=Task 456&context={"subEntityId": "task456"}

  • Link to a configurable tab itself:

    https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123&label=Task List 123&context={"channelId": "19:cbe3683f25094106b826c9cada3afbe0@thread.skype"}

  • Link to a task item within the configurable tab:

    https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123/456&label=Task 456&context={"subEntityId": "task456","channelId": "19:cbe3683f25094106b826c9cada3afbe0@thread.skype"}

  • Link to a tab app added to a meeting or group chat:

    https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123/456&label=Task 456?context={"chatId": "17:b42de192376346a7906a7dd5cb84b673@thread.v2","contextType":"chat"}

Important

Ensure that all the query parameters and the white spaces are properly URI encoded. You must follow the preceding examples using the last example:

var encodedWebUrl = encodeURIComponent(JSON.stringify('https://tasklist.example.com/123/456&label=Task 456'));
var encodedContext = encodeURIComponent(JSON.stringify({"subEntityId": "task456"}));
var taskItemUrl = 'https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=' + encodedWebUrl + '&context=' + encodedContext;

You can navigate to content in Teams from your tab using TeamsJS or deep links. This is useful if your tab needs to connect users with other content in Teams, such as to a channel, message, another tab, or to open a scheduling dialog. Formerly, navigation might have required a deep link, but it can now in many instances be accomplished using the TeamsJS library. But where possible use of the typed capabilities of the TeamsJS library is recommended.

One of the benefits of using TeamsJS, particularly for Teams app that might run in other hosts (Outlook and Office), is that it's possible to check if the host supports the capability you're attempting to use. To check a host's support of a capability, you can use the isSupported() function associated with the namespace of the API. The TeamsJS library organizes APIs into capabilities by way of namespaces. For example, prior to usage of an API in the pages namespace you can check the returned Boolean value from pages.isSupported() and take the appropriate action within the context of your app and apps UI.

For more information about capabilities and the APIs in the TeamsJS library, see Building tabs and other hosted experiences with the TeamsJS library.

You can use the following deep link format in a bot, connector, or message extension card: https://teams.microsoft.com/l/entity/<appId>/<EntityId>?webUrl=<entityWebUrl>/<EntityName>.

Note

  • When a bot sends a TextBlock message with a deep link, a new browser tab opens when users select the link. This happens in Chrome and Microsoft Teams desktop app running on Linux.
  • If the bot sends the same deep link URL in an Action.OpenUrl, the Teams tab opens in the current browser when the user selects the link. No new browser tab is opened.

The query parameters are:

  • appID: Your manifest ID, for example fe4a8eba-2a31-4737-8e33-e5fae6fee194.

  • entityID: The item ID that you provided when configuring the tab. For example, tasklist123.

  • entityWebUrl: An optional field with a fallback URL to use if the client doesn't support rendering of the tab - https://tasklist.example.com/123 or https://tasklist.example.com/list123/task456.

  • entityName: A label for the item in your tab to use when displaying the deep link, Task List 123 or Task 456.

Example: https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123&TaskList

A task module deep link is a serialization of the TaskInfo object with two other details, the APP_ID and optionally the BOT_APP_ID:

  • https://teams.microsoft.com/l/task/APP_ID?url=<TaskInfo.url>&height=<TaskInfo.height>&width=<TaskInfo.width>&title=<TaskInfo.title>&completionBotId=BOT_APP_ID

  • https://teams.microsoft.com/l/task/APP_ID?card=<TaskInfo.card>&height=<TaskInfo.height>&width=<TaskInfo.width>&title=<TaskInfo.title>&completionBotId=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.

Tip

Encode the deep link URL when using the card parameter, for example, JavaScript encodeURI() function.

The following table provides information on APP_ID and BOT_APP_ID:

Value Type Required Description
APP_ID string Yes The ID of the app invoking the task module. The validDomains array in the manifest for APP_ID must contain the domain for url if url is in the URL. The app ID is already known when a task module is invoked from a tab or a bot, which is why it isn't included in TaskInfo.
BOT_APP_ID string No If a value for completionBotId is specified, the result object is sent using a task/submit invoke message to the specified bot. BOT_APP_ID must be specified as a bot in the app's manifest, that is you can't send it to any bot.

Note

APP_ID and BOT_APP_ID can be the same in many cases, if an app has a recommended bot to use as an app's ID and if there is one.

Code Sample

Sample name Description .NET Node.js
Deep link consuming Subentity ID This sample shows how to use deep-link from bot chat to tab consuming Subentity ID. It also shows deeplinks for navigate to app, navigate to chat, open profile dialog and open scheduling dialog. View View