ユーザーへのプロアクティブな通知の送信

[アーティクル]
03/08/2023

この記事の対象: SDK v4

通常、ボットは、ユーザーからのメッセージの受信に応答して、ユーザーに直接メッセージを送信します。場合によっては、ボットがプロアクティブメッセージ (ユーザーを起源としない要因に応答するメッセージ) を送信する必要がある場合があります。

プロアクティブメッセージは、さまざまなシナリオで役立ちます。たとえば、ユーザーが製品の価格を監視するようにボットに依頼していた場合、ボットは、製品の価格が 20% 下がった場合にユーザーにアラートを発行できます。ユーザーの質問に対する回答をまとめるのに時間が必要な場合、ボットは、時間がかかることをユーザーに通知して、会話を続けられるようにします。質問の回答がまとまったら、ボットは、その情報をユーザーと共有します。

この記事では、一般的なボットのプロアクティブメッセージに関する情報について説明します。 Microsoft Teams におけるプロアクティブメッセージの詳細については、以下をご覧ください。

C#、JavaScript、Java または Python の Teams の会話ボット サンプル
プロアクティブメッセージを送信する方法に関する Microsoft Teams のドキュメント。

Note

Bot Framework JavaScript SDK、C#、Python SDK は引き続きサポートされますが、Java SDK については、最終的な長期サポートは 2023 年 11 月に終了する予定です。

Java SDK を使用して構築された既存のボットは引き続き機能します。

新しいボットを構築する場合は、Microsoft Copilot Studio の使用をご検討ください。また、適切なコパイロットソリューションの選択に関する記事もお読みください。

詳細については、「The future of bot building」をご覧ください。

前提条件

