プロアクティブメッセージ

[アーティクル]
06/23/2022

重要

このセクションのコードサンプルは、バージョン 4.6 以降のバージョンの Bot Framework SDK に基づいて作成されます。以前のバージョンのドキュメントを探している場合は、ドキュメントの Resources フォルダーの「bots - v3 SDK」セクションを参照してください。

プロアクティブメッセージは、ユーザーからの要求に応答していないボットによって送信されるメッセージです。これには、次のようなメッセージを含めることができます。

ウェルカムメッセージ
通知
予定されたメッセージ

重要

現在、ボットは Government Community Cloud (GCC) と GCC-High で利用できますが、国防総省 (DOD) では利用できません。

プロアクティブメッセージの場合、ボットは政府機関のクラウド環境に対して次のエンドポイントを使用する必要があります。

GCC: https://smba.infra.gcc.teams.microsoft.com/gcc。
GCCH: https://smba.infra.gov.teams.microsoft.us/gcch。

ボットがプロアクティブなメッセージをユーザー、グループチャット、またはチームに送信するには、ボットがメッセージを送信するためのアクセス権を持っている必要があります。グループチャットまたはチームの場合、ボットを含むアプリを最初にその場所にインストールする必要があります。必要に応じて、チーム内で Microsoft Graph を使用してアプリをプロアクティブにインストールしたり、アプリポリシーを使用して、テナント内のチームやユーザーにアプリをプッシュしたりすることができます。ユーザーの場合、自分でアプリをインストールしているか、アプリがインストールされているチームのメンバーである必要があります。

プロアクティブメッセージの送信は、通常のメッセージの送信とは異なります。返信に使うアクティブな turnContext はありません。また、メッセージを送信する前に会話を作成する必要があります。たとえば、新しい 1 対 1 のチャットやチャネル内の新しい会話スレッドなどです。プロアクティブメッセージングでは、新しいグループチャットやチーム内の新しいチャネルを作成することはできません。

プロアクティブメッセージを送信するには、次の手順に従います。

必要に応じて、ユーザー ID、チーム ID、またはチャネル ID を取得します。
必要に応じて会話を作成します。
会話ID を取得します。
メッセージを送信します。

サンプルセクションのコードスニペットは、1 対 1 の会話を作成するためのものです。 1 対 1 の会話とグループやチャネルの両方に向けた完全な作業サンプルへのリンクについては、「コードサンプル」を参照してください。

プロアクティブメッセージを効果的に使用するには、「プロアクティブメッセージングのベストプラクティス」を参照してください。特定のシナリオでは、Graph を使用してアプリをプロアクティブにインストールする必要があります。サンプルセクションのコードスニペットは、1 対 1 の会話を作成するためのものです。 1 対 1 の会話とグループやチャネルの両方に向けた完全な作業サンプルについては、「コードサンプル」を参照してください。

ユーザー ID、チーム ID、またはチャネル ID を取得する

チャネルで新しい会話や会話スレッドを作成するには、適切な ID がなくてはいけません。次のいずれかを使用して、この ID を受信または取得できます。

アプリが特定のコンテキストでインストールされると、onMembersAddedアクティビティを受信します。
アプリがインストールされているコンテキストに新しいユーザーが追加されると、onMembersAddedアクティビティを受信します。
アプリがインストールされているチームでチャネルのリストを取得することができます。
アプリがインストールされているチームでメンバーリストを取得することができます。
ボットが受け取るすべてのアクティビティには、必要な情報が含まれている必要があります。

情報を取得する方法に関わらず、tenantId、userId、channelId のいずれかを保存しないと、新たな会話が作成されません。 teamId を使って、チームの一般チャネルや既定のチャネルに新しい会話スレッドを作成することもできます。

userId は、ボット ID と特定のユーザーに固有です。ボット間で userId を再利用することはできません。 channelId はグローバルです。ただし、チャネルにプロアクティブメッセージを送信するには、お使いのボットがチームにインストールされている必要があります。

ユーザーまたはチャネル情報を取得したら、会話を作成する必要があります。

会話を作成する

会話が存在しない場合、または conversationId がわからない場合は、会話を作成する必要があります。会話は 1 回だけ作成し、conversationId 値または conversationReference オブジェクトを保存する必要があります。

