发送主动安装消息

Teams 中的主动消息传递

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

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

Teams 中的主动应用安装

在机器人可以主动向用户发送消息之前,必须将其安装为个人应用,或安装在用户所属的团队中。 有时,你需要主动向尚未安装或以前未与应用交互的用户发送消息。 例如,如果需要向组织中的每个人发送重要信息,则可以使用 Microsoft Graph 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 与 相同 IdFromManifestexternalId 在这种情况下不得使用 。

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

    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

其他代码示例

另请参阅