ボットの基本を理解する。
プロアクティブメッセージ サンプルのコピー (C#、JavaScript、Java、または Python)。このサンプルは、この記事でプロアクティブメッセージングを説明するために使用します。

プロアクティブサンプルについて

一般に、アプリケーションとしてのボットにはいくつかのレイヤーがあります。

HTTP 要求を受け入れることができ、特にメッセージングエンドポイントをサポートする Web アプリケーション。
チャネルとの接続を処理するアダプター。
ターンのハンドラー。通常、ボットアプリの会話の理由を処理する bot クラス内にカプセル化されます。

ユーザーからの受信メッセージに応答して、アプリはアダプターの プロセスアクティビティ メソッドを呼び出します。これにより、ターンおよびターンコンテキストが作成され、ミドルウェアパイプラインが呼び出され、ボットのターンハンドラーが呼び出されます。

プロアクティブメッセージを開始するには、ボットアプリケーションが他の入力を受信できる必要があります。プロアクティブメッセージを開始するためのアプリケーションロジックは、SDK の範囲外です。このサンプルでは、標準のメッセージ エンドポイントに加えて、通知エンドポイントを使用してプロアクティブターンをトリガーします。

この通知エンドポイントの GET 要求に応答して、アプリはアダプターの会話継続メソッドを呼び出します。これはアクティビティ処理メソッドと似た方法で動作します。 会話継続メソッド:

プロアクティブターンに使用するための、ユーザーとコールバックメソッドの適切な会話参照を受け取ります。
プロアクティブターンのイベントアクティビティとターンコンテキストを作成します。
アダプターのミドルウェアパイプラインを呼び出します。
指定されたコールバックメソッドを呼び出します。
ターンコンテキストでは、会話参照を使用して、メッセージをユーザーに送信します。

次の図に示すように、このサンプルには、ボット、メッセージエンドポイント、プロアクティブメッセージをボットに送信するために使用される追加エンドポイントが含まれています。

ボットが会話参照を取得し、それを使用してプロアクティブメッセージを送信する方法を示す対話図。

会話の参照を取得して格納する

Bot Framework Emulator がボットに接続する際に、ボットは 2 つの会話更新アクティビティを受け取ります。次に示すように、ボットの会話更新アクティビティハンドラーで、会話の参照が取得され、ディクショナリに格納されます。

Bots\ProactiveBot.cs

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

bots/proactiveBot.js

this.onConversationUpdate(async (context, next) => {
    this.addConversationReference(context.activity);

    await next();
});

addConversationReference(activity) {
    const conversationReference = TurnContext.getConversationReference(activity);
    this.conversationReferences[conversationReference.conversation.id] = conversationReference;
}

ProactiveBot.java

@Override
protected CompletableFuture<Void> onConversationUpdateActivity(TurnContext turnContext) {
    addConversationReference(turnContext.getActivity());
    return super.onConversationUpdateActivity(turnContext);
}

// adds a ConversationReference to the shared Map.
private void addConversationReference(Activity activity) {
    ConversationReference conversationReference = activity.getConversationReference();
    conversationReferences.put(conversationReference.getUser().getId(), conversationReference);
}

bots/proactive_bot.py

async def on_conversation_update_activity(self, turn_context: TurnContext):
    self._add_conversation_reference(turn_context.activity)
    return await super().on_conversation_update_activity(turn_context)

def _add_conversation_reference(self, activity: Activity):
    """
    This populates the shared Dictionary that holds conversation references. In this sample,
    this dictionary is used to send a message to members when /api/notify is hit.
    :param activity:
    :return:
    """
    conversation_reference = TurnContext.get_conversation_reference(activity)
    self.conversation_references[
        conversation_reference.user.id
    ] = conversation_reference

会話の参照には、アクティビティが存在する会話を表す conversation プロパティが含まれます。会話には、会話の参加ユーザーを一覧表示する user プロパティと、現在のアクティビティに対する返信が送信される可能性のある宛先を表す サービス URL プロパティが含まれます。プロアクティブメッセージをユーザーに送信するには、有効な会話の参照が必要です。 (Teams チャネルの場合、サービス URL はリージョン化されたサーバーにマップされます)。

Note

実際のシナリオでは、会話の参照はデータベースに保持されます。メモリ内のオブジェクトは使用されません。

プロアクティブなメッセージを送信する

2 番目のコントローラーである "通知" コントローラーは、プロアクティブメッセージをユーザーに送信する役割を果たします。次の手順で、プロアクティブメッセージを生成します。

プロアクティブメッセージを送信する先の会話の参照を取得します。
アダプターの continue conversation メソッドを呼び出して、使用するターンハンドラーデリゲートと会話の参照を指定します。 (continue conversation メソッドによって、参照されている会話に対してターンコンテキストが生成され、指定したターンハンドラーデリゲートが呼び出されます。)
デリゲートで、ターンコンテキストを使用して、プロアクティブメッセージを送信します。ここでは、委任は通知コントローラーで定義され、プロアクティブメッセージをユーザーに送信します。

Note

各チャネルでは安定したサービス URL を使用する必要があります。URL は時間の経過によって変化する可能性があります。サービス URL の詳細については、Bot Framework アクティビティスキーマの基本的なアクティビティ構造とサービス URL のセクションを参照してください。

サービス URL が変更されると、以前の会話参照は無効になり、会話を続行するための呼び出しによってエラーまたは例外が生成されます。この場合、ボットは、プロアクティブメッセージを再度送信する前に、ユーザーの新しい会話参照を取得する必要があります。

Controllers\NotifyController .cs

ボットの通知ページが要求されるたびに、通知コントローラーは、ディクショナリから会話の参照を取得します。次に、コントローラーは ContinueConversationAsync メソッドと BotCallback メソッドを使用して、プロアクティブメッセージを送信します。

[Route("api/notify")]
[ApiController]
public class NotifyController : ControllerBase
{
    private readonly IBotFrameworkHttpAdapter _adapter;
    private readonly string _appId;
    private readonly ConcurrentDictionary<string, ConversationReference> _conversationReferences;

    public NotifyController(IBotFrameworkHttpAdapter adapter, IConfiguration configuration, ConcurrentDictionary<string, ConversationReference> conversationReferences)
    {
        _adapter = adapter;
        _conversationReferences = conversationReferences;
        _appId = configuration["MicrosoftAppId"] ?? string.Empty;
    }

    public async Task<IActionResult> Get()
    {
        foreach (var conversationReference in _conversationReferences.Values)
        {
            await ((BotAdapter)_adapter).ContinueConversationAsync(_appId, conversationReference, BotCallback, default(CancellationToken));
        }
        
        // Let the caller know proactive messages have been sent
        return new ContentResult()
        {
            Content = "<html><body><h1>Proactive messages have been sent.</h1></body></html>",
            ContentType = "text/html",
            StatusCode = (int)HttpStatusCode.OK,
        };
    }

    private async Task BotCallback(ITurnContext turnContext, CancellationToken cancellationToken)
    {
        await turnContext.SendActivityAsync("proactive hello");
    }
}

index.js

サーバーの /api/notify ページが要求されるたびに、サーバーは、ディクショナリから会話の参照を取得します。次に、サーバーは continueConversation メソッドを使用して、プロアクティブメッセージを送信します。 continueConversation のパラメーターは、このターンのボットのターンハンドラーとして機能する関数です。

    res.setHeader('Content-Type', 'text/html');
    res.writeHead(200);
    res.write('<html><body><h1>Proactive messages have been sent.</h1></body></html>');
    res.end();
});

NotifyController.java

ボットの通知ページが要求されるたびに、通知コントローラーは、ディクショナリから会話の参照を取得します。次に、コントローラーは continueConversation メソッドを使用して、プロアクティブメッセージを送信します。

@RestController
public class NotifyController {
    /**
     * The BotFrameworkHttpAdapter to use. Note is is provided by dependency
     * injection via the constructor.
     *
     * @see com.microsoft.bot.integration.spring.BotDependencyConfiguration
     */
    private final BotFrameworkHttpAdapter adapter;

    private ConversationReferences conversationReferences;
    private String appId;

    @Autowired
    public NotifyController(
        BotFrameworkHttpAdapter withAdapter,
        Configuration withConfiguration,
        ConversationReferences withReferences
    ) {
        adapter = withAdapter;
        conversationReferences = withReferences;
        appId = withConfiguration.getProperty("MicrosoftAppId");
    }

