Create deep links to a Microsoft Teams tab

To every tab, Microsoft Teams adds a Copy link to tab menu item. This generates a deep link that points to this tab, which users can share. This deep link is in a different format than one you can generate yourself. This topic will describe this second type of deep link.

You can enable team members to create and share links to items within your tab, such as an individual task within a tab that contains a task list. When clicked, the link navigates to your tab, which focuses on the specific item. To implement this, you add a "copy link" action to each item, in whatever way best suits your UI. When the user takes this action, you call shareDeepLink() to display a dialog box containing a link that the user can copy to the clipboard. When you make this call, you also pass an ID for your item, which you get back in the context when the link is followed and your tab is reloaded.

Further, you can generate deep links programmatically, using the format specified later in this topic. You might want to use these in bot and Connector messages that inform users about changes to your tab, or to items within it.


Static tabs have a scope of "personal" and configurable tabs have a scope of "team". The two tab types have a slightly different syntax since only the configurable tab has a channel property associated with its context object. See the Manifest reference for more information on personal and team scopes.


Deep links work properly only if the tab was configured using the v0.4 or later library and because of that has an entity ID. Deep links to tabs without entity IDs still navigate to the tab but can't provide the sub-entity ID to the tab.

To show a dialog box that contains a deep link to an item within your tab, call microsoftTeams.shareDeepLink({ subEntityId: <subEntityId>, subEntityLabel: <subEntityLabel>, subEntityWebUrl: <subEntityWebUrl> })

The fields to provide are as follows:

  • subEntityId A unique identifier for the item within your tab to which you are deep linking
  • subEntityLabel A label for the item to use for displaying the deep link
  • subEntityWebUrl An optional field with a fallback URL to use if the client does not support rendering the tab

The format for a deep link that you can use in a bot or Connector message is as follows:<appId>/<entityId>?webUrl=<entityWebUrl>&label=<entityLabel>&context=<context>

The query parameters are:

  • appId The ID from your manifest; for example, "fe4a8eba-2a31-4737-8e33-e5fae6fee194"
  • entityId The ID for the item in the tab, which you provided when configuring the tab; for example, "tasklist123"
  • entityWebUrl or subEntityWebUrl An optional field with a fallback URL to use if the client does not support rendering the tab; for example, "" or "https//"
  • entityLabel or subEntityLabel A label for the item in your tab, to use when displaying the deep link; for example, "Task List 123" or "Task 456"
  • context A JSON object containing the following fields:
    • subEntityId An ID for the item within the tab; for example, "task456"
    • canvasUrl The URL to load in the tab (same as the contentUrl you provided when configuring the tab); for example, ""
    • channelId The Microsoft Teams channel ID (available from the tab context); for example, "". This property is only available in configurable tabs with a scope of "team". It is not available in static tabs, which have a scope of "personal".


canvasUrl is required but isn't currently used; it is reserved for future use.


  • Link to a configurable tab itself: List 123&context={"canvasUrl": "","channelId": ""}
  • Link to a task item within the configurable tab: 456&context={"subEntityId": "task456","canvasUrl": "","channelId": ""}
  • Link to a static tab itself: List 123
  • Link to a task item within the static tab: 456&context={"subEntityId": "task456"}


Ensure that the entire URL is URI encoded. For the sake of readability, the above examples are not, but you should. Using the last example:

var taskItemUrl = ' 456&context={"subEntityId": "task456"}';
var encodedUri = encodeURI(taskItemUrl);

When navigating to a deep link, Microsoft Teams simply navigates to the tab and provides a mechanism via the Microsoft Teams JavaScript library to retrieve the sub-entity ID (if it exists).

The microsoftTeams.getContext call returns a context that includes the subEntityId field if the tab was navigated to via a deep link.