会议应用 API

  • 项目

会议扩展性提供 API 来增强会议体验。 可以在列出的 API 的帮助下执行以下操作：

  • 在会议生命周期内生成应用或集成现有应用。
  • 使用 API 使应用了解会议。
  • 选择所需的 API 来改进会议体验。

注意

使用 Microsoft Teams JavaScript 客户端库 (TeamsJS) (版本：1.10 及更高版本) 单一登录 (SSO) 在会议侧面板中工作。

下表提供了 Microsoft Teams JavaScript 库和Microsoft Bot Framework SDK 中可用的 API 列表：

方法 说明 源
获取用户上下文 获取上下文信息以在 Microsoft Teams 选项卡中显示相关内容。 TeamsJS 库
获取参与者 通过会议 ID 和参与者 ID 提取参与者信息。 Microsoft Bot Framework SDK
发送会议内通知 使用用户机器人聊天的现有对话通知 API 提供会议信号，并允许机器人通知显示会议内通知的用户操作。 Microsoft Bot Framework SDK
获取会议详细信息 获取会议的静态元数据。 Microsoft Bot Framework SDK
发送实时字幕 将实时字幕发送到正在进行的会议。 TeamsJS 库
将应用内容共享到演示区域 从会议中的应用侧面板将应用的特定部分共享到会议演示区域。 TeamsJS 库
接收实时 Teams 会议事件 接收实时会议事件，例如会议开始和结束或参与者加入和离开。 Microsoft Bot Framework SDK
获取传入音频状态 允许应用获取会议用户的传入音频状态设置。 TeamsJS 库
切换传入音频 允许应用将会议用户的传入音频状态设置从静音切换为取消静音，反之亦然。 TeamsJS 库

获取用户上下文 API

重要

  • 默认情况下， 新的 Teams 客户端 支持 Teams 会议中的应用的浅色主题。 app.theme当 getContext API 中的 属性返回值时default，Teams 客户端处于浅色主题中。
  • 早期版本的 Teams 客户端仅支持 Teams 会议中应用的深色和对比度主题

若要标识和检索选项卡内容的上下文信息，请参阅获取 Teams 选项卡上下文。meetingId 由在会议上下文中运行的选项卡使用，并添加到响应有效负载中。

示例

