Modifica

Deep link to a workflow in Teams

  • Articolo

You can create a deep link to perform a specific task in Teams, such as to create a new chat, open a scheduling dialog, and navigate to audio-video call.

In this article, you’ll learn to create a deep link:

Applications can start a new chat with a list of users and provide additional information such as chat name and draft message by using the following format:

https://teams.microsoft.com/l/chat/0/0?users=<user1>,<user2>,...&topicName=<chat name>&message=<precanned text>

Example: https://teams.microsoft.com/l/chat/0/0?users=joe@contoso.com,bob@contoso.com&topicName=Prep%20For%20Meeting%20Tomorrow&message=Hi%20folks%2C%20kicking%20off%20a%20chat%20about%20our%20meeting%20tomorrow

The query parameters are:

  • users: The comma-separated list of user IDs representing the participants of the chat. The user that performs the action is always included as a participant. Currently, the User ID field supports the Microsoft Entra UserPrincipalName, such as an email address only.
  • topicName: An optional field for chat's display name if a chat has three or more users. If this field isn't specified, the chat's display name is based on the names of the participants.
  • message: An optional field for the message text that you want to insert into the current user's compose box while the chat is in a draft state.

To use this deep link with your bot, specify the deep link as the URL target in your card's button or tap action through the openUrl action type. Apps can also use Teams JavaScript client library (TeamsJS) v.2.0 or later to create this without having to manually prepare the deep link. The following example uses TeamsJS to check if chat capability is supported:

if(chat.isSupported()) {
    const chatPromise = chat.openGroupChat({ users: ["joe@contoso.com","bob@contoso.com"], topic: "Prep For Meeting Tomorrow", message: "Hi folks kicking off chat about our meeting tomorrow"});
    chatPromise.
      then((result) => {/*Successful operation*/}).
      catch((error) => {/*Unsuccessful operation*/});
}
else { /* handle case where capability isn't supported */ }

Note

If a chat already exists deep link opens in that chat.

You can create deep link in your Teams apps to open a meeting scheduling dialog and provide information, such as meeting title and participants using the following methods:

While we recommend the use of typed APIs of TeamsJS, it's possible to manually create deep links to the Teams built-in scheduling dialog.

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

https://teams.microsoft.com/l/meeting/new?subject=<meeting subject>&startTime=<date>&endTime=<date>&content=<content>&attendees=<user1>,<user2>,<user3>,...

Note

The search parameters don't support + signal in place of whitespace (``). Ensure your URI encoding code returns %20 for spaces. For example, ?subject=test%20subject is good, but ?subject=test+subject is bad.

The query parameters are:

  • attendees: An optional comma-separated list of user IDs representing the attendees of the meeting. The user performing the action is the meeting organizer. The user ID field supports only the Microsoft Entra UserPrincipalName, typically an email address.
  • startTime: The optional parameter for start time of the event. Start time should be in long ISO 8601 format, for example 2018-03-12T23:55:25+02:00.
  • endTime: An optional parameter for end time of the event, also in ISO 8601 format.
  • subject: An optional parameter for the meeting subject.
  • content: An optional parameter for the meeting details field.

Note

You can't specify the location as it isn't supported. You must specify the UTC offset, which includes time zones, when generating the start and end times.

To use this deep link with your bot, you can specify the deep link as the URL target in your card's button or as a tap action through the openUrl action type.

Example: https://teams.microsoft.com/l/meeting/new?subject=test%20subject&attendees=joe@contoso.com,bob@contoso.com&startTime=10%2F24%2F2018%2010%3A30%3A00&endTime=10%2F24%2F2018%2010%3A30%3A00&content=​​​​​​​test%3Acontent​​​​​​​​​​​​​​

You can also use TeamsJS v.2.0 or later in your Teams app to open the meeting scheduling dialog without having to manually prepare the link. In order to open the scheduling dialog in Teams, you must continue using the original deep-link URL based method, as Teams doesn't support the calendar capability yet:

// Open a scheduling dialog from your tab
if(calendar.isSupported()) {
   const calendarPromise = calendar.composeMeeting({
      attendees: ["joe@contoso.com", "bob@contoso.com"],
      content: "test content",
      endTime: "2018-10-24T10:30:00-07:00",
      startTime: "2018-10-24T10:00:00-07:00",
      subject: "test subject"});
   calendarPromise.
      then((result) => {/*Successful operation*/}).
      catch((error) => {/*Unsuccessful operation*/});
}
else { /* handle case where capability isn't supported */ }

