Edit

Share via

Deep link to Teams chat

You can create a deep link to a Teams chatsuch as to start a new chatgo to a channel conversationand access a file within a channel.

You can navigate to or create private chats between users with the Microsoft Teams JavaScript client library (TeamsJS) by specifying the set of participants. If a chat doesn’t exist with the specified participantsthe user is navigated to an empty new chat.

When a user creates a new chat using a deep linkTeams creates the new chat in the draft state until the user sends the first message. You can also provide the name of the chat if it doesn’t already existalong with text that should be inserted into the user's compose box. Consider this a shortcut for the user taking the manual action of navigating to or creating the chat and then compose the message.

As a use-case exampleif you’re retrieving a Microsoft 365 user profile information from your bot as a cardthis deep link can allow the app user to easily chat with that person.

You can configure deep links to start a new chat in one of the following two ways:

While use of the typed APIs is recommendedyou can alternatively use the following format for a manually created deep link that you can use in a botconnectoror message extension card:

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

To use this deep link with your botspecify the deep link as the URL target in your card's button or tap action through the openUrl action type.

The query parameters are:

  • users: A comma-separated list of user IDs representing the participants of the chat. The user that performs the action is always included as a participant. The User ID parameter supports the Microsoft Entra UserPrincipalNamesuch as an email address only.
  • topicName: An optional parameter for chat's display name if a chat has three or more users. If this field isn't specifiedthe 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 app user's compose box while the chat is in the draft state.

Example: https://teams.microsoft.com/l/chat/0/[email protected],[email protected]&topicName=Prep%20For%20Meeting%20Tomorrow&message=Hi%20folks%2C%20kicking%20off%20a%20chat%20about%20our%20meeting%20tomorrow

The following example demonstrates how to open a chat message to a group of participants with an initial message. You can target the deep link to an existing or a new chat. If a chat already existsthe deep link opens in that chat.

