通过

Teams 聊天的深层链接

  • 项目

可以创建指向 Teams 聊天的深层链接，例如开始新聊天、转到频道对话以及访问频道中的文件。

可以通过指定一组参与者，导航到使用 Microsoft Teams JavaScript 客户端库 (TeamsJS) 的用户之间创建私人聊天。 如果不存在与指定参与者的聊天，则会将用户导航到空的新聊天。

当用户使用深层链接创建新聊天时，Teams 会以草稿状态创建新聊天，直到用户发送第一条消息。 还可以提供聊天名称（如果尚不存在），以及应插入到用户的撰写框中的文本。 将此视为用户执行手动操作的快捷方式，即导航到或创建聊天，然后撰写消息。

例如，如果要从机器人检索Microsoft 365 用户配置文件信息作为卡，则此深层链接可让应用用户轻松与该用户聊天。

可以通过以下两种方式之一配置深层链接以开始新聊天：

虽然建议使用类型化 API，但也可以对手动创建的深层链接使用以下格式，以便在机器人、连接器或消息扩展卡中使用：

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

若要将此深层链接与机器人配合使用，请在卡按钮中指定深层链接作为 URL 目标，或通过操作openUrl类型点击操作。

查询参数为：

  • users：表示聊天参与者的用户 ID 的逗号分隔列表。 执行操作的用户始终作为参与者被包括在内。 User ID 参数仅支持 Microsoft Entra UserPrincipalName，例如电子邮件地址。
  • topicName：如果聊天有三个或更多用户，则为聊天显示名称的可选参数。 如果未指定此字段，则聊天的显示名称基于参与者的姓名。
  • message：要在聊天处于草稿状态时插入当前应用用户的撰写框中的消息文本的可选字段。

例如：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

以下示例演示如何使用初始消息向一组参与者打开聊天消息。 可以将深层链接定位到现有聊天或新聊天。 如果聊天已存在，则会在该聊天中打开深层链接。

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

若要导航到 Teams 中的特定聊天对话，请使用以下深层链接格式：

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

查询参数为 chatId，表示聊天的聊天 ID。 支持的格式 chatId 为 19：xxx。

例如：https://teams.microsoft.com/l/chat/19:c6d70e392a384916c3262b15406d763e@thread.v2/conversations

可以使用以下深层链接格式转到通道线程中的特定会话：

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

查询参数为：

  • channelId：会话的频道 ID。 例如，19:3997a8734ee5432bb9cdedb7c432ae7d@thread.tacv2。
  • tenantId：租户 ID，例如 0d9b645f-597b-41f0-a2a3-ef103fbd91bb。
  • groupId：文件的组 ID。 例如，3606f714-ec2e-41b3-9ad1-6afb331bd35d。
  • parentMessageId： 会话的父消息 ID。
  • teamName：团队名称。
  • channelName：团队频道的名称。

注意

可以在通道的 URL 中看到 channelId 和 groupId。

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

使用以下深层链接格式在 Teams 中将用户导航到个人或群组聊天中的邮件：

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

查询参数为：

  • chatId：对话的聊天 ID。 支持的格式 chatId 为 19： xxx。 例如，19:253f5895-9a62-4362-8d38-43f0205c702c_f1b94dcf-0aa3-4989-bcdf-ef4a5ed00f86@unq.gbl.spaces。
    应用可以通过 Teams 中的应用上下文、机器人的传入有效负载或通过 Microsoft Graph API 读取聊天 ID。

    注意

    对于与机器人的一对一聊天，机器人的传入有效负载包含 a：xxx 格式的对话 ID。

  • messageId：聊天中每条消息的唯一消息 ID。 当机器人在聊天中发布消息时， messageId 将返回 。 还可以通过 Microsoft Graph API 获取 messageId 。 例如，1563480968434。
  • context：将 contextType 指定为聊天。

例如：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

可以通过深层链接使用预填充的消息与机器人开始对话。 使用前缀为 28: 前缀的机器人 ID 代替电子邮件地址。 深层链接的格式为：

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

查询参数为 bot guid，它是应用清单中的机器人 ID 属性。

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

提供的深层链接仅将消息加载到机器人的聊天文本框中，不会自动发送消息。 若要发送邮件，必须选择“ 发送 ”按钮或选择 Enter。

若要导航到特定团队，请使用以下深层链接格式：

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

查询参数为：

  • channelId：会话 (URL 编码) 的通道 ID。 例如，19%3ATWLPKo8lD4v8zDxyw4FnDYY-ovnBJG5CSjmrHUAoOz41%40thread.tacv2。
  • groupId：文件的组 ID。 例如，72602e12-78ac-474c-99d6-f619710353a9。
  • tenantId：租户 ID，例如 72f988bf-86f1-41af-91ab-2d7cd011db47。