下面是基于会议类型、用户类型和呼叫类型获取用户上下文 API 的 TeamsJS v2 响应：

  • 会议类型

    下面是针对租户内用户的频道会议的 JSON 有效负载响应：

    {
    "app": {
    "locale": "en-us",
    "sessionId": "ff47ec00-e6a7-4dc1-a6ae-f44110f50c94",
    "theme": "default",
    "iconPositionVertical": 0,
    "osLocaleInfo": {
      "platform": "windows",
      "regionalFormat": "en-in",
      "shortDate": "dd-MM-yyyy",
      "longDate": "dd MMMM yyyy",
      "shortTime": "HH:mm",
      "longTime": "HH:mm:ss"
    },
    "parentMessageId": "1678109354022",
    "userClickTime": 1678109521159,
    "userFileOpenPreference": "inline",
    "host": {
      "name": "Teams",
      "clientType": "desktop",
      "sessionId": "c3c3c0a0-f7a1-b070-6b89-c8cd1f380042",
      "ringId": "ring1"
    },
    "appLaunchId": "7346ae66-5cac-47f9-8a0d-1228dac474cb"
    },
    "page": {
    "id": "Test",
    "frameContext": "sidePanel",
    "subPageId": "",
        "isFullScreen": false,
        "isMultiWindow": true,
        "sourceOrigin": ""
       },
       "user": {
        "id": "57efa5f3-273c-47e2-a871-4879e5d849cf",
        "displayName": "",
        "isCallingAllowed": undefined,
        "isPSTNCallingAllowed": undefined,
        "licenseType": "Unknown",
        "loginHint": "v-prkamble@microsoft.com",
        "userPrincipalName": "v-prkamble@microsoft.com",
        "tenant": {
         "id": "72f988bf-86f1-41af-91ab-2d7cd011db47",
         "teamsSku": "enterprise"
        }
       },
       "channel": {
        "id": "19:49683807ffce4318ad6d6d7a24dbde45@thread.tacv2",
        "displayName": undefined,
        "relativeUrl": undefined,
        "membershipType": undefined,
        "defaultOneNoteSectionId": undefined,
        "ownerGroupId": undefined,
        "ownerTenantId": undefined
       },
       "chat": {
        "id": "19:49683807ffce4318ad6d6d7a24dbde45@thread.tacv2"
       },
       "meeting": {
        "id": "MCMxOTo0OTY4MzgwN2ZmY2U0MzE4YWQ2ZDZkN2EyNGRiZGU0NUB0aHJlYWQudGFjdjIjMTY3ODEwOTM1NDAyMg=="
       },
       "sharepoint": undefined,
       "team": {
        "internalId": "19:b34aeec3f8e54240a5c283e86bfc4878@thread.tacv2",
        "displayName": undefined,
        "type": undefined,
        "groupId": undefined,
        "templateId": undefined,
        "isArchived": undefined,
        "userRole": 1
       },
       "sharePointSite": {
        "teamSiteUrl": "",
        "teamSiteDomain": "microsoft.sharepoint.com",
        "teamSitePath": "",
        "teamSiteId": "",
        "mySitePath": undefined,
        "mySiteDomain": undefined
       }
      }

  • 用户类型

    以下是针对来宾用户的预定私人会议中的 JSON 有效负载响应：

      {
        "app": {
         "locale": "en-us",
         "sessionId": "268beeb4-a52d-4ba8-b1c8-8b9f0b9b3492",
         "theme": "default",
         "iconPositionVertical": 23,
         "osLocaleInfo": {
          "platform": "windows",
          "regionalFormat": "en-in",
          "longDate": "dd MMMM yyyy",
          "shortDate": "dd-MM-yyyy",
          "longTime": "HH:mm:ss",
          "shortTime": "HH:mm"
         },
         "parentMessageId": "",
         "userClickTime": 1678023265131,
         "userFileOpenPreference": "inline",
         "host": {
          "name": "Teams",
          "clientType": "desktop",
          "sessionId": "967c980b-1e41-a2cd-eac0-a4bff8f73ce7",
          "ringId": "ring1"
         },
         "appLaunchId": "c35c4496-f28c-4107-8e6c-2dba09fb881a"
        },
        "page": {
         "id": "Test",
         "frameContext": "content",
         "subPageId": "",
         "isFullScreen": false,
         "isMultiWindow": false,
         "sourceOrigin": NULL
        },
        "user": {
         "id": "57efa5f3-273c-47e2-a871-4879e5d849cf",
         "displayName": undefined,
         "isCallingAllowed": undefined,
         "isPSTNCallingAllowed": undefined,
         "licenseType": "Unknown",
         "loginHint": "v-prkamble@microsoft.com",
         "userPrincipalName": "v-prkamble@microsoft.com",
         "tenant": {
          "id": "72f988bf-86f1-41af-91ab-2d7cd011db47",
          "teamsSku": "enterprise"
         }
        },
        "channel": undefined,
        "chat": {
         "id": "19:meeting_YmU5NWM3NGEtZjMyMi00ZDg4LTk4OGUtMjUzMGJkZjRhMDhm@thread.v2"
        },
        "meeting": {
         "id": "MCMxOTptZWV0aW5nX1ltVTVOV00zTkdFdFpqTXlNaTAwWkRnNExUazRPR1V0TWpVek1HSmtaalJoTURobUB0aHJlYWQudjIjMA=="
        },
        "sharepoint": undefined,
        "team": undefined,
        "sharePointSite": {
         "teamSiteUrl": "",
         "teamSiteDomain": "microsoft.sharepoint.com",
         "teamSitePath": "",
         "teamSiteId": undefined,
         "mySitePath": "/personal/v-prkamble_microsoft_com",
         "mySiteDomain": "microsoft-my.sharepoint.com"
        }
  }

  • 呼叫类型

    下面是针对租户内用户的一对一调用的 JSON 有效负载响应：

          {
       "app": {
        "locale": "en-us",
        "sessionId": "1b3dc47e-f6ae-4fe2-8ed6-844a505f3186",
        "theme": "dark",
        "iconPositionVertical": null,
        "osLocaleInfo": {
         "platform": "windows",
         "regionalFormat": "en-in",
         "shortDate": "dd-MM-yyyy",
         "longDate": "dd MMMM yyyy",
         "shortTime": "HH:mm",
         "longTime": "HH:mm:ss"
        },
        "parentMessageId": "",
        "userClickTime": 1678088052473,
        "userFileOpenPreference": undefined,
        "host": {
         "name": "Teams",
         "clientType": "desktop",
         "sessionId": "",
         "ringId": "general"
        },
        "appLaunchId": undefined
       },
       "page": {
        "id": "Test",
        "frameContext": "sidePanel",
        "subPageId": "",
        "isFullScreen": undefined,
        "isMultiWindow": true,
        "sourceOrigin": ""
       },
       "user": {
        "id": "e652dd92-dd63-4fcc-b5b2-2005681e8e9f",
        "displayName": undefined,
        "isCallingAllowed": undefined,
        "isPSTNCallingAllowed": undefined,
        "licenseType": "Unknown",
        "loginHint": "admin@M365x94626565.onmicrosoft.com",
        "userPrincipalName": "admin@M365x94626565.onmicrosoft.com",
        "tenant": {
         "id": "aa923623-ae61-49ee-b401-81f414b6ad5a",
         "teamsSku": "unknown"
        }
       },
       "channel": undefined,
       "chat": {
        "id": "19:a74d8489-4455-4670-9581-7b38a8017c58_e652dd92-dd63-4fcc-b5b2-2005681e8e9f@unq.gbl.spaces"
       },
       "meeting": {
        "id": "MCMxOTphNzRkODQ4OS00NDU1LTQ2NzAtOTU4MS03YjM4YTgwMTdjNThfZTY1MmRkOTItZGQ2My00ZmNjLWI1YjItMjAwNTY4MWU4ZTlmQHVucS5nYmwuc3BhY2VzIzA="
       },
       "sharepoint": undefined,
       "team": undefined,
       "sharePointSite": {
        "teamSiteUrl": undefined,
        "teamSiteDomain": "m365x94626565.sharepoint.com",
        "teamSitePath": undefined,
        "teamSiteId": undefined,
        "mySitePath": undefined,
        "mySiteDomain": undefined
       }
      }