アプリが初めてインストールされたときに会話を取得できます。会話が作成されたら、会話 ID を取得する必要があります。 conversationId は、会話更新イベントで使用できます。

conversationId がない場合は、Graph を使用してアプリをプロアクティブにインストールし、conversationId を取得できます。

会話 ID を取得する

メッセージを送信するには、conversationReference オブジェクトまたは conversationId か tenantId のいずれかを使用します。この ID は、会話を作成するか、そのコンテキストから送信されたアクティビティから保存することで取得することができます。参照用にこの ID を格納します。

適切なアドレス情報を取得したら、メッセージを送信できます。

メッセージを送信する

正しいアドレス情報を取得したので、メッセージを送信することができます。 SDK を使用している場合は、メソッドを使用し、直接 API 呼び出しを行う continueConversation conversationId tenantId 必要があります。メッセージを正常に送信するには、conversationParameters を正しく設定する必要があります。サンプルセクションを参照するか、コードサンプルセクションに記載されているサンプルの 1 つを使用してください。

プロアクティブなメッセージを送信したので、ユーザーとボットの間の情報交換を改善するために、プロアクティブなメッセージを送信する間、これらのベストプラクティスに従う必要があります。

ボットからプロアクティブなメッセージを送信する方法については、次のビデオを参照してください。

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

ユーザーにプロアクティブメッセージを送信するのは、ユーザーと効果的なコミュニケーションを行うのに役立ちます。ただし、ユーザーの観点からは、メッセージはプロンプトなしで表示されます。ウェルカムメッセージがある場合、アプリを操作するのは初めてです。この機能を使用し、このメッセージの目的を理解するためにユーザーに完全な情報を提供することが重要です。

ウェルカムメッセージ

プロアクティブメッセージングを使用してウェルカムメッセージをユーザーに送信する場合、ユーザーがメッセージを受信する理由についてのコンテキストはありません。また、ユーザーがアプリを操作するのはこれが初めてです。第一印象を良くするチャンスです。最高のウェルカムメッセージには、次のことが必ず含まれている必要があります。

ユーザがメッセージを受信する理由。メッセージを受信する理由が、ユーザーにとって明確でなければなりません。あなたのボットがチャネルにインストールされていて、すべてのユーザーにウェルカムメッセージを送信した場合は、どのチャネルにインストールされ、誰がインストールしたのかを通知する必要があります。
提示する内容。ユーザーは、アプリで何ができるか、そしてユーザーにどのような価値をもたらすことができるかを識別できなければなりません。
ユーザーが次にするべきこと。コマンドを試すか、アプリを操作するようにユーザーを招待します。ウェルカムメッセージが不十分だと、ユーザーがボットをブロックする可能性があります。要点を書いて、ウェルカムメッセージを明確にします。ウェルカムメッセージが目的の効果を発揮していない場合は、ウェルカムメッセージを繰り返します。

通知メッセージ

プロアクティブメッセージングを使用して通知を送信するには、通知に基づいて一般的なアクションを実行するための明確なパスがユーザーにあることを確認してください。ユーザーが通知を受け取った理由を明確に理解していることを確認してください。良好な通知メッセージには、通常、以下のものが含まれます。

何が起こったのでしょうか? 何が原因で通知が発生したのかを明確に示しています。
結果はどうでしたか? 通知を受け取るためにどのアイテムが更新されているかを明確にする必要があります。
誰が/何がトリガーになったのですか? 誰が、または何をして、通知を送信されることになったのか。
ユーザーが対応できることは何ですか? ユーザーが通知に基づいてアクションを取ることを容易にします。
ユーザーはどのようにオプトアウトできますか? ユーザーが追加の通知をオプトアウトするためのパスを提供する必要があります。

組織などの大規模なユーザーグループにメッセージを送信するには、 Graph を使用してアプリをプロアクティブにインストールします。

予定されたメッセージ

プロアクティブメッセージングを使用してスケジュールされたメッセージをユーザーに送信する場合は、タイムゾーンがユーザーのタイムゾーンに更新されていることを確認してください。これにより、メッセージが適切な時間にユーザーに確実に配信されます。スケジュールメッセージには通常、次のものが含まれます。

ユーザがメッセージを受信する理由。ユーザーがメッセージを受信する理由を簡単に理解できるようにします。
ユーザーは次に何ができますか? ユーザーは、メッセージの内容に基づいて必要なアクションを実行できます。

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