    @GetMapping("/api/notify")
    public ResponseEntity<Object> proactiveMessage() {
        for (ConversationReference reference : conversationReferences.values()) {
            adapter.continueConversation(
                appId, reference, turnContext -> turnContext.sendActivity("proactive hello").thenApply(resourceResponse -> null)
            );
        }

        // Let the caller know proactive messages have been sent
        return new ResponseEntity<>(
            "<html><body><h1>Proactive messages have been sent.</h1></body></html>",
            HttpStatus.ACCEPTED
        );
    }
}

ボットの通知ページが要求されるたびに、サーバーは、ディクショナリから会話の参照を取得します。次に、サーバーは _send_proactive_message を使用して、プロアクティブメッセージを送信します。

if __name__ == "__main__":
    try:
        web.run_app(APP, host="localhost", port=CONFIG.PORT)
    except Exception as error:
        raise error

プロアクティブメッセージを送信するには、アダプターにボット用のアプリ ID が必要です。ボットのアプリ ID は、運用環境で使用できます。エミュレーターを使用してボットをローカルでテストする際に、空の文字列 ("") を使用できます。

ボットをテストする

Bot Framework Emulator をインストールします (まだインストールしていない場合)。
ご自身のマシンを使ってローカルでサンプルを実行します。
エミュレーターを起動し、ボットに接続します。
お使いのボットの API/通知ページに読み込みます。これによりエミュレーターでプロアクティブメッセージが生成されます。

追加情報

要件

プロアクティブメッセージを送信する前に、ボットに会話参照が必要です。ボットは、ユーザーから受信したアクティビティから会話参照を取得できますが、通常は、ボットがプロアクティブメッセージを送信する前に、少なくとも 1 回はユーザーがボットと対話する必要があります。

多くのチャネルでは、ユーザーがボットに少なくとも 1 回メッセージを送信していない限り、ボットがユーザーにメッセージを送信することを禁止しています。一部のチャネルでは例外が許可されます。たとえば、Teams チャネルでは、ボットは、ボットが含まれる確立済みグループ会話内の個人に対して、プロアクティブ (またはマンツーマン) メッセージを送信できます。

設計上の考慮事項

お使いのボットでプロアクティブメッセージを実装するときは、短い時間で複数のプロアクティブメッセージを送信しないでください。一部のチャネルでは、ボットがユーザーにメッセージを送信できる頻度に制限が設定され、これらの制限に違反した場合は、ボットが無効になります。

最も単純な種類のプロアクティブメッセージの場合、ボットは、現在の状態や会話のトピックに関係なく、メッセージがトリガーされたときにメッセージを会話に挿入します。このシナリオでは、プロアクティブメッセージによって通常の会話フローが中断されます。

通知をより円滑に処理するには、会話フローに通知を統合するための他の方法を検討してください (会話の状態にフラグを設定する方法や、通知をキューに追加する方法など)。

プロアクティブターンについて

continue conversation メソッドでは、会話参照とターンコールバックハンドラーを使用して次の操作を行います。

ボットアプリケーションがプロアクティブメッセージを送信できるターンを作成します。アダプターは、このターンの event アクティビティを作成し、その名前を "ContinueConversation" に設定します。
アダプターのミドルウェアパイプラインを経由してターンを送信します。
ターンコールバックハンドラーを呼び出してカスタムロジックを実行します。

プロアクティブメッセージ サンプルでは、ターンコールバックハンドラーは通知コントローラーで定義され、ボットの通常のターンハンドラーを介してプロアクティブアクティビティを送信することなく、メッセージを会話に直接送信します。また、このサンプルコードでは、プロアクティブターンでボットの状態にアクセスしたり、更新したりすることはありません。

多くのボットはステートフルであり、状態を使用して複数のターンで会話を管理します。 continue conversation メソッドでターンコンテキストが作成されると、ターンには適切なユーザーと会話の状態が関連付けられます。プロアクティブターンをボットのロジックに統合できます。ボットのロジックがプロアクティブメッセージを認識する必要がある場合は、何通りか方法があります。次のことを実行できます。

ボットのターンハンドラーをターンコールバックハンドラーとして指定します。その後、ボットは "ContinueConversation" イベントアクティビティを受け取ります。
ターンコールバックハンドラーを使用して、最初にターンコンテキストに情報を追加してから、ボットのターンハンドラーを呼び出します。

どちらの場合も、プロアクティブイベントを処理するようにボットロジックを設計する必要があります。

次のステップ

連続して行われる会話フローの実装

次の方法で共有

ユーザーへのプロアクティブな通知の送信

前提条件

プロアクティブサンプルについて

会話の参照を取得して格納する

プロアクティブなメッセージを送信する

ボットをテストする

追加情報

要件

設計上の考慮事項

プロアクティブターンについて

次のステップ

その他のリソース

次の方法で共有

ユーザーへのプロアクティブな通知の送信

前提条件

プロアクティブ サンプルについて

会話の参照を取得して格納する

プロアクティブなメッセージを送信する

ボットをテストする

追加情報

要件

設計上の考慮事項

プロアクティブ ターンについて

次のステップ

その他のリソース

プロアクティブサンプルについて

プロアクティブターンについて