获取参与者 API

GetParticipant API 必须有机器人注册和 ID 才能生成身份验证令牌。 有关详细信息，请参阅机器人注册和 ID。

注意

  • 用户类型不包括在 getParticipantRole API 中。
  • 请勿缓存参与者角色，因为会议组织者可以随时更改角色。
  • 目前，只有少于 350 名参与者的通讯组列表或名单才支持 GetParticipant API。

查询参数

提示

从 选项卡 SSO 身份验证中获取参与者 ID 和租户 ID。

Meeting API 必须将meetingId、participantId 和 tenantId 作为 URL 参数。 参数作为 Microsoft Teams JavaScript 客户端库的一部分提供， (TeamsJS) 库和机器人活动。

下表列出了查询参数：

值 类型 必需 说明
meetingId 字符串 是 会议标识符可通过机器人调用和 TeamsJS 库获得。
participantId 字符串 是 参与者 ID 就是用户 ID。 它在 Tab SSO、机器人调用和 TeamsJS 库中可用。 建议从 Tab SSO 获取参与者 ID。
tenantId 字符串 是 租户用户需要租户 ID。 它在 Tab SSO、机器人调用和 TeamsJS 库中可用。 建议从 Tab SSO 获取租户 ID。

示例

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
  // Gets the details for the given meeting participant. 
  // This only works in Teams meeting scoped conversations.
  TeamsMeetingParticipant participant = await TeamsInfo.GetMeetingParticipantAsync(turnContext, "yourMeetingId", "yourParticipantId", "yourParticipantTenantId").ConfigureAwait(false);
  TeamsChannelAccount member = participant.User;
  MeetingParticipantInfo meetingInfo = participant.Meeting;
  ConversationAccount conversation = participant.Conversation;

  // Sends a message activity to the sender of the incoming activity. 
  await turnContext.SendActivityAsync(MessageFactory.Text($"The participant role is: {meetingInfo.Role}"), cancellationToken);
}
属性名称 说明
user.id 用户的 ID。
user.aadObjectId Microsoft Entra用户的对象 ID。
user.name 用户名。
user.givenName 用户的名字。
user.surname 用户的姓氏。
user.email 用户的邮件 ID。
user.userPrincipalName 用户的 UPN。
user.tenantId Microsoft Entra租户 ID。
user.userRole 用户的角色。 例如，“admin”或“user”。
meeting.role 参与者在会议中的角色。 例如，“组织者”或“演示者”或“与会者”。
meeting.inMeeting 指示参与者是否在会议中的值。
conversation.id 会议聊天 ID。
conversation.isGroup 指示对话是否包含两个以上参与者的布尔值。

响应代码

下表列出了响应代码：

响应代码 说明
403 获取参与者信息未与应用共享。 如果未在会议中安装应用，则会触发错误响应 403。 如果租户管理员在实时站点迁移期间禁用或阻止应用，则会触发错误响应 403。
200 成功检索参与者信息。
401 应用使用无效的令牌进行响应。
404 会议已过期或参与者不可用。

发送会议内通知

会议中的所有用户都会收到通过会议内通知有效负载发送的通知。 会议内通知有效负载会触发会议内通知，并能够帮助提供使用用户机器人聊天的现有聊天通知 API 传递的会议信号。 可以根据用户操作发送会议内通知。 可通过机器人服务获取有效负载。

还可以向会议中的特定参与者发送有针对性的会议内通知。 有关详细信息，请参阅 定向会议内通知。

注意

  • 调用会议内通知时，内容将显示为聊天消息。
  • 在用户在 Web 视图中执行操作后，必须调用 submitTask() 函数才能自动关闭。 这是应用提交的要求。 有关详细信息，请参阅 Teams SDK 任务模块。
  • 如果希望应用支持匿名用户，初始调用请求有效负载必须依赖于 from 对象中的 from.id 请求元数据，而不是 from.aadObjectId 请求元数据。 from.id是用户 ID，from.aadObjectId是用户的Microsoft Entra ID。 有关详细信息，请参阅在选项卡中使用任务模块和创建和发送任务模块。

查询参数

下表包含查询参数：

值 类型 必需 说明
conversationId 字符串 是 聊天标识符作为 Bot Invoke 的一部分提供。

示例

Bot ID 在清单中声明，机器人接收结果对象。

注意

  • 在请求的有效负载示例中，externalResourceUrl 的 completionBotId 参数是可选的。
  • externalResourceUrl 宽度和高度参数必须以像素为单位。 有关详细信息，请参阅设计指南。
  • URL 是页面，在会议内通知中加载为 <iframe>。 域必须位于应用清单中的应用 validDomains 数组中。
// Specifies the type of text data in a message attachment.
Activity activity = MessageFactory.Text("This is a meeting signal test");