注意

可以在团队的 URL 中获取 channelId 和 groupId 。

例如：https://teams.microsoft.com/l/team/19%3ATWLPKo8lD4v8zDxyw4FnDYY-ovnBJG5CSjmrHUAoOz41%40thread.tacv2/conversations?groupId=72602e12-78ac-474c-99d6-f619710353a9&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47

可以使用以下深层链接格式导航到特定通道：

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

    例如：https://teams.microsoft.com/l/channel/19%3A9be3de4e70874c71a608dee9ba803ed3%40thread.tacv2/My%20example%20channel?groupId=72602e12-78ac-474c-99d6-f619710353a9&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47

  • 专用频道： https://teams.microsoft.com/l/channel/<channelId>/<channelName>?groupId=<groupId>&tenantId=<tenantId>&ngc=true

    例如：https://teams.microsoft.com/l/channel/19%3A9be3de4e70874c71a608dee9ba803ed3%40thread.tacv2/My%20example%20channel?groupId=72602e12-78ac-474c-99d6-f619710353a9&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47&ngc=true

  • 共享频道： https://teams.microsoft.com/l/channel/<channelId>/<channelName>?groupId=<groupId>&tenantId=<tenantId>&ngc=true&allowXTenantAccess=true

    例如：https://teams.microsoft.com/l/channel/19%3A9be3de4e70874c71a608dee9ba803ed3%40thread.tacv2/My%20example%20channel?groupId=72602e12-78ac-474c-99d6-f619710353a9&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47&ngc=true&allowXTenantAccess=true

查询参数为：

  • channelId：会话 (URL 编码) 的通道 ID。 例如，19%3A9be3de4e70874c71a608dee9ba803ed3%40thread.tacv2。
  • channelName：) 编码的团队频道 (URL 的名称。 例如，My%20example%20channel。
  • groupId：团队的组 ID。 例如，72602e12-78ac-474c-99d6-f619710353a9。
  • tenantId：租户 ID，例如 72f988bf-86f1-41af-91ab-2d7cd011db47。
  • ngc：指示下一代通道。 对于专用频道，需要设置为 true。
  • allowXTenantAccess：指示可以跨租户边界访问的通道。 对于共享频道，需要设置为 true。

在机器人、连接器或消息扩展中使用以下深层链接格式，卡配置深层链接以连接到通道中的文件：

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

查询参数为：

  • fileId：Sharepoint Online 中的唯一文件 ID，也称为 sourcedoc 或 sharepointIds.listItemUniqueId 来自 Sharepoint Online driveItem API 响应。 例如，1FA202A5-3762-4F10-B550-C04F81F6ACBD。
  • tenantId：租户 ID，例如 0d9b645f-597b-41f0-a2a3-ef103fbd91bb。
  • fileType：支持的文件类型，如 .docx、.pptx、.xlsx 和 .pdf
  • objectUrl：文件的对象 URL。 格式为 https://{tenantName}.sharepoint.com/sites/{TeamName}/SharedDocuments/{ChannelName}/FileName.ext。 例如，https://microsoft.sharepoint.com/teams/(filepath)。
  • baseUrl：文件的基本 URL。 格式为 https://{tenantName}.sharepoint.com/sites/{TeamName}。 例如，https://microsoft.sharepoint.com/teams。
  • serviceName：服务名称、应用 ID。 例如，teams。
  • threadId：threadID 是存储文件的团队的团队 ID。 它是可选的，不能为存储在用户 OneDrive 文件夹中的文件设置。 例如，19:<f8fbfc4d89e24ef5b3b8692538cebeb7@thread.skype>。
  • groupId：文件的组 ID。 例如，ae063b79-5315-4ddb-ba70-27328ba6c31e。

注意

  • 可以在通道的 URL 中看到 threadId 和 groupId。
  • 在新 Teams 客户端中，不支持对通道中的文件使用 objectURL 深层链接格式，请在深层链接格式中使用 objectUrl 。

以下示例格式说明了指向文件的深层链接：

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:f8fbfc4d89e24ef5b3b8692538cebeb7@thread.skype&groupId=ae063b79-5315-4ddb-ba70-27328ba6c31e

此对象的序列化

{
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:f8fbfc4d89e24ef5b3b8692538cebeb7@thread.skype",
groupId: "ae063b79-5315-4ddb-ba70-27328ba6c31e"
}

代码示例

示例名称 Description .NET Node.js
使用子实体 ID 的深层链接 此示例演示如何使用从机器人聊天到使用子实体 ID 的选项卡的深层链接。 它还显示了以下项的深层链接：
- 导航到应用
- 导航到聊天
- 打开配置文件对话框
- 打开计划对话框		 View View