发送主动安装消息

  • 项目

Teams 中的主动消息传递

由机器人发起主动消息，从而开始与用户对话。 它们提供多种用途，包括发送欢迎消息、进行调查或投票，以及广播组织范围内的通知。 Teams 中的主动消息可以作为 临时 或 基于对话 的对话传递:

消息类型 说明
临时主动消息 机器人在不中断对话流的情况下插入消息。
基于对话的主动消息 机器人会新建对话线程、控制对话、传递主动消息、关闭控制并将控制返回给前一个对话。

Teams 中的主动应用安装

在机器人可以主动向用户发送消息之前，必须将其安装为个人应用，或安装在用户所属的团队中。 有时，你需要主动向尚未安装或以前未与应用交互的用户发送消息。 例如，如果需要向组织中的每个人发送重要信息，则可以使用 Microsoft 图形 API为用户主动安装机器人。

权限

Microsoft Graph teamsAppInstallation 资源类型 权限有助于管理 Microsoft Teams 平台内所有用户(个人)或团队(频道)作用域的应用安装生命周期:

应用权限 说明
TeamsAppInstallation.ReadWriteSelfForUser.All 允许 Teams 应用为任何 用户 读取、安装、升级并卸载自身，无需事先登录或使用。
TeamsAppInstallation.ReadWriteSelfForTeam.All 允许 Teams 应用在任何 团队 中读取、安装、升级并卸载自身，无需事先登录或使用。

若要使用这些权限，必须将 webApplicationInfo 密钥添加到应用清单 (以前称为 Teams 应用清单) 具有以下值：

  • id：Microsoft Entra应用 ID。
  • 资源: 应用的资源 URL。

注意

  • 由于是为他人进行安装，因此机器人需要应用程序，而非用户委派的权限。

  • Microsoft Entra租户管理员必须显式授予应用程序的权限。 向应用程序授予权限后，Microsoft Entra租户的所有成员都会获得授予的权限。

启用主动应用安装和消息传递

重要

Microsoft Graph 只能安装发布到组织的应用商店或 Microsoft Teams 应用商店的应用。

为 Teams 创建并发布主动消息传递机器人

若要开始，你需要一个适用于 Teams 的机器人，该机器人具有组织的应用商店或 Teams 应用商店中的主动消息传递功能。

提示

生产就绪 公司 Communicator 应用模板允许广播消息传递，且是生成主动机器人应用程序的良好起点。

获取应用的 teamsAppId

可以通过以下方式检索 teamsAppId:

  • 从组织的应用目录:

    Microsoft Graph 页面参考：teamsApp 资源类型

    HTTP GET 请求:

    GET https://graph.microsoft.com/v1.0/appCatalogs/teamsApps?$filter=externalId eq '{IdFromManifest}'

    请求必须返回 teamsApp 对象 id，即应用目录生成的应用 ID。 这与在应用清单中提供的 ID 不同：

    {
  "value": [
    {
      "id": "b1c5353a-7aca-41b3-830f-27d5218fe0e5",
      "externalId": "f31b1263-ba99-435a-a679-911d24850d7c",
      "name": "Test App",
      "version": "1.0.1",
      "distributionMethod": "Organization"
    }
  ]
}

    注意

    当应用位于 Teams 应用商店中时， teamsAppId 与 相同 IdFromManifest ， externalId 在这种情况下不得使用 。

  • 如果应用已为个人范围内的用户上传：

    Microsoft Graph 页面参考：列出为用户安装的应用

    HTTP GET 请求:

    GET https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps?$expand=teamsApp&$filter=teamsApp/externalId eq '{IdFromManifest}'

  • 如果已为团队范围内的频道上传应用：

    Microsoft Graph 页面参考：列出团队中的应用

    HTTP GET 请求:

    GET https://graph.microsoft.com/v1.0/teams/{team-id}/installedApps?$expand=teamsApp&$filter=teamsApp/externalId eq '{IdFromManifest}'

    提示

    要压缩结果列表，可以筛选 teamsApp 对象的字段。

确定当前是否已为消息收件人安装机器人

可以确定当前是否已为消息收件人安装机器人，如下所示:

Microsoft Graph 页面参考：列出为用户安装的应用

HTTP GET 请求:

GET https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps?$expand=teamsApp&$filter=teamsApp/id eq '{teamsAppId}'

请求返回:

  • 如果未安装应用，则为空数组。
  • 具有单一 teamsAppInstallation 对象的数组(如果已安装应用)。

安装应用

可以安装应用，如下所示:

Microsoft Graph 页面参考：为用户安装应用

HTTP POST 请求:

POST https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps
Content-Type: application/json

{
   "teamsApp@odata.bind" : "https://graph.microsoft.com/v1.0/appCatalogs/teamsApps/{teamsAppId}"
}

如果用户正在运行 Microsoft Teams，则会立即安装应用。 可能需要重启才可查看已安装的应用。

检索对话 chatId

为用户安装应用后，机器人会收到事件 conversationUpdate通知 ，其中包含发送主动消息所需的信息。

Microsoft Graph 页面参考：获取聊天

  1. 必须具有应用的 {teamsAppInstallationId}。 如果没有，请使用以下命令：

    HTTP GET 请求:

    GET https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps?$expand=teamsApp&$filter=teamsApp/id eq '{teamsAppId}'

    响应的 ID 属性为 teamsAppInstallationId。

  2. 发出以下请求以提取 chatId:

    HTTP GET 请求 (权限 —TeamsAppInstallation.ReadWriteSelfForUser.All) ：

    GET https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps/{teamsAppInstallationId}/chat

    响应的 ID 属性为 chatId。

    还可以使用以下请求检索 chatId，但需要更广泛的 Chat.Read.All 权限:

    HTTP GET 请求 (权限 —Chat.Read.All) ：

    GET https://graph.microsoft.com/v1.0/users/{user-id}/chats?$filter=installedApps/any(a:a/teamsApp/id eq '{teamsAppId}')

发送主动邮件

在已为用户或团队添加机器人且已收到所有用户信息后，机器人可以 发送主动消息。

代码段

以下代码提供了发送主动消息的示例:

public async Task<int> SendNotificationToAllUsersAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
   int msgSentCount = 0;

   // Send notification to all the members.
   foreach (var conversationReference in _conversationReferences.Values)
   {
       await turnContext.Adapter.ContinueConversationAsync(_configuration["MicrosoftAppId"], conversationReference, BotCallback, cancellationToken);
       msgSentCount++;
   }

   return msgSentCount;
}

private async Task BotCallback(ITurnContext turnContext, CancellationToken cancellationToken)
{
    // Sends an activity to the sender of the incoming activity.
   await turnContext.SendActivityAsync("Proactive hello.");
}

代码示例

示例名称 说明 .NET Node.js
主动安装应用并发送主动通知 此示例演示如何通过调用 Microsoft Graph API 为用户使用主动安装应用并发送主动通知。 View View

其他代码示例

Teams 主动消息传递代码示例

另请参阅