// Configures the current activity to generate a notification within Teams.
activity.TeamsNotifyUser(true, "https://teams.microsoft.com/l/bubble/APP_ID?url=<url>&height=<height>&width=<width>&title=<title>&completionBotId=BOT_APP_ID");

// Sends a message activity to the sender of the incoming activity. 
await turnContext.SendActivityAsync(activity).ConfigureAwait(false);
属性名称 说明
类型 活动的类型。
text 消息的文本内容。
summary 邮件的摘要文本。
channelData.notification.alertInMeeting 指示在会议中是否向用户显示通知的布尔值。
channelData.notification.externalResourceUrl 通知的外部资源 URL 的值。
replyToId 线程的父消息或根消息的 ID。
APP_ID 在清单中声明的应用 ID。
completionBotId 机器人应用 ID。

响应代码

下表列出了响应代码：

响应代码 说明
201 已成功发送活动信号。
401 应用使用无效的令牌进行响应。
403 应用无法发送信号。 403 响应代码可能出现有很多原因，例如租户管理员在实时站点迁移期间禁用和阻止应用。 在这种情况下，有效负载包含详细的错误消息。
404 会议聊天不存在。

定向会议通知和应用图标标记 API

该 targetedMeetingNotification API 允许应用发送有针对性的会议内通知，并向会议中的特定参与者显示应用图标。 应用根据用户操作发送有针对性的会议内通知和应用图标标记。 该 API 可通过机器人 API 获取。

先决条件

必须在 属性下webApplicationInfo使用 RSC 权限配置应用清单，才能向会议中的特定参与者发送有针对性的会议内通知并显示应用图标。 使用以下示例配置清单：


对于应用清单版本 1.12 及更高版本 
"webApplicationInfo": {
    "id": "<<MICROSOFT-APP-ID>>",
    "resource": "https://RscBasedStoreApp"  },
  "authorization": {
    "permissions": {
      "resourceSpecific": [
            {
                "name": "OnlineMeetingNotification.Send.Chat",
                "type": "Application"
            }
        ]    
    }
}


对于应用清单 1.11 及更早版本 
"webApplicationInfo": {
    "id": "<<MICROSOFT-APP-ID>>",
    "resource": "https://RscBasedStoreApp",
    "applicationPermissions": [
      "OnlineMeetingNotification.Send.Chat"
    ]
}

注意

  • API 有效负载仅允许具有 URL 的对话。
  • 不支持用户 ID 格式 aadObjectid 和 UPN 。

获取目标会议内通知和应用图标的受支持用户 ID 格式：

示例

下面是针对会议内通知和应用图标标记的请求有效负载的示例：

POST /v1/meetings/{meetingId}/notification

{

  "type": "targetedMeetingNotification",
  "value": {
    "recipients": [ 
"29:1I12M_iy2wTa97T6LbjTh4rJCWrtw2PZ3lxpD3yFv8j2YPnweY2lpCPPAn3RI0PP7rghfHauUz48I1t7ANhj4CA"
     ], 
    "surfaces": [ 
      { 
        "surface": "meetingStage", 
        "contentType": "task", 
        "content": { 
          "value": { 
            "height": "300", 
            "width": "400", 
            "title": "Targeted meeting Notification", 
            "url": "https://somevalidurl.com"           
}
        } 
      } 
    ] 
  },
  "channelData": { // optional if a developer doesn't want to support user attributes.
    "onBehalfOf": [ 
      { 
        "itemid": 0, 
        "mentionType": "person", 
        "mri": "29:1mDOCfGM9825lMHlwP8NjIVMJeQAbN-ojYBT5VzQfPpnst1IFQeYB1QXC8Zupn2RhgfLIW27HmynQk-4bdx_YhA", 
        "displayName": "yunny chung"      } 
    ] 
  }
}
属性名称 说明
meetingId 会议 ID 可通过机器人调用和 TeamsJS 库获得。
type targetedMeetingNotification
recipients 用户 ID 列表。 通过获取参与者 API 获取会议参与者的用户 ID。 使用获取 成员 API 获取聊天名单的完整列表。 空或 null 收件人列表将返回 400。
surface 一种图面类型。 支持的图面类型为 meetingStage 和 meetingTabIcon。
surfaces 可在其中呈现通知的图面列表。
contentType 目标会议中通知呈现的内容类型。 支持的值为 task。
content TaskModuleContinueResponse
content.value.height 可选;请求的通知高度。
content.value.width 可选;请求的通知宽度。
content.value.title 可选;通知的标题。
content.value.url 可选;通知中要呈现的 URL。 确保 URL 是应用清单中的一 validDomains 部分。 如果字符串为空或未提供 URL，则会议通知上不会呈现任何内容。
ChannelData.OnBehalfOf 可选;这是为了支持 用户属性。
onBehalfOf.itemid 介绍项目的标识。 其值必须为 0。
onBehalfOf.mentionType person关键字 (keyword) 。 描述一个人的提及。
onBehalfOf.mri 显示为发件人的用户 MRI。
onBehalfOf.displayName 可选; person的名称。 在名称解析不可用时用作回退。

