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 EntraUserPrincipalName，例如电子邮件地址。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
配置深层链接以使用 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 */ }
用于导航到聊天的深层链接
若要导航到 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"}
例如：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
查询参数为：
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 指定为聊天。
例如：http://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
用于导航到团队的深层链接
若要导航到特定团队，请使用以下深层链接格式：
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
用于导航到频道的深层链接
可以使用以下深层链接格式导航到特定通道：
标准通道：
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。 例如，1FA202A5-3762-4F10-B550-C04F81F6ACBD。tenantId：租户 ID，例如0d9b645f-597b-41f0-a2a3-ef103fbd91bb。fileType：支持的文件类型，如 .docx、.pptx、.xlsx 和 .pdfobjectUrl：文件的对象 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 |
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