使用 Microsoft Graph 公共预览版启用 Teams 中的主动机器人安装 (主动) Enable proactive bot installation and proactive messaging in Teams with Microsoft Graph (Public Preview)

重要

Microsoft Graph 和 Microsoft Teams 公共预览版可提供快速访问权限和反馈。Microsoft Graph and Microsoft Teams public previews are available for early-access and feedback. 虽然此版本已经进行了大的测试,但它不适合用于生产。Although this release has undergone extensive testing, it is not intended for use in production.

Teams 中的主动消息传递Proactive messaging in Teams

主动邮件由机器人启动,以与用户开始对话。Proactive messages are initiated by bots to start conversations with a user. 它们用于许多目的,包括发送欢迎邮件、进行调查或投票,以及广播组织范围内的通知。They serve many purposes including sending welcome messages, conducting surveys or polls, and broadcasting organization-wide notifications. Teams 中的主动消息可以作为临时对话或基于对话框****的对话传递:Proactive messages in Teams can be delivered as either ad-hoc or dialog-based conversations:

消息类型Message Type 说明Description
临时主动邮件Ad-hoc proactive message 机器人将截获一条消息,而不会中断对话流。The bot interjects a message without interrupting the conversation flow.
基于对话框的主动邮件Dialog-based proactive message 机器人会创建新的对话框线程,控制对话,传递主动消息,关闭,然后将控件返回到上一个对话。The bot creates a new dialog thread, takes control of a conversation, delivers the proactive message, closes, and returns control to the previous dialog.

请参阅向用户 SDK v4 发送主动通知See, Send proactive notifications to users SDK v4

Teams 中的主动应用安装Proactive app installation in Teams

在自动程序可主动向用户传出消息之前,需要将其作为个人应用或用户所在团队进行安装。Before your bot can proactively message a user, it needs to be installed either as a personal app, or in a team where the user is a member. 有时,你可能需要主动向尚未 安装或之前 未与应用进行交互的消息用户。At times, you may need to proactively message users that have not installed or previously interacted with your app. 例如,需要向组织中的所有人显示至其他所有人的信息。For instance, the need to message vital information to everyone in your organization. 对于此类应用场景,可使用 Microsoft Graph API 主动为用户安装自动程序。For such scenarios, you can use the Microsoft Graph API to proactively install your bot for your users.

权限Permissions

使用 Microsoft Graph teamsAppInstallation 资源类型 权限,可管理 Microsoft Teams 平台内 (个人) 或团队 (频道) 的应用安装生命周期:Microsoft Graph teamsAppInstallation resource type permissions allow you to manage your app's installation lifecycle for all user (personal) or team (channel) scopes within the Microsoft Teams platform:

应用权限Application permission 说明Description
TeamsAppInstallation.ReadWriteSelfForUser.All 允许 Teams 应用针对任何用户自己读取、安装 、升级和卸载其自身,而无需在登录或使用之前。Allows a Teams app to read, install, upgrade, and uninstall itself for any user, without prior sign in or use.
TeamsAppInstallation.ReadWriteSelfForTeam.All 允许 Teams 应用在任何团队中自行读取、安装、升级和 卸载其自身,而无需先登录或使用。Allows a Teams app to read, install, upgrade, and uninstall itself in any team, without prior sign in or use.

若要使用这些权限,必须使用以下 值将 webApplicationInfo 密钥添加到应用部件清单:To use these permissions, you must add a webApplicationInfo key to your app manifest with the following values:

  • id — 你的 Azure AD 应用 ID。id — your Azure AD app id.
  • 资源 — 应用程序的资源 URL。resource — the resource URL for the app.

备注

  • 自动程序不需要_具有非__用户委派权限_的应用程序,因为安装对用户来来并不是用户。Your bot requires application not user delegated permissions because the installation is not for yourself but for others.

  • Azure AD 租户管理员必须 对应用程序显式授予权限An Azure AD tenant administrator must explicitly grant permissions to an application. 授权应用程序后 ,Azure AD 租户的所有成员都将获取已授予的权限。After an application is granted permissions, all members of the Azure AD tenant will gain the granted permissions.

启用主动应用安装和消息Enable proactive app installation and messaging

重要

Microsoft Graph 仅将安装在组织的应用程序目录或 AppSource 中发布的应用Microsoft Graph will only install apps published within your organization's app catalog or in AppSource.

✔为 Teams 创建和发布主动邮件传递自动程序✔ Create and publish your proactive messaging bot for Teams

若要开始使用,需要具有主动邮件功能的 Teamsproactive messaging自动程序,并发布在组织的应用目录 AppSource 中To get started, you will need a bot for Teams with proactive messaging capabilities and published in your organization's app catalog or in AppSource.

提示

生产就绪 型公司Communicator 公司模板支持广播消息,并且是构建主动机器人应用程序的很好基础。The production-ready Company Communicator app template enables broadcast messaging and is a good foundation for building your proactive bot application.

✔为 teamsAppId 你的应用获取✔ Get the teamsAppId for your app

1. 后续步骤 teamsAppId 中将需要您。1. You will need the teamsAppId for the next steps.

可以 teamsAppId 从组织的应用程序目录检索到:The teamsAppId can be retrieved from your organization's app catalog:

Microsoft Graph 页参考:teamsApp 资源类型Microsoft Graph page reference: teamsApp resource type

HTTP GET 请求:HTTP GET request:

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

请求将返回 teamsApp 对象。The request will return a teamsApp object. 返回的对象是 id 应用的目录生成的应用 ID,与在 Teams 应用清单中提供的"id:"不同:The returned object's id is the app's catalog generated app id and is different from the "id:" that you provided in your Teams app manifest:

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

