Configuration and handling of deep links

Article
04/30/2024

You can configure your Teams app to execute deep links from different contexts such as personal tab, shared tab, chat message, and bot.

Personal or Shared tab

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. Apps can execute a deep link using the TeamsJS library. To execute a deep link, call the following API:

TeamsJS v2
TeamsJS v1

You can trigger the 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.

To trigger a deep link from your tab, call:

microsoftTeams.executeDeepLink(/*deepLink*/);

Chat message

You can configure your app to post messages to a chat and add deep links to them. The following are different ways you can include a deep link in a message:

Hyperlink text message

When you add a deep link to a hyperlinked Markdown text message, it's triggered and opened within Teams. Following is an example:

Example: [App](https://teams.microsoft.com/l/app/{appId}), where appId is your application ID. For more information, see app ID for different types of apps.

For more information, see use Markdown formatting in Teams.

Raw link text message

When you add a deep link to a raw text message, it's triggered and opened within Teams. Following is an example:

Example: https://teams.microsoft.com/l/app/{appId}, where appId is your application ID. For more information, see app ID for different types of apps.

Adaptive Card

You can include an openURL action in an Adaptive Card and add a deep link to it. The deep link is executed within Teams. As raw links or hyperlinks in an Adaptive Card open in the browser, we recommend that you use openURL action. For more information, see Action.OpenUrl.

Following is an example Adaptive Card payload:


{
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "type": "AdaptiveCard",
    "version": "1.5",
    "body": [
        {
            "type": "TextBlock",
            "text": "This card's action will open a URL"
        }
    ],
    "actions": [
        {
    "type": "Action.OpenUrl",
    "title": "Action.OpenUrl",
    "url": "https://teams.microsoft.com/l/app/{appId}"
    }
    ]
}

Handle deep links

When a deep link to a tab app is triggered, ensure that all parameters are set in that link for the tab context. It allows the tab context to identify the page, subpage, or label configured in the deep link and open the specific section. For more information, see Get context for your tab.

Consume a deep link from a tab

When Teams navigates to the tab through a deep link, Teams verifies if the subpage ID exists and retrieves it through the TeamsJS library.

If the tab is navigated through a deep link, the app.getContext() calls microsoftTeams.getContext() to verify if the subpage ID exists. In TeamsJS v2 library, the subpage ID is named as subPageId, and in v1, it's subEntityId. For more information, see PageInfo interface.

Share via