if(chat.isSupported()) {
    const chatPromise = chat.openGroupChat({ users: ["[email protected]","[email protected]"]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 */ }

To navigate to a specific chat conversation in Teamsuse the following deep link format:

https://teams.microsoft.com/l/chat/<chatId>/conversations

The query parameter is chatIdwhich represents chat ID of the conversation. The supported format for chatId is 19:xxx.

To get the chat ID

In the chatpoint to a messageselect More options > Copy link. The copied link contains the chat IDwhich typically starts with 19:.

Example: https://teams.microsoft.com/l/chat/19:[email protected]/conversations

You can use the following deep link format to go to a particular conversation within channel thread:

https://teams.microsoft.com/l/message/<channelId>/<messageId>?tenantId=<tenantId>&groupId=<groupId>&parentMessageId=<parentMessageId>&teamName=<teamName>&channelName=<channelName>&createdTime=<createdTime>

The query parameters are:

  • channelId: Channel ID of the conversation. For example19:[email protected].
  • tenantId: Tenant IDsuch as 0d9b645f-597b-41f0-a2a3-ef103fbd91bb.
  • groupId: Group ID of the file. For example3606f714-ec2e-41b3-9ad1-6afb331bd35d.
  • parentMessageId: Parent message ID of the conversation.
  • teamName: Name of the team.
  • channelName: Name of the team's channel.

Note

You can see channelId and groupId in the URL from the channel.

Example: https://teams.microsoft.com/l/message/<channelId>/1648741500652?tenantId=<tenantId>&groupId=<groupId>&parentMessageId=1648741500652&teamName=<teamName>&channelName=<channelName>&createdTime=1648741500652

Use the following deep link format to navigate a user to a message in a personal or group chat in Teams:

https://teams.microsoft.com/l/message/{chatId}/{messageId}?tenantId=<tenantId>?context={"contextType":"chat"}

The query parameters are:

  • chatId: Chat ID of the conversation. The supported format for chatId is 19: xxx. For example19:253f5895-9a62-4362-8d38-43f0205c702c_f1b94dcf-0aa3-4989-bcdf-ef4a5ed00f86@unq.gbl.spaces.
    Apps can read a chat ID through app context in Teamsincoming payload to botor through Microsoft Graph APIs.

    Note

    For one-on-one chats with botthe incoming payload to bot contains the conversation ID in a:xxx format.

  • messageId: Unique message ID of each message in a chat. When a bot posts a message in chatthe messageId is returned. You can also get the messageId through Microsoft Graph APIs. For example1563480968434.
  • context: Specify the contextType as chat.

Example: https://teams.microsoft.com/l/message/19:253f5895-9a62-4362-8d38-43f0205c702c_f1b94dcf-0aa3-4989-bcdf-ef4a5ed00f86@unq.gbl.spaces/1563480968434?context=%7B%22contextType%22:%22chat%22%7D

You can start a conversation with a bot using a prepopulated message through a deep link. Use the bot ID prefixed with 28: in place of an email address. The format of the deep link is:

https://teams.microsoft.com/l/chat/0/0?users=28:[bot guid]&message=This%20message%20was%20triggered%20by%20a%20link!

The query parameter is bot guidwhich is the bot ID attribute in the app manifest.

Example: https://teams.microsoft.com/l/chat/0/0?users=28:47345678-2134-6534-9143-65146789012&message=This%20message%20was%20triggered%20by%20a%20link!

The deep link provided only loads the message into the chat text box of the botand doesn't send the message automatically. To send the messageyou must either select the Send button or select Enter.

To navigate to a particular teamuse the following deep link format:

https://teams.microsoft.com/l/team/<channelId>/conversations?groupId=<groupId>&tenantId=<tenantId>

The query parameters are:

  • channelId: Channel ID of the conversation (URL encoded). For example19%3ATWLPKo8lD4v8zDxyw4FnDYY-ovnBJG5CSjmrHUAoOz41%40thread.tacv2.
  • groupId: Group ID of the file. For example72602e12-78ac-474c-99d6-f619710353a9.
  • tenantId: Tenant IDsuch as aaaabbbb-0000-cccc-1111-dddd2222eeee.

Note

You can get channelId and groupId in the URL from the team.

Example: https://teams.microsoft.com/l/team/19%3ATWLPKo8lD4v8zDxyw4FnDYY-ovnBJG5CSjmrHUAoOz41%40thread.tacv2/conversations?groupId=72602e12-78ac-474c-99d6-f619710353a9&tenantId=aaaabbbb-0000-cccc-1111-dddd2222eeee

You can use the following deep link formats to navigate to particular channels:

  • Standard channel: https://teams.microsoft.com/l/channel/<channelId>/<channelName>?groupId=<groupId>&tenantId=<tenantId>

    Example: https://teams.microsoft.com/l/channel/19%3A9be3de4e70874c71a608dee9ba803ed3%40thread.tacv2/My%20example%20channel?groupId=72602e12-78ac-474c-99d6-f619710353a9&tenantId=aaaabbbb-0000-cccc-1111-dddd2222eeee

  • Private channel: https://teams.microsoft.com/l/channel/<channelId>/<channelName>?groupId=<groupId>&tenantId=<tenantId>&ngc=true

    Example: https://teams.microsoft.com/l/channel/19%3A9be3de4e70874c71a608dee9ba803ed3%40thread.tacv2/My%20example%20channel?groupId=72602e12-78ac-474c-99d6-f619710353a9&tenantId=aaaabbbb-0000-cccc-1111-dddd2222eeee&ngc=true

  • Shared channel: https://teams.microsoft.com/l/channel/<channelId>/<channelName>?groupId=<groupId>&tenantId=<tenantId>&ngc=true&allowXTenantAccess=true

    Example: https://teams.microsoft.com/l/channel/19%3A9be3de4e70874c71a608dee9ba803ed3%40thread.tacv2/My%20example%20channel?groupId=72602e12-78ac-474c-99d6-f619710353a9&tenantId=aaaabbbb-0000-cccc-1111-dddd2222eeee&ngc=true&allowXTenantAccess=true

The query parameters are:

  • channelId: Channel ID of the conversation (URL encoded). For example19%3A9be3de4e70874c71a608dee9ba803ed3%40thread.tacv2.
  • channelName: Name of the team's channel (URL encoded). For exampleMy%20example%20channel.
  • groupId: Group ID of the team. For example72602e12-78ac-474c-99d6-f619710353a9.
  • tenantId: Tenant IDsuch as aaaabbbb-0000-cccc-1111-dddd2222eeee.
  • ngc: Indicates a next-generation channel. For private channels needs to be set to true.
  • allowXTenantAccess: Indicates a channel that can be accessed across tenant boundaries. For shared channels needs to be set to true.

Use the following deep link format can be used in a botconnectoror message extension card for configuring a deep link to connect to a file in a channel:

https://teams.microsoft.com/l/file/<fileId>?tenantId=<tenantId>&fileType=<fileType>&objectUrl=<objectUrl>&baseUrl=<baseUrl>&serviceName=<Name>&threadId=<threadId>&groupId=<groupId>

The query parameters are:

  • fileId: Unique file ID from Sharepoint Onlinealso known as sourcedoc or sharepointIds.listItemUniqueId from Sharepoint Online driveItem API response. For example1FA202A5-3762-4F10-B550-C04F81F6ACBD.
  • tenantId: Tenant IDsuch as 0d9b645f-597b-41f0-a2a3-ef103fbd91bb.
  • fileType: Supported file typesuch as .docx.pptx.xlsxand .pdf.
  • objectUrl: Object URL of the file. The format is https://{tenantName}.sharepoint.com/sites/{TeamName}/SharedDocuments/{ChannelName}/FileName.ext. For examplehttps://microsoft.sharepoint.com/teams/(filepath).
  • baseUrl: Base URL of the file. The format is https://{tenantName}.sharepoint.com/sites/{TeamName}. For examplehttps://microsoft.sharepoint.com/teams.
  • serviceName: Name of the serviceapp ID. For exampleteams.
  • threadId: The threadID is the team ID of the team where the file is stored. It's optional and can't be set for files stored in a user's OneDrive folder. For example19:<[email protected]>.
  • groupId: Group ID of the file. For exampleae063b79-5315-4ddb-ba70-27328ba6c31e.

Note

  • You can see threadId and groupId in the URL from the channel.
  • In the new Teams clientthe deep link format using objectURL for a file in a channel isn't supporteduse objectUrl in the deep link format.

The following example format illustrates the deep link to files:

https://teams.microsoft.com/l/file/5E0154FC-F2B4-4DA5-8CDA-F096E72C0A80?tenantId=0d9b645f-597b-41f0-a2a3-ef103fbd91bb&fileType=pptx&objectUrl=https%3A%2F%2Fmicrosoft.sharepoint.com%2Fteams%2FActionPlatform%2FShared%20Documents%2FFC7-%20Bot%20and%20Action%20Infra%2FKaizala%20Actions%20in%20Adaptive%20Cards%20-%20Deck.pptx&baseUrl=https%3A%2F%2Fmicrosoft.sharepoint.com%2Fteams%2FActionPlatform&serviceName=teams&threadId=19:[email protected]&groupId=ae063b79-5315-4ddb-ba70-27328ba6c31e

Serialization of this object

{
fileId: "5E0154FC-F2B4-4DA5-8CDA-F096E72C0A80",
tenantId: "0d9b645f-597b-41f0-a2a3-ef103fbd91bb",
filetype: = "pptx",
objectUrl: "https://microsoft.sharepoint.com/teams/ActionPlatform/Shared Documents/FC7- Bot and Action Infra/Kaizala Actions in Adaptive Cards - Deck.pptx",
baseUrl: "https://microsoft.sharepoint.com/teams/ActionPlatform",
serviceName: "teams",
threadId: = "19:[email protected]",
groupId: "ae063b79-5315-4ddb-ba70-27328ba6c31e"
}

Code Sample

Sample name Description .NET Node.
Deep link consuming Subentity ID This Teams sample application highlights deeplinks for various functionalitiessuch as initiating callschatsand navigating within tabs and apps. It features a comprehensive setup guide and supports interactions with both bots and tabs for enhanced user engagement. View View
  • Last updated on