Deep links to applications in Microsoft Teams
Microsoft Teams supports a linking mechanism known as "deep links". Deep links, when executed, direct Microsoft Teams to take the end user to a particular location within the application. For example, one could generate a deep link take a user to a static app page, or to a calendar invite, or to a chat thread.
The basics
As part of the Microsoft Teams SDK, there is a js function that executes deep links.
microsoftTeams.executeDeepLink(url)
Microsoft has developed a specification for generating deep links.
The most basic deep link is formatted as such:
https://teams.microsoft.com/l/entity/<appId>/<entityId>
Linking to an app
This style of deep link will actually direct the user to a personal app page. For example, if we were to create a deep link for the Frameable MultiShare application the link would be formatted in the following way:
In this case the appId the knonw public appId associated with the id field in our manifest file. The entityId is also found in our manifest in the staticTabs section.
However, there is an important caveat concerning the appId. If the app is approved and available in AppSource, the appId can be relied upon for the deep link. This will be different from an app that is loaded manually into the Teams Admin center.
What to do for side loaded apps
When an app is uploaded into the Teams Admin center the id in the manifest becomes knknown as the "external" application id. This id cannot be used to create a deep link. Instead one will need to perform an graph API request to get the generated app id in order to generate a deeplink. The graph request find this can be done in the following way, for an example guid of 8702e4d2-bb53-4a2f-b816-1db995045261
GET appCatalogs/teamsApps?filter=externalId eq '8702e4d2-bb53-4a2f-b816-1db995045261'
This will return the following payload:
{ "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#appCatalogs/teamsApps", "@odata.count": 1, "@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET appCatalogs/teamsApps?$select=displayName,distributionMethod", "value": [ { "id": "3d4ea7f9-0e7e-4af2-8059-83733c272e5a", "externalId": "8702e4d2-bb53-4a2f-b816-1db995045261", "displayName": "Our Fancy App", "distributionMethod": "organization" } ]}
Within the payload the body.value[0].id is the appId that should be used to create a deep link.
Learning more
See the official documentaion for more on how to create deep links and use them from within your applications.
