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

[アーティクル]
08/02/2022

適用対象: SDK v4

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

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

注意

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

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

前提条件

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

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

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

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

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

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

この通知エンドポイントでの GET 要求に応答して、アプリはアダプターの continue conversation メソッドを呼び出します。これは、 プロセスアクティビティ メソッドと同様に動作します。 continue conversation メソッド:

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

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

proactive bot

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

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 プロパティが含まれています。会話には、会話に参加しているユーザーを一覧表示する ユーザー プロパティと、現在のアクティビティへの応答が送信される場所を示す サービス URL プロパティが含まれます。プロアクティブメッセージをユーザーに送信するには、有効な会話の参照が必要です。 (Teams チャネルの場合、サービス URL はリージョン化されたサーバーにマップされます)。

注意

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

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

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

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

注意

各チャネルでは安定したサービス 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 のパラメーターは、このターンのボットのターンハンドラーとして機能する関数です。

// Listen for incoming notifications and send proactive messages to users.
server.get('/api/notify', async (req, res) => {
    for (const conversationReference of Object.values(conversationReferences)) {
        await adapter.continueConversationAsync(process.env.MicrosoftAppId, conversationReference, async context => {
            await context.sendActivity('proactive hello');
        });
    }

    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 を使用して、プロアクティブメッセージを送信します。

# Send a message to all conversation members.
# This uses the shared Dictionary that the Bot adds conversation references to.
async def _send_proactive_message():
    for conversation_reference in CONVERSATION_REFERENCES.values():
        await ADAPTER.continue_conversation(
            conversation_reference,
            lambda turn_context: turn_context.send_activity("proactive hello"),
            APP_ID,
        )

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

ボットをテストする

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

次のステップ

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

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

前提条件

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

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

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

ボットをテストする

関連情報

要件

設計上の考慮事項

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

次のステップ

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

前提条件

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

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

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

ボットをテストする

関連情報

要件

設計上の考慮事項

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

次のステップ

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

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

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