机器人的主动消息传递

重要

本文基于 v3 Bot Framework SDK。 如果要查找 SDK 的当前文档 4.6 或更高版本，请参阅 对话机器人 部分。

主动消息是由机器人发送以启动对话的消息。 希望机器人开始对话的原因可能有很多，其中包括：

• 个人机器人对话的欢迎消息。
• 轮询响应。
• 外部事件通知。

发送消息以启动新的会话线程不同于发送消息以响应现有会话。 当机器人开始新对话时，是不存在将消息发布到预先存在的对话中的。 若要发送主动消息，需要：

1. 决定要说的内容
2. 获取用户的唯一 ID 和租户 ID
3. 发送邮件

创建主动消息时，必须调用 MicrosoftAppCredentials.TrustServiceUrl，并在创建用于发送消息的 ConnectorClient 之前传入服务 URL。 如果没有，应用会收到 401: Unauthorized 响应。 有关详细信息，请参阅 示例。

主动消息传递的最佳做法

发送主动消息是一种与用户沟通的有效方式。 但是，从用户的角度来看，该消息似乎是未经提示的。 如果有欢迎消息，这是他们第一次与你的应用交互。 使用此功能并向用户提供完整信息以了解该消息的用途非常重要。

主动消息一般分为两类: 欢迎消息或通知。

欢迎消息

使用主动消息传递向用户发送欢迎消息时，请确保从用户的角度来看，该消息不会出现提示。 如果有欢迎消息，这是他们第一次与你的应用交互。 最佳欢迎消息包括：

• 为什么他们收到此消息：用户应该清楚他们收到此消息的原因。 如果机器人安装在频道中，并且你向所有用户发送了欢迎消息，请让他们知道它安装在哪个频道中以及可能谁安装了它。
• 你提供什么：它们可以对你的应用执行哪些操作？ 可以为他们带来什么价值？
• 他们接下来应该做什么：邀请用户尝试某个命令，或者以某种方式与应用交互。

通知消息

使用主动消息发送通知时，需要确保用户有一个清晰的路径，以便根据通知采取常见操作，并清楚地了解通知发生的原因。 良好的通知消息通常包括：

• 发生了什么：明确指出发生了什么情况才导致发送通知。
• 它发生了什么：应该清楚更新了哪些项目/内容来引起通知。
• 谁做的：谁执行了导致发送通知的操作？
• 他们可以对其执行的操作：使用户能够轻松地根据通知执行操作。
• 如何选择退出：为用户提供选择退出其他通知的路径。

获取必要的用户信息

机器人可以通过获取用户 的唯一 ID 和 租户 ID 与单个 Microsoft Teams 用户创建新对话。可以使用以下方法之一获取这些值：

• 从安装应用的频道提取团队名单。
• 当用户在频道中与机器人交互时缓存它们。
• 当在机器人所属的频道对话中 @提及用户时。
• 当在个人范围内安装应用或将新成员添加到频道或群组聊天时，收到 conversationUpdate 事件时则缓存它们。

使用 Graph 主动安装应用

注意

目前，使用 Graph 主动安装应用处于 beta 阶段。

有时，可能需要主动向之前未安装或与应用交互的用户发送消息。 例如，你希望使用公司通信器向整个组织发送消息。 对于这种情况，可以使用 Graph API 主动为用户安装应用，然后缓存应用在安装时将收到的 conversationUpdate 事件中的必要值。

只能安装组织应用目录或 Microsoft Teams 应用商店中的应用。

有关完整详细信息，请参阅 Graph 文档中的为用户安装应用。 .NET 中还有一个示例。

示例

在使用 REST API 创建新会话之前，请确保你进行身份验证并具有 持有者令牌 。

POST {Service URL of your bot}/v3/conversations

{
  "bot": {
    "id": "c38eda0f-e780-49ae-86f0-afb644203cf8",
    "name": "The Bot"
  },
  "members": [
    {
      "id": "29:012d20j1cjo20211"
    }
  ],
  "channelData": {
    "tenant": {
      "id": "197231joe-1209j01821-012kdjoj"
    }
  }
}

提供 id 作为机器人应用 ID 和 name 机器人名称。 可以从机器人对象（例如 turnContext.Activity.From.Id）获取 membersid 。TurnContext 同样， id 租户从机器人 TurnContext 对象（例如 turnContext.Activity.ChannelData.Tenant.Id）中获取。

你必须提供用户 ID 和租户 ID。 如果调用成功，API 将返回以下响应对象。

{
    "id":"a:1qhNLqpUtmuI6U35gzjsJn7uRnCkW8NiZALHfN8AMxdbprS1uta2aT-jytfIlsZR3UZeg3TsIONNInBHsdjzj3PtfHuhkxxvS1jZZ61UAbw8fIdXcNSJyTJm7YvHFOgxo"

}

此 ID 是个人聊天的唯一对话 ID。 请存储此值，并将其重复用于将来与用户的交互。

使用 .NET

此示例使用 Microsoft.Bot.Connector.Teams NuGet 包。