注意

如果提供的输入无效，API 将返回状态代码 400。

响应代码

下表列出了响应代码：

响应代码 说明
202 已成功发送通知。
207 通知仅发送给少数参与者。
400 会议通知请求有效负载验证失败。
401 机器人令牌无效。
403 不允许机器人发送通知。
404 找不到会议聊天，或者在名单中找不到任何参与者。

获取会议详细信息 API

会议详细信息 API 使应用能够获取会议的静态元数据。 元数据提供不会动态变化的数据点。 API 可通过机器人服务使用。 目前，私人计划会议或定期会议以及安排的频道会议或定期会议分别支持具有不同 RSC 权限的 API。

会议详细信息 API 必须具有机器人注册和机器人 ID。 它要求 Bot SDK 获取 TurnContext。 若要使用会议详细信息 API，必须基于任何会议的范围（如私人会议或频道会议）获取不同的 RSC 权限。

注意

Teams 桌面和移动客户端中的已安排私人会议、计划频道会议、即时会议 (Meet 现在) 、一对一呼叫和群组呼叫支持会议详细信息 API。

先决条件

若要使用会议详细信息 API，必须基于任何会议的范围（如私人会议或频道会议）获取不同的 RSC 权限。


对于应用清单版本 1.12 及更高版本

使用以下示例为任何私人会议配置应用清单的 webApplicationInfo 和 authorization 属性：

"webApplicationInfo": {
    "id": "<bot id>",
    "resource": "https://RscPermission",
},
"authorization": {
    "permissions": {
        "resourceSpecific": [
            {
                "name": "OnlineMeeting.ReadBasic.Chat",
                "type": "Application"
            }
        ]
    }
}

使用以下示例为任何频道会议配置应用清单的 webApplicationInfo 和 authorization 属性：

"webApplicationInfo": {
    "id": "<bot id>",
    "resource": "https://RscPermission",
},
"authorization": {
    "permissions": {
        "resourceSpecific": [
            {
                "name": "ChannelMeeting.ReadBasic.Group",
                "type": "Application"
            }
        ]
    }
}


对于应用清单 1.11 及更早版本

使用以下示例为任何私人会议配置应用清单的 webApplicationInfo 属性：

"webApplicationInfo": {
    "id": "<bot id>",
    "resource": "https://RscPermission",
    "applicationPermissions": [
      "OnlineMeeting.ReadBasic.Chat"
    ]
}

使用以下示例为任何频道会议配置应用清单的 webApplicationInfo 属性：

"webApplicationInfo": {
    "id": "<bot id>",
    "resource": "https://RscPermission",
    "applicationPermissions": [
      "ChannelMeeting.ReadBasic.Group"
    ]
}

注意

  • ChannelMeeting.ReadBasic.Group如果将权限添加到清单，机器人会自动从添加机器人的所有团队中创建的频道会议接收会议开始或结束事件。
  • 对于一对一呼叫 organizer ，聊天的发起方为发起方，组呼叫 organizer 为呼叫发起方。 对于公共频道会议 organizer ，是创建频道帖子的人员。

查询参数

下表列出了查询参数：

值 类型 必需 说明
meetingId 字符串 是 会议标识符可通过机器人调用和 TeamsJS 库获得。

示例

// Gets the information for the given meeting id.
MeetingInfo result = await TeamsInfo.GetMeetingInfoAsync(turnContext);

// Sends a message activity to the sender of the incoming activity. 
await turnContext.SendActivityAsync(JsonConvert.SerializeObject(result));
属性名称 说明
details.id 会议 ID，编码为 BASE64 字符串。
details.msGraphResourceId MsGraphResourceId，专用于 MS 图形 API 调用。
details.scheduledStartTime 会议的安排开始时间（UTC）。
details.scheduledEndTime 会议计划的结束时间（UTC）。
details.joinUrl 用于加入会议的 URL。
details.title 会议的标题。
details.type 会议类型 (OneToOneCall、GroupCall、Scheduled、定期、MeetNow、ChannelScheduled 和 ChannelRecurring) 。
conversation.isGroup 指示对话是否包含两个以上参与者的布尔值。
conversation.conversationType 对话类型。
conversation.id 会议聊天 ID。
organizer.id 组织者的用户 ID。
organizer.aadObjectId 组织者的Microsoft Entra对象 ID。
organizer.tenantId 组织者的Microsoft Entra租户 ID。

如果是定期会议类型：

startDate：指定开始应用模式的日期。 startDate 的值必须对应于事件资源上 start 属性的日期值。 如果不符合模式，则第一次会议可能不会在此日期发生。

endDate：指定停止应用模式的日期。 如果会议不符合模式，则最后一次会议可能不会在此日期发生。

发送实时字幕 API

发送实时字幕 API 公开了一个 POST 终结点，用于 Teams 通信访问实时翻译 (CART) 字幕、人工类型隐藏字幕。 当最终用户启用了字幕时，发送到此终结点的文本内容会显示在 Teams 会议中。

CART URL

