通过

Teams 中工作流的深层链接

  • 项目

可以创建深层链接以在 Teams 中执行特定任务，例如创建新聊天、打开日程安排对话框以及导航到音频视频通话。

本文介绍如何创建深层链接：

应用程序可以使用用户列表开始新的聊天，并使用以下格式提供其他信息，例如聊天名称和草稿消息：

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

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

查询参数为：

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

若要将此深层链接与机器人配合使用，请在卡按钮中指定深层链接作为 URL 目标，或通过操作openUrl类型点击操作。 应用还可以使用 Teams JavaScript 客户端库 (TeamsJS) v.2.0 或更高版本来创建此库，而无需手动准备深层链接。 以下示例使用 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 应用中创建深层链接，以打开会议安排对话框并使用以下方法提供信息，例如会议标题和参与者：

虽然我们建议使用 TeamsJS 的类型化 API，但可以手动创建指向 Teams 内置计划对话框的深层链接。

使用以下格式配置可在机器人、连接器或消息扩展卡中使用的深层链接：

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

注意

搜索参数不支持用 + 信号代替空格 (``)。 确保 URI 编码代码 %20 返回空格。 例如， ?subject=test%20subject 是好的，但 ?subject=test+subject 是坏的。

查询参数为：

  • attendees：表示与会者的用户 ID 的可选逗号分隔列表。 执行操作的用户是会议组织者。 用户 ID 字段仅支持 Microsoft Entra UserPrincipalName，通常是电子邮件地址。
  • startTime：事件的开始时间的可选参数。 开始时间应采用 长 ISO 8601 格式，例如 2018-03-12T23：55：25+02：00。
  • endTime：事件的结束时间的可选参数，也采用 ISO 8601 格式。
  • subject：会议主题的可选参数。
  • content：会议详细信息字段的可选参数。

注意

无法指定位置，因为它不受支持。 生成开始时间和结束时间时，必须指定 UTC 偏移量（包括时区）。

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

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

还可以在 Teams 应用中使用 TeamsJS v.2.0 或更高版本打开会议安排对话框，而无需手动准备链接。 若要在 Teams 中打开计划对话框，必须继续使用基于原始深层链接 URL 的方法，因为 Teams 尚不支持日历功能：

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

有关使用日历的详细信息，请参阅 API 参考文档中的“日历”命名空间。

可以将 Teams 应用配置为准备深层链接，以便用户启动一对一通话、群组呼叫或视频呼叫。 可以通过指定呼叫类型和参与者，对单个用户或一组用户调用仅音频或音频视频呼叫。 在 Teams 发出呼叫之前，客户端会提示进行确认。 如果有组呼叫，则可以在同一深层链接调用中呼叫一组 VoIP 和 PSTN 用户。

在视频通话中，Teams 客户端在打开呼叫方视频进行呼叫之前要求确认。 呼叫接收方可以选择通过 Teams 呼叫通知窗口通过仅音频或音频和视频进行响应。

注意

此方法不能用于调用会议。

可以通过以下两种方式之一配置深层链接：

虽然我们建议使用 TeamsJS v.2.0 或更高版本的类型化 API，但也可以使用手动配置的深层链接启动调用。 请参阅以下格式：

深度链接 格式 示例
进行音频通话 https://teams.microsoft.com/l/call/0/0?users=<user1>,<user2> https://teams.microsoft.com/l/call/0/0?users=joe@contoso.com
进行音频和视频通话 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
使用可选参数源进行音频和视频通话 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
对 VoIP 和 PSTN 用户进行音频和视频通话 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

下面是查询参数：

  • users：表示呼叫参与者的用户 ID 的逗号分隔列表。 用户 ID 字段支持Microsoft EntraUserPrincipalName（通常是电子邮件地址），或者在 PSTN 呼叫中，它支持 PSTN MRI 4：<phonenumber>。
  • withVideo：一个可选参数，可用于进行视频呼叫。 设置此参数只会打开调用方相机。 呼叫的接收方可以选择通过音频应答，或者通过 Teams 呼叫通知窗口应答音频和视频呼叫。

应用程序还可以使用 TeamsJS v.2.0 或更高版本启动调用，而无需手动准备这些深层链接。 以下代码演示如何使用 TeamsJS 启动调用：

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

用于在会议中将内容共享到阶段的深层链接

若要添加深层链接以在舞台上共享内容，需要具有应用上下文。 应用上下文允许 Teams 客户端提取应用清单，并检查是否可以在舞台上共享。 下面是应用上下文的示例：

{ "appSharingUrl" : "https://teams.microsoft.com/extensibility-apps/meetingapis/view", "appId": "9ec80a73-1d41-4bcb-8190-4b9eA9e29fbb" , "useMeetNow": false }