以前アプリをインストールしたり操作したりしていないユーザーにプロアクティブにメッセージを送信します。たとえば、社内コミュニケーターを使用して、組織全体にメッセージを送信する必要があるとします。この場合、Graph API を使用して、ユーザー向けにアプリをプロアクティブにインストールできます。インストール時にアプリが受け取る conversationUpdate イベントから必要な値をキャッシュします。

組織のアプリカタログまたは Teams アプリストアにあるアプリのみインストールできます。

Graph ドキュメントの「ユーザー向けアプリのインストール」および「Graph を使用した Teams でのプロアクティブボットのインストールとメッセージング」を参照してください。 GitHub プラットフォームには Microsoft .NET framework サンプルもあります。

サンプル

次のコードは、プロアクティブなメッセージを送信する方法を示しています。

[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)
    {
        // If you encounter permission-related errors when sending this message, see
        // https://aka.ms/BotTrustServiceUrl
        await turnContext.SendActivityAsync("proactive hello");
    }
}


async messageAllMembersAsync(context) {
    const members = await this.getPagedMembers(context);

    members.forEach(async (teamMember) => {
        const message = MessageFactory.text('Hello ${ teamMember.givenName } ${ teamMember.surname }. I\'m a Teams conversation bot.');

        var ref = TurnContext.getConversationReference(context.activity);
        ref.user = teamMember;

        await context.adapter.createConversation(ref,
            async (t1) => {
                const ref2 = TurnContext.getConversationReference(t1.activity);
                await t1.adapter.continueConversation(ref2, async (t2) => {
                    await t2.sendActivity(message);
                });
            });
    });

    await context.sendActivity(MessageFactory.text('All messages have been sent.'));
}

async def _message_all_members(self, turn_context: TurnContext):
    team_members = await self._get_paged_members(turn_context)

    for member in team_members:
        conversation_reference = TurnContext.get_conversation_reference(
            turn_context.activity
        )

        conversation_parameters = ConversationParameters(
            is_group=False,
            bot=turn_context.activity.recipient,
            members=[member],
            tenant_id=turn_context.activity.conversation.tenant_id,
        )

        async def get_ref(tc1):
            conversation_reference_inner = TurnContext.get_conversation_reference(
                tc1.activity
            )
            return await tc1.adapter.continue_conversation(
                conversation_reference_inner, send_message, self._app_id
            )

        async def send_message(tc2: TurnContext):
            return await tc2.send_activity(
                f"Hello {member.name}. I'm a Teams conversation bot."
            )

        await turn_context.adapter.create_conversation(
            conversation_reference, get_ref, conversation_parameters
        )

    await turn_context.send_activity(
        MessageFactory.text("All messages have been sent")
    )

POST /v3/conversations
{
  "bot": {
    "id": "28:10j12ou0d812-2o1098-c1mjojzldxcj-1098028n ",
    "name": "The Bot"
  },
  "members": [
    {
      "id": "29:012d20j1cjo20211"
    }
  ],
  "channelData": {
    "tenant": {
      "id": "197231joe-1209j01821-012kdjoj"
    }
  }
}

ユーザー ID とテナント ID を入力する必要があります。呼び出しに成功した場合、API は以下の応答オブジェクトを返します。

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

コードサンプル

次の表は、基本的な会話フローを Teams アプリケーションに組み込んだ簡単なコードサンプルと、Teams のチャネルで新しい会話スレッドを作成する方法を示しています。

サンプルの名前	説明	.NET	Node.js	Python
Teams での会話の基本	1 対 1 のプロアクティブメッセージの送信など、Teams での会話の基本をご紹介します。	表示	表示	表示
チャネルで新しいスレッドを開始する	チャネルで新しいスレッドを作成する方法をご紹介します。	表示	表示	表示
アプリのプロアクティブインストールとプロアクティブ通知の送信	このサンプルは、ユーザー向けのアプリのプロアクティブなインストールを使用し、Microsoft Graph API を呼び出してプロアクティブな通知を送信する方法を示しています。	表示	表示

追加のコードサンプル

Teams のプロアクティブメッセージングコードサンプル

ステップバイステップのガイド

ボットからプロアクティブなメッセージを送信するのに役立つステップバイステップガイドに従ってください。

次のステップ

ボットメッセージの書式を設定する

プロアクティブ メッセージ