可以从 Teams 会议中的“会议选项 ”页获取 POST 终结点的 CART URL。 有关详细信息，请参阅 Microsoft Teams 会议中的 CART 字幕。 无需修改 CART URL 即可使用 CART 字幕。

查询参数

CART URL 包括以下查询参数：

值 类型 必需 说明
meetingId 字符串 是 会议标识符可通过机器人调用和 TeamsJS 库获得。
例如：meetingid=%7b%22tId%22%3a%2272f234bf-86f1-41af-91ab-2d7cd0321b47%22%2c%22oId%22%3a%22e071f268-4241-47f8-8cf3-fc6b84437f23%22%2c%22thId%22%3a%2219%3ameeting_NzJiMjNkMGQtYzk3NS00ZDI1LWJjN2QtMDgyODVhZmI3NzJj%40thread.v2%22%2c%22mId%22%3a%220%22%7d
令牌 字符串 是 授权令牌。
例如：token=04751eac

示例

https://api.captions.office.microsoft.com/cartcaption?meetingid=%7b%22tId%22%3a%2272f234bf-86f1-41af-91ab-2d7cd0321b47%22%2c%22oId%22%3a%22e071f268-4241-47f8-8cf3-fc6b84437f23%22%2c%22thId%22%3a%2219%3ameeting_NzJiMjNkMGQtYzk3NS00ZDI1LWJjN2QtMDgyODVhZmI3NzJj%40thread.v2%22%2c%22mId%22%3a%220%22%7d&token=gjs44ra

方法

Resource 方法 说明
/cartcaption POST 处理会议的字幕（已启动）

注意

确保所有请求的内容类型都是采用 UTF-8 编码的纯文本。 请求正文仅包含字幕。

示例

POST /cartcaption?meetingid=04751eac-30e6-47d9-9c3f-0b4ebe8e30d9&token=04751eac&lang=en-us HTTP/1.1
Host: api.captions.office.microsoft.com
Content-Type: text/plain
Content-Length: 22
Hello I’m Cortana, welcome to my meeting.

注意

每个 POST 请求都会生成新的字幕行。 若要确保最终用户有足够的时间读取内容，请将每个 POST 请求正文限制为 80-120 个字符。

错误代码

下表列出了错误代码：

错误代码 说明
400 错误请求。 响应正文包含过多信息。 例如，无法显示所有必需的参数。
401 未经授权。 令牌错误或过期。 如果收到此错误，请在 Teams 中生成新的 CART URL。
404 找不到会议或未开始会议。 如果收到此错误，请确保启动会议并选择开始字幕。 在会议中启用字幕后，可以开始让会议显示字幕。
500 内部服务器错误。 有关详细信息，请联系支持人员或提供反馈。

接收实时 Teams 会议事件

可以接收实时会议事件，例如会议开始和结束或参与者加入和离开事件。

接收会议开始和结束事件

注意

安排会议和频道会议支持会议开始和结束事件。

用户可以接收实时会议事件。 只要任何应用与会议关联，就会与机器人共享会议实际开始时间和结束时间。 会议实际开始和结束时间不同于计划的开始和结束时间。 会议详细信息 API 提供计划的开始和结束时间。 该事件提供实际开始和结束时间。

ChannelMeeting.ReadBasic.Group如果在清单中添加 了 和 OnlineMeeting.ReadBasic.Chat 权限，机器人会自动开始接收计划和频道会议类型的会议开始或结束事件。

先决条件

应用清单必须具有 webApplicationInfo 属性才能接收会议开始和结束事件。 使用以下示例配置清单：


对于应用清单版本 1.12 及更高版本 
"webApplicationInfo": {
    "id": "<bot id>",
    "resource": "https://RscPermission",
    },
"authorization": {
    "permissions": {
        "resourceSpecific": [
            {
                "name": "OnlineMeeting.ReadBasic.Chat",
                "type": "Application"
            }
            {
                "name": "ChannelMeeting.ReadBasic.Group",
                "type": "Application"
            }
        ]    
    }
}


对于应用清单 1.11 及更早版本 
"webApplicationInfo": {
    "id": "<bot id>",
    "resource": "https://RscPermission",
    "applicationPermissions": [
      "OnlineMeeting.ReadBasic.Chat",
      "ChannelMeeting.ReadBasic.Group"
    ]
}

获取会议开始或结束事件的示例

机器人通过 OnTeamsMeetingStartAsync 和 OnTeamsMeetingEndAsync 处理程序接收会议开始和会议结束事件。 与会议事件相关的信息是 对象的一MeetingStartEventDetails部分，该对象包括元数据字段，例如 、meetingType、title、id、 joinUrlstartTime和 EndTime。

注意

  • 从 turnContext.ChannelData 获取会议 ID。
  • 请勿使用会话 ID 作为会议 ID。
  • 请勿使用会议事件有效负载 turncontext.activity.value 中的会议 ID。

以下示例演示如何捕获会议开始和结束事件：

会议开始事件

// Invoked when a Teams Meeting Start event activity is received from the connector.
protected override async Task OnTeamsMeetingStartAsync(MeetingStartEventDetails meeting, ITurnContext<IEventActivity> turnContext, CancellationToken cancellationToken)
{
    // Sends a message activity to the sender of the incoming activity. 
    await turnContext.SendActivityAsync(JsonConvert.SerializeObject(meeting));
}