For more information about working with the calendar, see calendar namespace in the API reference documentation.

You can configure your Teams apps to prepare a deep link for users to start one-on-one call, a group call, or video call. You can invoke audio only or audio-video calls to a single user or a group of users by specifying the call type and the participants. Before Teams places the call, the client prompts for a confirmation. If there's a group call, you can call a set of VoIP and PSTN users in the same deep link invocation.

In a video call, the Teams client asks for confirmation before turning on the caller's video for the call. The receiver of the call has a choice to respond through audio only or audio and video, through the Teams call notification window.

Note

This method can't be used for invoking a meeting.

You can configure deep links in one of the following two ways:

While we recommend the use of the typed APIs of TeamsJS v.2.0 or later, you can also use a manually configured deep link to start a call. Refer to the following formats:

Deep link Format Example
Make an audio call https://teams.microsoft.com/l/call/0/0?users=<user1>,<user2> https://teams.microsoft.com/l/call/0/0?users=joe@contoso.com
Make an audio and video call https://teams.microsoft.com/l/call/0/0?users=<user1>,<user2>&withVideo=true https://teams.microsoft.com/l/call/0/0?users=joe@contoso.com&withVideo=true
Make an audio and video call with an optional parameter source https://teams.microsoft.com/l/call/0/0?users=<user1>,<user2>&withVideo=true&source=demoApp https://teams.microsoft.com/l/call/0/0?users=joe@contoso.com&withVideo=true&source=demoApp
Make an audio and video call to a combination of VoIP and PSTN users https://teams.microsoft.com/l/call/0/0?users=<user1>,4:<phonenumber> https://teams.microsoft.com/l/call/0/0?users=joe@contoso.com,4:9876543210

Following are the query parameters:

  • users: A comma-separated list of user IDs representing the participants of the call. The user ID field supports the Microsoft Entra UserPrincipalName, typically an email address, or in a PSTN call, it supports a PSTN MRI 4:<phonenumber>.
  • withVideo: An optional parameter, which you can use to make a video call. Setting this parameter only turns on the caller's camera. The receiver of the call has a choice to answer through an audio or an audio and video call through the Teams call notification window.

Applications can also use TeamsJS v.2.0 or later to start calls without having to manually prepare these deep links. The following code demonstrates using TeamsJS to start a call:

if(call.isSupported()) {
    const callPromise = call.startCall({ targets: ["joe@contoso.com","bob@contoso.com","4:9876543210"], requestedModalities: [call.CallModalities.Audio], source: "demoApp"});
    callPromise.
      then((result) => {/*Successful operation*/}).
      catch((error) => {/*Unsuccessful operation*/});
}
else { /* handle case where capability isn't supported */ }

Generate a deep link to share content to stage in meetings

You can generate a deep link to share the app to stage and to start or join a meeting.

For deep links to share content to stage, see deep link to share content to stage in meetings.

You can generate a deep link to the meeting side panel in a meeting. Use the following format for a deep link to the meeting side panel:

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

Example:

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"}

By default, a deep link opens in a meeting side panel. To open a deep link directly in an app rather than the meeting side panel, add openInMeeting=false in the deep link format:

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

For more information, see deep link to a tab.

Deep link doesn't open in the meeting side panel in the following scenarios:

  • There's no active meeting.
  • The app doesn't have sidePanel context declared in the app manifest.
  • openInMeeting is set to false in the deep link.
  • The deep link is selected outside of the meeting window or component.
  • The deep link doesn't match the current meeting, such as a deep link created in another meeting.

Teams app can read the URL for joining a meeting URL through Graph APIs. This deep link brings up the UI for the user to join the meeting. For more information, see Get onlineMeeting and Get meeting details.

Code sample

Sample name Description .NET Node.js
Deep link consuming Subentity ID This sample shows how to use a deep link from a bot chat to a tab consuming the Subentity ID. It also shows deep links for:
- Navigating to an app
- Navigating to a chat
- Open a profile dialog
- Open a scheduling dialog		 View View