应用上下文的查询参数包括：

  • appID：这是可从应用清单获取的 ID。
  • appSharingUrl：需要在舞台上共享的 URL 应该是应用清单中定义的有效域。 如果 URL 不是有效的域，将显示一个错误对话框，向用户提供错误说明。
  • useMeetNow：这包括一个布尔参数，可为 true 或 false。

    • True：当 useMeetNow 值为 true 并且没有正在进行的会议时，将启动新的“立即开会”会议。 当有正在进行的会议时，此值将被忽略。

    • False：的默认值 useMeetNow 为 false，这意味着当深层链接共享到阶段且没有正在进行的会议时，将显示日历弹出窗口。 但是，可以在会议期间直接共享。

确保所有查询参数都正确编码了 URI，并且必须在最终 URL 中对应用上下文进行两次编码。 下面是一个示例：

const appContext= JSON.stringify({ 
  "appSharingUrl" : "https://teams.microsoft.com/extensibility-apps/meetingapis/view",
  "appId": "9cc80a93-1d41-4bcb-8170-4b9ec9e29fbb",
  "useMeetNow": false
});
const encodedContext = encodeURIComponent(appContext).replace(/'/g,"%27").replace(/"/g,"%22");
const encodedAppContext = encodeURIComponent(encodedContext).replace(/'/g,"%27").replace(/"/g,"%22");

可以从 Teams Web 或 Teams 桌面或移动客户端启动深层链接。

使用以下格式从 Teams Web 启动深层链接，以在舞台上共享内容：

msteams:/l/meeting-share?deeplinkId={GUID}&fqdn={string}&lm=deeplink&appContext={json encoded app context}

例如：https://teams.microsoft.com/l/meeting-share?deeplinkId={sampleid}&fqdn=teams.microsoft.com&lm=deeplink%22&appContext=%257B%2522appSharingUrl%2522%253A%2522https%253A%252F%252Fteams.microsoft.com%252Fextensibility-apps%252Fmeetingapis%252Fview%2522%252C%2522appId%2522%253A%25229cc80a93-1d41-4bcb-8170-4b9ec9e29fbb%2522%252C%2522useMeetNow%2522%253Atrue%257D

深度链接 格式 示例
若要共享应用并打开 Teams 日历，如果 useMeeetNow 为 false，则默认为 。 https://teams.microsoft.com/l/meeting-share?deeplinkId={deeplinkid}&fqdn={fqdn}}&lm=deeplink%22&appContext={encoded app context} https://teams.microsoft.com/l/meeting-share?deeplinkId={sampleid}&fqdn=teams.microsoft.com&lm=deeplink%22&appContext=%257B%2522appSharingUrl%2522%253A%2522https%253A%252F%252Fteams.microsoft.com%252Fextensibility-apps%252Fmeetingapis%252Fview%2522%252C%2522appId%2522%253A%25229cc80a93-1d41-4bcb-8170-4b9ec9e29fbb%2522%252C%2522useMeetNow%2522%253Afalse%257D
共享应用并启动即时会议，如果 useMeeetNow为 true。 https://teams.microsoft.com/l/meeting-share?deeplinkId={deeplinkid}&fqdn={fqdn}}&lm=deeplink%22&appContext={encoded app context} https://teams.microsoft.com/l/meeting-share?deeplinkId={sampleid}&fqdn=teams.microsoft.com&lm=deeplink%22&appContext=%257B%2522appSharingUrl%2522%253A%2522https%253A%252F%252Fteams.microsoft.com%252Fextensibility-apps%252Fmeetingapis%252Fview%2522%252C%2522appId%2522%253A%25229cc80a93-1d41-4bcb-8170-4b9ec9e29fbb%2522%252C%2522useMeetNow%2522%253Atrue%257D

查询参数为：

  • deepLinkId：用于遥测关联的任何标识符。
  • fqdn： fqdn 是一个可选参数，可用于切换到会议的适当环境，以在舞台上共享应用。 它支持特定应用共享在特定环境中发生的情况。 的 fqdn 默认值为企业 URL，可能的值 Teams.live.com 适用于 Teams for Life、 teams.microsoft.com或 teams.microsoft.us。

注意

若要使应用通过验证，当你从网站、Web 应用或自适应卡片创建深层链接时，请使用 “在会议中共享” 作为字符串或副本。

可以生成深层链接，将 应用共享到阶段 以及开始或加入会议。

可以在会议中生成 指向会议侧面板 的深层链接。 使用以下格式进行到会议端面板的深层链接：

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

示例：

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

默认情况下，深层链接在会议侧面板中打开。 若要直接在应用而不是会议端面板中打开深层链接，请添加 openInMeeting=false 深层链接格式：

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

有关详细信息，请参阅 指向选项卡的深层链接。

在以下情况下，深层链接不会在会议侧面板中打开：

  • 没有活动会议。
  • 应用未 sidePanel 在应用清单中声明上下文。
  • openInMeeting 在深层链接中设置为 false 。
  • 深层链接在会议窗口或组件之外选择。
  • 深层链接与当前会议不匹配，例如在另一个会议中创建的深层链接。

Teams 应用可以通过 Graph API 读取用于加入会议 URL 的 URL。 此深层链接会显示用户加入会议的 UI。 有关详细信息，请参阅 获取 onlineMeeting 和 获取会议详细信息。

代码示例

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