会议结束事件

// Invoked when a Teams Meeting End event activity is received from the connector.
protected override async Task OnTeamsMeetingEndAsync(MeetingEndEventDetails meeting, ITurnContext<IEventActivity> turnContext, CancellationToken cancellationToken)
{
    // Sends a message activity to the sender of the incoming activity.
    await turnContext.SendActivityAsync(JsonConvert.SerializeObject(meeting));
}

会议开始事件有效负载的示例

以下代码提供了会议开始事件有效负载的示例：

{
  "name": " application/vnd.microsoft.meetingStart",
  "type": "event",
  "timestamp": "2023-02-23T19:34:07.478Z",
  "localTimestamp": "2023-02-23T11:34:07.478-8",
  "channelId": "msteams",
  "serviceUrl": "https://smba.trafficmanager.net/teams/",
  "from": {
    "id": "user_id"
  },
  "conversation": {
    "isGroup": true,
    "conversationType": "groupchat",
    "id": "conversation_id"
  },
  "recipient": {
    "id": "28:65f50003-e15d-434a-9e14-0fcfeb3d7817"
  },
  "value": {
    "id": "meeting_id",
    "joinUrl": "join_url",
    "title": "Example meeting",
    "meetingType": "Scheduled",
    "startTime": "2023-02-23T19:34:07.478Z"
  },
  "channelData": {
    "tenant": {
      "id": "tenant_id"
    }
  }
}

会议结束事件有效负载的示例

以下代码提供了会议结束事件有效负载的示例：

{
  "name": " application/vnd.microsoft.meetingEnd",
  "type": "event",
  "timestamp": "2023-02-23T19:34:07.478Z",
  "localTimestamp": "2023-02-23T11:34:07.478-8",
  "channelId": "msteams",
  "serviceUrl": "https://smba.trafficmanager.net/teams/",
  "from": {
    "id": "user_id"
  },
  "conversation": {
    "isGroup": true,
    "conversationType": "groupchat",
    "id": "conversation_id"
  },
  "recipient": {
    "id": "28:65f50003-e15d-434a-9e14-0fcfeb3d7817"
  },
  "value": {
    "id": "meeting_id",
    "joinUrl": "join_url",
    "title": "Example meeting",
    "meetingType": "Scheduled",
    "EndTime": "2023-02-23T20:30:07.478Z"
  },
  "channelData": {
    "tenant": {
      "id": "tenant_id"
    }
  }
}
属性名称 说明
name 用户名。
type 活动类型。
timestamp 消息的本地日期和时间，以 ISO-8601 格式表示。
id 活动的 ID。
channelId 与此活动关联的通道。
serviceUrl 应发送对此活动的响应的服务 URL。
from.id 发送请求的用户 ID。
from.aadObjectId Microsoft Entra发送请求的用户的对象 ID。
conversation.isGroup 指示对话是否包含两个以上参与者的布尔值。
conversation.tenantId Microsoft Entra对话或会议的租户 ID。
conversation.id 会议聊天 ID。
recipient.id 接收请求的用户的 ID。
recipient.name 接收请求的用户的名称。
entities.locale 包含有关区域设置的元数据的实体。
entities.country 包含有关国家/地区的元数据的实体。
entities.type 包含有关客户端的元数据的实体。
channelData.tenant.id Microsoft Entra租户 ID。
channelData.source 从中触发或调用事件的源名称。
channelData.meeting.id 与会议关联的默认 ID。
价值。MeetingType 会议类型。
价值。标题 会议的主题。
价值。Id 与会议关联的默认 ID。
价值。JoinUrl 会议的加入 URL。
价值。StartTime 会议开始时间（UTC）。
价值。EndTime 会议结束时间（UTC）。
locale 客户端设置的消息的区域设置。

接收会议参与者事件

机器人可以接收实时会议事件，例如参与者加入和离开事件。 仅当在开发人员门户中订阅了这些事件时，机器人才能接收参与者事件。

注意

  • 仅计划会议支持参与者事件。
  • 若要让机器人接收参与者事件，请确保在参与者加入或离开会议之前将机器人添加到会议。

若要订阅参与者事件，请执行以下步骤：

  1. 在 开发人员门户中 ，打开机器人应用或导入现有应用。

  2. 在 “会议事件订阅 ”部分中，选择事件：

    • 参与者加入
    • 参与者休假

  3. 选择“保存”

    显示开发人员门户如何显示参与者事件的屏幕截图。

  4. 确保在 OnlineMeetingParticipant.Read.Chat 应用清单中配置 RSC 权限。

    如果你的应用没有 RSC 权限，请在开发人员门户中通过应用的 “配置>权限” 部分添加它。 有关详细信息，请参阅 RSC 权限。

以下示例演示如何捕获参与者加入和离开事件：

示例代码参考

//Invoked on participant join a meeting
protected override async Task OnTeamsMeetingParticipantsJoinAsync(MeetingParticipantsEventDetails meeting, ITurnContext<IEventActivity> turnContext, CancellationToken cancellationToken)
{
  await turnContext.SendActivityAsync("Member has joined the meeting.");
  return;
}