2. 如果已为个人范围内的用户上传/旁加载应用,你可以如下所示 teamsAppId 进行检索:2. If your app has already been uploaded/sideloaded for a user in the personal scope, you can retrieve the teamsAppId as follows:

Microsoft Graph 页参考:列出为用户安装的应用Microsoft Graph page reference: List apps installed for user

HTTP GET 请求:HTTP GET request:

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

3. 如果已为团队范围内的频道上传/旁加载应用,可以按如下所示 teamsAppId 检索:3. If your app has already been uploaded/sideloaded for a channel in the team scope, you can retrieve the teamsAppId as follows:

Microsoft Graph 页参考:列出团队中的应用Microsoft Graph page reference: List apps in team

HTTP GET 请求:HTTP GET request:

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

提示

可以筛选 teamsApp 对象的任何字段来缩小结果列表。You can filter on any of the fields of the teamsApp object to narrow the list of results.

✔确定当前是否为邮件收件人安装了机器人✔ Determine whether your bot is currently installed for a message recipient

Microsoft Graph 页参考:列出为用户安装的应用Microsoft Graph page reference: List apps installed for user

HTTP GET 请求:HTTP GET request:

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

如果未安装应用,则此请求将返回空数组,或者返回包含单个 teamsAppInstallation 对象的数组(如果已安装)。This request will return an empty array if the app is not installed, or an array with a single teamsAppInstallation object if it has been installed.

✔安装应用✔ Install your app

Microsoft Graph 参考:为用户安装应用Microsoft Graph reference: Install app for user

HTTP POST 请求:HTTP POST request:

POST https://graph.microsoft.com/beta/users/{user-id}/teamwork/installedApps
{
   "teamsApp@odata.bind" : "https://graph.microsoft.com/beta/appCatalogs/teamsApps/{teamsAppId}"
}

如果用户运行 Microsoft Teams,可能会立即看到应用安装。If the user has Microsoft Teams running, they may see the app install immediately. 或者,可能需要重新启动才能查看已安装的应用。Alternatively, a restart may be necessary to see the installed app.

✔检索对话 chatId✔ Retrieve the conversation chatId

为用户安装应用后,机器人将收到 conversationUpdate 事件通知 ,其中包含发送主动消息所需的信息。When your app is installed for the user, the bot will receive a conversationUpdate event notification that will contain the necessary information to send the proactive message.

chatId也可以按如下方式检索:The chatId can also be retrieved as follows:

Microsoft Graph 参考:获取聊天Microsoft Graph reference: Get chat

1. 您将需要您的应用程序 {teamsAppInstallationId}1. You will need your app's {teamsAppInstallationId}. 如果没有,请使用以下名称:If you don't have it, use the following:

HTTP GET 请求:HTTP GET request:

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

响应的 id 属性为 teamsAppInstallationId .The id property of the response is the teamsAppInstallationId.

2. 发出以下请求可提取 chatId2. Make the following request to fetch the chatId:

HTTP GET 请求 (权限 — TeamsAppInstallation.ReadWriteSelfForUser.All) :HTTP GET request (permission — TeamsAppInstallation.ReadWriteSelfForUser.All):

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

响应的 id 属性为 chatId .The id property of the response is the chatId.

或者,你也可以根据 chatId 下面请求检索请求,但需要更广泛 Chat.Read.All 的权限:Alternately, you can retrieve the chatId with the request below, but it will require the broader Chat.Read.All permission:

HTTP GET 请求 (权限 — Chat.Read.All) :HTTP GET request (permission — Chat.Read.All):

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

✔动发送主动邮件✔ Send proactive messages

为用户或团队添加了机器人并获取必要的用户信息后,可以开始 发送主动邮件Once your bot has been added for a user or team and has acquired the necessary user information, it can begin to send proactive messages.

以下代码段来自 于 C# 的 Microsoft Bot Framework 示例。The following code snippet is from the Microsoft Bot Framework Samples for C#.

using System.Collections.Concurrent;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Bot.Builder;
using Microsoft.Bot.Schema;

namespace Microsoft.BotBuilderSamples
{
    public class ProactiveBot : ActivityHandler
    {
        // Message to send to users when the bot receives a Conversation Update event
        private const string WelcomeMessage = "Welcome to the Proactive Bot sample.  Navigate to http://localhost:3978/api/notify to proactively message everyone who has previously messaged this bot.";

        // Dependency injected dictionary for storing ConversationReference objects used in NotifyController to proactively message users
        private readonly ConcurrentDictionary<string, ConversationReference> _conversationReferences;

        public ProactiveBot(ConcurrentDictionary<string, ConversationReference> conversationReferences)
        {
            _conversationReferences = conversationReferences;
        }

        private void AddConversationReference(Activity activity)
        {
            var conversationReference = activity.GetConversationReference();
            _conversationReferences.AddOrUpdate(conversationReference.User.Id, conversationReference, (key, newValue) => conversationReference);
        }

        protected override Task OnConversationUpdateActivityAsync(ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
        {
            AddConversationReference(turnContext.Activity as Activity);

            return base.OnConversationUpdateActivityAsync(turnContext, cancellationToken);
        }

        protected override async Task OnMembersAddedAsync(IList<ChannelAccount> membersAdded, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
        {
            foreach (var member in membersAdded)
            {
                // Greet anyone that was not the target (recipient) of this message.
                if (member.Id != turnContext.Activity.Recipient.Id)
                {
                    await turnContext.SendActivityAsync(MessageFactory.Text(WelcomeMessage), cancellationToken);
                }
            }
        }

        protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
        {
            AddConversationReference(turnContext.Activity as Activity);

            // Echo back what the user said
            await turnContext.SendActivityAsync(MessageFactory.Text($"You sent '{turnContext.Activity.Text}'"), cancellationToken);
        }
    }
}

查看其他代码示例View additional code samples