次の方法で共有

ボットのプロアクティブ メッセージング

  • [アーティクル]

重要

この記事は、v3 Bot Framework SDK に基づいています。 SDK の現在のドキュメント バージョン 4.6 以降をお探しの場合は、「 会話ボット 」セクションを参照してください。

プロアクティブ メッセージは、会話を開始するためにボットによって送信されるメッセージです。 ボットに会話を開始させる理由として、次のようなものがあります。

  • 個人用ボットの会話用のウェルカム メッセージ。
  • ポーリング応答。
  • 外部イベント通知。

新しい会話スレッドを開始するためのメッセージの送信は、既存の会話に応答してメッセージを送信する場合とは異なります。 ボットが新しい会話を開始する場合は、メッセージの投稿先となる既存の会話がありません。 プロアクティブ メッセージを送信するには、次の手順を実行する必要があります。

  1. 何を言うかを決める
  2. ユーザーの一意の ID とテナント ID を取得する
  3. メッセージを送信する

プロアクティブ メッセージを作成するときは、MicrosoftAppCredentials.TrustServiceUrlを呼び出し、メッセージの送信に使用するConnectorClientを作成する前にサービス URL を渡す必要があります。 そうでない場合は、アプリによって 401: Unauthorized 応答が受信されます。 詳細については、 サンプルを参照してください。

プロアクティブ メッセージングのベスト プラクティス

プロアクティブ メッセージの送信は、ユーザーと通信するための効果的な方法です。 ただし、ユーザーの観点からは、メッセージはプロンプトなしで表示されます。 ウェルカム メッセージがある場合は、アプリと対話するのは初めてです。 この機能を使用し、このメッセージの目的を理解するためにユーザーに完全な情報を提供することが重要です。

プロアクティブ メッセージは、一般にウェルカム メッセージと通知の 2 つのカテゴリに分類されます。

ウェルカム メッセージ

プロアクティブ メッセージングを使用してウェルカム メッセージをユーザーに送信する場合は、ユーザーの観点からメッセージが実行されていないことを確認します。 ウェルカム メッセージがある場合は、アプリと対話するのは初めてです。 最適なウェルカム メッセージは次のとおりです。

  • このメッセージを受信する理由: このメッセージを受け取る理由は、ユーザーには明確にする必要があります。 あなたのボットがチャネルにインストールされていて、すべてのユーザーにウェルカム メッセージを送信した場合は、どのチャネルにインストールされ、誰がインストールしたのかを通知する必要があります。
  • 何を提供しますか: アプリで何ができますか? ユーザーはどのような価値を得られるのでしょうか?
  • 次に実行する必要がある操作: コマンドを試すか、何らかの方法でアプリを操作するように招待します。

通知メッセージ

プロアクティブ メッセージングを使用して通知を送信する場合は、通知に基づいて一般的なアクションを実行するための明確なパスと、通知が発生した理由を明確に理解する必要があります。 通常、適切な通知メッセージには次のものが含まれます。

  • 何が起こったか: 通知の原因を明確に示します。
  • 何が起こったか:通知を引き起こすために更新されたアイテム/物は明らかです。
  • 誰が行ったか: 通知を送信する原因となったアクションを実行したのは誰ですか?
  • ユーザーがそれに対してできること: ユーザーが通知に基づいて簡単にアクションを実行できるようにします。
  • オプトアウトする方法: ユーザーが追加の通知をオプトアウトするためのパスを指定します。

必要なユーザー情報を取得する

ボットは、ユーザーの 一意の ID と テナント ID を取得することで、個々のMicrosoft Teams ユーザーとの新しい会話を作成できます。これらの値は、次のいずれかの方法で取得できます。

  • アプリがインストールされているチャネルから チーム名簿をフェッチ します。
  • ユーザーが チャネルでボットと対話するときにキャッシュする。
  • ユーザーが チャネル会話で@mentioned されている場合、ボットはの一部です。
  • アプリが個人用スコープにインストールされたとき、または新しいメンバーがチャネルまたはグループ チャットに追加されたときに、conversationUpdate イベントを受信したときにキャッシュします。

Graph を使用してアプリをプロアクティブにインストール

注:

Graph を使用してアプリを事前にインストールすることはベータ版です。

場合によっては、以前にアプリをインストールまたは操作していないユーザーに事前にメッセージを送信することが必要になる場合があります。 たとえば、社内コミュニケーターを使用して、組織全体にメッセージを送信する必要があるとします。 このシナリオでは、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などのオブジェクトTurnContextボットからmembersidを取得できます。 同様に、テナントのid、ボットから turnContext.Activity.ChannelData.Tenant.Id などのオブジェクトTurnContext。

ユーザー 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 を使用し、POST 要求を発行してリソースを /conversations することもできます。

チャネル会話を作成する例

.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);
        }
    }
}

関連項目

Bot Framework サンプル。