下面是参与者加入和离开事件有效负载的示例：

下面是参与者加入事件有效负载的示例：

{ 

    "type": "event", 
    "name": "application/vnd.microsoft.meetingParticipantJoin",
    "timestamp": "2023-02-23T19:34:07.478Z", 
    "channelId": "msteams", 
    "serviceUrl": "https://smba.trafficmanager.net/amer/", 
    "from": { 
        "id": "29:id_xyz" 
    }, 
    "conversation": { 
        "isGroup": true, 
        "conversationType": "groupchat", 
        "id": "19:meeting_threadId@thread.v2" 
    }, 
    "recipient": { 
        "id": "28:botid" 
    },  
    "value": { 
       "members": [ 
       { 
        "user": { 
            "tenantId": "tenantid", 
            "objectId": "user_object_Id", 
            "id": "29:userId ", 
            "name": "Test User", 
            "aadObjectId": " user_object_Id " 
        },   
        "meeting": { 
            "inMeeting": true, 
            "role": "Organizer" //Attendee, Organizer, Presenter 
        },  
        }], 
    }, 
    "channelData": { 
        "tenant": { 
            "id": "tenantId" 
        }, 
        "meeting": { 
            "id": "encoded_meetingId" 
        } 
    } 
}

获取传入音频状态

API getIncomingClientAudioState 允许应用获取会议用户的传入音频状态设置。 可以通过 TeamsJS 库获取 API。

注意

  • getIncomingClientAudioState公共开发人员预览版中提供了适用于移动设备的 API。
  • 新的 toggleIncomingClientAudio Teams 客户端中提供了 API。
  • 特定于资源的许可适用于清单版本 1.12 和更高版本，因此此 API 不适用于清单版本 1.11 和更早版本。

清单

"authorization": {
    "permissions": {
      "resourceSpecific": [
        {
          "name": "OnlineMeetingParticipant.ToggleIncomingAudio.Chat",
          "type": "Delegated"
        }
      ]
    }
  }

示例

callback = (errcode, result) => {
        if (errcode) {
            // Handle error code
        }
        else {
            // Handle success code
        }
    }
// The getIncomingClientAudioState API shows the current audio state.
microsoftTeams.meeting.getIncomingClientAudioState(this.callback)

查询参数

下表包含查询参数：

值 类型 必需 说明
callback 字符串 是 回调包含两个参数 error 和 result。 此错误可以包含错误类型SdkError，也可以在null音频提取成功时出现。 当音频提取成功时， 结果 可以包含 true 或 false 值，或者在音频提取失败时为 null。 如果结果为 true，则传入音频将静音;如果结果为 false，则取消静音。

响应代码

下表列出了响应代码：

响应代码 说明
500 内部错误。
501 当前上下文中不支持 API。
1000 应用没有允许共享到阶段的适当权限。

切换传入音频

该 toggleIncomingClientAudio API 允许应用将会议用户的传入音频状态设置从静音切换为取消静音，反之亦然。 可以通过 TeamsJS 库获取 API。

注意

  • toggleIncomingClientAudio公共开发人员预览版中提供了适用于移动设备的 API。
  • 特定于资源的许可适用于清单版本 1.12 和更高版本，因此此 API 不适用于清单版本 1.11 和更早版本。

清单

"authorization": {
 "permissions": {
  "resourceSpecific": [
   {
    "name": "OnlineMeetingParticipant.ToggleIncomingAudio.Chat",
    "type": "Delegated"
   }
  ]
 }
}

示例

callback = (error, result) => {
        if (error) {
            // Handle error code
        }
        else {
            // Handle success code
        }
    }
// The toggleIncomingClientAudio API allows an app to toggle the incoming audio state.
microsoftTeams.meeting.toggleIncomingClientAudio(this.callback)

查询参数

下表包含查询参数：

值 类型 必需 说明
callback 字符串 是 回调包含两个参数 error 和 result。 此错误可以包含错误类型SdkError，也可以在null切换成功时出现。 当切换成功时， 结果 可以包含 true 或 false 值，或者在切换失败时为 null。 如果结果为 true，则传入音频将静音;如果结果为 false，则取消静音。

响应代码

下表列出了响应代码：

响应代码 说明
500 内部错误。
501 当前上下文中不支持 API。
1000 应用没有允许共享到阶段的适当权限。

代码示例

示例名称 Description .NET Node.js 清单
会议扩展性 用于传递令牌的 Teams 会议扩展性示例。 View View View
会议内通知 演示如何使用机器人实现会议内通知。 View View View
会议侧面板 用于在会议中与侧面板交互的 Teams 会议扩展性示例。 View View
会议中的“详细信息”选项卡 此示例应用显示了 Teams 会议扩展性功能，用户可在其中创建投票，成员可以在会议中回答投票。 View View View
会议事件示例 此示例显示使用机器人的实时 Teams 会议事件。 View View View
会议招聘示例 此示例应用展示了使用会议中的应用的招聘方案的会议体验。 View View View

另请参阅