// Create or get existing chat conversation with user
var response = client.Conversations.CreateOrGetDirectConversation(activity.Recipient, activity.From, activity.GetTenantId());

// Construct the message to post to conversation
Activity newActivity = new Activity()
{
    Text = "Hello",
    Type = ActivityTypes.Message,
    Conversation = new ConversationAccount
    {
        Id = response.Id
    },
};

// Post the message to chat conversation with user
await client.Conversations.SendToConversationAsync(newActivity, response.Id);

使用 Node.js

var address =
{
    channelId: 'msteams',
    user: { id: userId },
    channelData: {
        tenant: {
            id: tenantId
        }
    },
    bot:
    {
        id: appId,
        name: appName
    },
    serviceUrl: session.message.address.serviceUrl,
    useAuth: true
}

var msg = new builder.Message().address(address);
msg.text('Hello, this is a notification');
bot.send(msg);

创建频道对话

团队添加的机器人可以发布到频道中，以创建新的回复链。 如果使用的是 Node.js Teams SDK，请使用 startReplyChain()，它会提供一个完全填充的地址，其中包含正确的活动 ID 和对话 ID。 如果使用的是 C#，请参阅以下示例。

或者，可以使用 REST API 并向 /conversations 资源发出 POST 请求。

创建频道对话的示例

C#

.NET 示例来自 此示例

using Microsoft.Bot.Builder.Dialogs;
using Microsoft.Bot.Connector;
using Microsoft.Bot.Connector.Teams.Models;
using Microsoft.Teams.TemplateBotCSharp.Properties;
using System;
using System.Threading.Tasks;

namespace Microsoft.Teams.TemplateBotCSharp.Dialogs
{
    [Serializable]
    public class ProactiveMsgTo1to1Dialog : IDialog<object>
    {
        public async Task StartAsync(IDialogContext context)
        {
            if (context == null)
            {
                throw new ArgumentNullException(nameof(context));
            }

            var channelData = context.Activity.GetChannelData<TeamsChannelData>();
            var message = Activity.CreateMessageActivity();
            message.Text = "Hello World";

            var conversationParameters = new ConversationParameters
            {
                  IsGroup = true,
                  ChannelData = new TeamsChannelData
                  {
                      Channel = new ChannelInfo(channelData.Channel.Id),
                  },
                  Activity = (Activity) message
            };

            MicrosoftAppCredentials.TrustServiceUrl(serviceUrl, DateTime.MaxValue);
            var connectorClient = new ConnectorClient(new Uri(activity.ServiceUrl));
            var response = await connectorClient.Conversations.CreateConversationAsync(conversationParameters);

            context.Done<object>(null);
        }
    }
}

Node.js

export async function startReplyChain(chatConnector: builder.ChatConnector, message: builder.Message, channelId: string): Promise<builder.IChatConnectorAddress> {
    let activity = message.toMessage();

    // Build request
    let options: request.Options = {
        method: "POST",
        // We use urlJoin to concatenate urls. url.resolve should not be used here,
        // since it resolves urls as hrefs are resolved, which could result in losing
        // the last fragment of the serviceUrl
        url: urlJoin((activity.address as any).serviceUrl, "/v3/conversations"),
        body: {
            isGroup: true,
            activity: activity,
            channelData: {
                teamsChannelId: channelId,
            },
        },
        json: true,
    };

    let response = await sendRequestWithAccessToken(chatConnector, options);
    if (response && response.hasOwnProperty("id")) {
        let address = createAddressFromResponse(activity.address, response) as any;
        if (address.user) {
            delete address.user;
        }
        if (address.correlationId) {
            delete address.correlationId;
        }
        return address;
    } else {
        throw new Error("Failed to start reply chain: no conversation ID returned.");
    }
}

HTTP

POST {Service URL of your bot}/v3/conversations

{
    "activity": {
        "type": "message",
        "text": "new conversation"
    },
    "bot": {
        "id": "{{botID}}",
        "name": "{{botName}}"
    },
    "channelData":{
      "teamsChannelId":"{{teamID}}",
      "teamsTeamId":"{{teamID}}",
      "channel":{"id":"{{teamID}}"},
      "team":{"id":"{{teamID}}"},
      "tenant":{"id": "{{tenantID}}"}
    },
    "isGroup": true,
    "tenantId": "{{tenantID}}"
}

可以从 对象（如 turnContext.Activity.ServiceURL 参数）获取 。{Service URL of your bot}TurnContext

可以从 对象（如 turnContext.Activity.TeamsChannelData 参数）获取 。channelDataTurnContext

提供 id 作为机器人应用 ID 和 name 机器人名称。 同样， id 租户从机器人 TurnContext 对象（例如 turnContext.Activity.ChannelData.Tenant.Id）中获取。

同样，可以在节中channelData为 teamsChannelId、teamsTeamId、、channel、team提供 teamID ，以将消息发送到团队的常规频道。

如果调用成功，API 将返回以下响应对象：

{
    "id": "{{conversationID}}",
    "activityId": "{{activityID}}"
}

另请参阅

Bot Framework 示例。