Edit

Deep link to a workflow in Teams

  • Article

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.

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 Azure Active Directory (Azure AD) 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 Java Script library 2.0 to create this without having to manually prepare the deep link. Following is an example using Microsoft Teams JavaScript client library (TeamsJS):

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.

Applications can open a meeting scheduling dialog and provide information such as meeting title and participants. While it's recommended to use the typed APIs of TeamsJS, it's possible to manually create deep links to the Teams built-in scheduling dialog. 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/meeting/new?subject=<meeting subject>&startTime=<date>&endTime=<date>&content=<content>&attendees=<user1>,<user2>,<user3>,...

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​​​​​​​​​​​​​​

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

Note

Currently, specifying the location isn't supported. You must specify the UTC offset, it means time zones, when generating your 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.

Applications can also use TeamsJS library 2.0 to open the meeting scheduling dialog without having to manually prepare the link. Refer to the following code sample, provided a note:

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

Note

In order to open the scheduling dialog in Teams, the developers need to continue using the original deep-link URL based method, since Teams doesn't support the calendar capability yet.

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

Applications can prepare a deep link for users to start one-on-one or a group audio 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 placing the call, Teams client prompts a confirmation to make the call. If there's a group call, you can call a set of VoIP users and a set of PSTN users in the same deep link invocation.

In a video call, the client asks for confirmation and turns 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 cannot be used for invoking a meeting.

While the use of the typed APIs of TeamsJS is recommended, you can also use a manually created 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: The comma-separated list of user IDs representing the participants of the call. Currently, the user ID field supports the Azure AD UserPrincipalName, typically an email address, or in a PSTN call, it supports a pstn mri 4:<phonenumber>.
  • withVideo: This is 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.
  • Source: This is an optional parameter, which informs about the source of the deep link.

Applications can also use TeamsJS library 2.0 to start calls without having to manually prepare these deep links. The following code demonstrates using the TeamsJS library 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 also generate a deep link to share the app to stage and start or join a meeting.

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

Note

  • Generating a deep link to share content to stage in meetings is available only in public developer preview.
  • Deep link to share content to stage in meeting is supported in Teams desktop client only.

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:

  • If there is no active meeting.
  • If the app doesn't have sidePanel context declared in the app manifest.
  • If openInMeeting=false is set in the deep link.
  • If deep link is selected outside of the meeting window or component.
  • If deep link doesn't match the current meeting for example, deep link is created from another meeting.

Application can read, join a meeting URL through Graph APIs. This deep link brings up the UI for the user to join that meeting.

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