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

[アーティクル]
11/14/2024

重要

このセクションのコードサンプルは、バージョン 4.6 以降のバージョンの Bot Framework SDK に基づいています。以前のバージョンのドキュメントをお探しの場合は、ドキュメントのレガシ SDK フォルダーのボット - v3 SDK セクションを参照してください。

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

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

重要

プロアクティブメッセージを送信するには、JavaScript または受信 Webhook 通知サンプルを使用して通知ボットを構築することをお勧めします。開始するには、 Teams Toolkit の探索をダウンロードします。詳細については、「 Teams Toolkit ドキュメント」を参照してください。
ボットは、Government Community Cloud (GCC)、GCC-High、および国防総省 (DOD) 環境で使用できます。プロアクティブメッセージの場合、ボットは政府クラウド環境に次のエンドポイントを使用する必要があります。
- GCC: https://smba.infra.gcc.teams.microsoft.com/teams
- GCCH: https://smba.infra.gov.teams.microsoft.us/teams
-国防総省： https://smba.infra.dod.teams.microsoft.us/teams

ユーザー、グループチャット、またはチームにプロアクティブメッセージを送信するには、ボットがメッセージを送信するために必要なアクセス権を持っている必要があります。グループチャットまたはチームの場合、ボットを含むアプリを最初にその場所にインストールする必要があります。

必要に応じて、チーム内の Microsoft Graph を使用してアプリを事前にインストールすることも、カスタムアプリポリシーを使用してチームやorganizationのユーザーにアプリをインストールすることもできます。特定のシナリオでは、Graph を使用してアプリをプロアクティブにインストールする必要があります。ユーザーがプロアクティブメッセージを受信するには、ユーザーのアプリをインストールするか、ユーザーをアプリがインストールされているチームの一部にします。

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

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

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

サンプルセクションのコードスニペットは、1 対 1 の会話を作成することです。 1 対 1 の会話とグループメッセージまたはチャネルメッセージの両方のサンプルへのリンクについては、コードサンプルを参照してください。プロアクティブメッセージを効果的に使用するには、プロアクティブメッセージングのベストプラクティスに関するページを参照してください。

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

チャネル内のユーザーまたはスレッドとの新しい会話を作成でき、正しい ID が必要です。この ID は、次のいずれかの方法で受信または取得できます。

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

情報の取得方法に関係なく、 tenantId を格納し、 userIdまたは channelId を格納して新しい会話を作成します。 teamId を使って、チームの一般チャネルや既定のチャネルに新しい会話スレッドを作成することもできます。プロアクティブメッセージをチャネルに送信する前に、ボットがチームにインストールされていることを確認します。

aadObjectIdはユーザーに固有であり、graph API を使用して取得して、個人用チャットで新しい会話を作成できます。プロアクティブメッセージを送信する前に、ボットが個人用スコープにインストールされていることを確認します。 aadObjectIdを使用してプロアクティブメッセージを送信するときに、ボットが個人用スコープにインストールされていない場合、ボットはメッセージと共に403 エラーForbiddenOperationException返します。
userId は、ボット ID と特定のユーザーに固有です。ボット間で userId を再利用することはできません。
channelId はグローバルです。

ユーザーまたはチャネルの情報を取得した後、会話を作成します。

注:

aadObjectIdを使用したプロアクティブメッセージの送信は、個人用スコープでのみサポートされます。

会話を作成する

会話が存在しない場合、または conversationIdがわからない場合は作成できます。会話を 1 回だけ作成し、 conversationId 値または conversationReference オブジェクトを格納します。

会話を作成するには、aadObjectIdまたはuserId、tenantId、serviceUrlが必要です。

serviceUrlの場合は、フローまたはグローバルサービス URL の 1 つをトリガーする受信アクティビティの値を使用します。プロアクティブなシナリオをトリガーする受信アクティビティから serviceUrl を使用できない場合は、次のグローバル URL エンドポイントを使用します。

公共： https://smba.trafficmanager.net/teams/
GCC: https://smba.infra.gcc.teams.microsoft.com/teams
GCCH: https://smba.infra.gov.teams.microsoft.us/teams
国防総省： https://smba.infra.dod.teams.microsoft.us/teams

コードサンプルについては、サンプルの呼び出しCreateConversationAsyncを参照してください。

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

会話 ID は、マルチテナント環境でも、特定のチャネル内のボットごとに一意です。この ID を使用すると、ボットのメッセージが適切なチャネルに転送され、同じ組織内または異なる組織内の他のボットまたはチャネルで中断されることはありません。

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

会話 ID を取得する

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

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

メッセージを送信する

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

注:

Teams では、電子メールまたはユーザープリンシパル名 (UPN) を使用したプロアクティブメッセージの送信はサポートされていません。

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

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

ボットをブロック、ミュート、またはアンインストールしたユーザーを理解する

開発者は、レポートを作成して、ボットをブロック、ミュート、またはアンインストールしたorganization内のユーザーを把握できます。この情報は、organizationの管理者が組織全体のメッセージをブロードキャストしたり、アプリの使用を促進したりするのに役立つ場合があります。

Teams を使用すると、ボットにプロアクティブメッセージを送信して、ユーザーがボットをブロックまたはアンインストールしたかどうかを確認できます。ボットがブロックまたはアンインストールされた場合、Teams はsubCode: MessageWritesBlockedを含む403応答コードを返します。この応答は、ボットによって送信されたメッセージがユーザーに配信されていないことを示します。

応答コードはユーザーごとに送信され、ユーザーの ID が含まれます。各ユーザーの応答コードを ID と共にコンパイルして、ボットをブロックしたすべてのユーザーのレポートを作成できます。

403 応答コードの例を次に示します。


HTTP/1.1 403 Forbidden

Cache-Control: no-store, must-revalidate, no-cache

 Pragma: no-cache

 Content-Length: 196

 Content-Type: application/json; charset=utf-8

 Server: Microsoft-HTTPAPI/2.0

 Strict-Transport-Security: max-age=31536000; includeSubDomains

 MS-CV: NXZpLk030UGsuHjPdwyhLw.5.0

 ContextId: tcid=0,server=msgapi-canary-eus2-0,cv=NXZpLk030UGsuHjPdwyhLw.5.0

 Date: Tue, 29 Mar 2022 17:34:33 GMT

{"errorCode":209,"message":"{\r\n  \"subCode\": \"MessageWritesBlocked\",\r\n  \"details\": \"Thread is blocked from message writes.\",\r\n  \"errorCode\": null,\r\n  \"errorSubCode\": null\r\n}"}

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

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

ウェルカムメッセージ

プロアクティブメッセージングを使用してウェルカムメッセージをユーザーに送信する場合、ユーザーがメッセージを受信する理由のコンテキストはありません。また、これはユーザーとアプリの最初の対話です。第一印象を良くするチャンスです。優れたユーザーエクスペリエンスにより、アプリの導入が向上します。ウェルカムメッセージが低いと、ユーザーがアプリをブロックする可能性があります。明確なウェルカムメッセージを記述し、目的の効果がない場合はウェルカムメッセージを反復処理します。

適切なウェルカムメッセージには、次のものが含まれます。

メッセージの理由 - ユーザーがメッセージを受信する理由を明確にする必要があります。あなたのボットがチャネルにインストールされていて、すべてのユーザーにウェルカムメッセージを送信した場合は、どのチャネルにインストールされ、誰がインストールしたのかを通知する必要があります。
オファー - ユーザーは、アプリで何ができるか、どのような価値をもたらすかを識別できる必要があります。
次の手順 - ユーザーは次の手順を理解する必要があります。たとえば、コマンドを試したり、アプリを操作したりするようにユーザーを招待します。

通知メッセージ

プロアクティブメッセージングを使用して通知を送信するには、通知に基づいて一般的なアクションを実行するための明確なパスがユーザーにあることを確認してください。タブアプリでユーザーアクションが必要な場合は、ボットではなくアクティビティフィード通知を使用します。ユーザーが通知を受け取った理由を明確に理解していることを確認してください。適切な通知メッセージには、次のものが含まれます。

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

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

通知のみのボットによって送信されたプロアクティブメッセージを更新または削除するには:

プロアクティブメッセージの送信時にメッセージ ID または会話参照を格納して、送信されたメッセージを追跡します。
元のメッセージを更新または削除するには、 UpdateActivityAsync または DeleteActivityAsync メソッドを使用します。

予定されたメッセージ

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

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

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

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

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

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

例

REST API を使用して新しい会話を作成する前に、認証とベアラートークンがあることを確認します。異なるコンテキストで会話を作成するための REST API を次に示します。

1 対 1 のチャットで会話を作成するための REST API。
チャネルで会話を作成するための REST API。
メッセージ交換のメッセージを更新する REST API: 会話内の既存のアクティビティを更新するには、要求エンドポイントに conversationId と activityId を含めます。このシナリオを完了するには、元の POST 呼び出しによって返されたアクティビティ ID をキャッシュする必要があります。
```
PUT {Service URL of your bot}/v3/conversations/{conversationId}/activities/{activityId}
```
```
{
    "type": "message",
    "text": "This message has been updated"
}
```
会話内の既存のアクティビティを更新するには、リクエストエンドポイントに conversationId と activityId を含めます。このシナリオを完了するには、元の事後呼び出しによって返された activity ID をキャッシュする必要があります。呼び出しに成功した場合、API は以下の応答オブジェクトを返します。
```
{
    "id": "{{activityID}}"
}
```

サンプル

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

[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)
        {
            var newReference = new ConversationReference()
            {
                Bot = new ChannelAccount()
                {
                    Id = conversationReference.Bot.Id
                },
                Conversation = new ConversationAccount()
                {
                    Id = conversationReference.Conversation.Id
                },
                ServiceUrl = conversationReference.ServiceUrl,
            };

            // Sends a proactive message from the bot to a conversation.
            await ((BotAdapter)_adapter).ContinueConversationAsync(_appId, newReference, 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://learn.microsoft.com/en-us/azure/bot-service/bot-builder-howto-proactive-message?view=azure-bot-service-4.0&tabs=csharp#avoiding-401-unauthorized-errors
        // Sends an activity to the sender of the incoming activity.
        await turnContext.SendActivityAsync("proactive hello");
    }
}

会話参照の作成を示すコードスニペットの例。

 var newReference = new ConversationReference()
        {
            Bot = new ChannelAccount()
            {
                Id = conversationReference.Bot.Id
            },
            Conversation = new ConversationAccount()
            {
                Id = conversationReference.Conversation.Id
            },
            ServiceUrl = conversationReference.ServiceUrl,
        };


async SendNotificationToAllUsersAsync(context) {
     const TeamMembers = await TeamsInfo.getPagedMembers(context);
     let Sent_msg_Cout = TeamMembers.members.length;
     TeamMembers.members.map(async member => {
         const ref = TurnContext.getConversationReference(context.activity);
         ref.user = member;
         await context.adapter.createConversation(ref, async (context) => {
             const ref = TurnContext.getConversationReference(context.activity);
             await context.adapter.continueConversation(ref, async (context) => {
                 await context.sendActivity("Proactive hello.");
             });
         });
     });
    await context.sendActivity(MessageFactory.text("Message sent:" + Sent_msg_Cout));
}

# Send message to all members.
async def _message_all_members(self, turn_context: TurnContext):
    team_members = await self._get_paged_members(turn_context)

    for member in team_members:
        # A conversation reference for the conversation that contains this activity.
        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
        )

    # Sends an activity to the sender of the incoming activity.
    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 での会話の基本	このサンプルアプリでは、ボットフレームワーク v4 で使用できるさまざまなボット会話イベントを個人用とチームのスコープで使用する方法を示します。	表示	表示	表示	表示
チャネルで新しいスレッドを開始する	このサンプルでは、Bot Framework v4 を使用して特定のチームのチャネルでスレッドを開始する方法を示します。	表示	表示	表示	表示
アプリのプロアクティブインストールとプロアクティブ通知の送信	このサンプルは、ユーザー向けのアプリのプロアクティブなインストールを使用し、Microsoft Graph API を呼び出してプロアクティブな通知を送信する方法を示しています。	表示	表示	該当なし	表示
プロアクティブメッセージング	これは、Bots を使用してプロアクティブなアラームメッセージを送信するために、ユーザーの会話参照情報を保存する方法を示すサンプルです。	表示	表示	該当なし

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

次のステップ

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

次の方法で共有

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

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

会話を作成する

会話 ID を取得する

メッセージを送信する

ボットをブロック、ミュート、またはアンインストールしたユーザーを理解する

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

ウェルカムメッセージ

通知メッセージ

予定されたメッセージ

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

例

サンプル

コードサンプル

次のステップ

関連項目

その他のリソース

次の方法で共有

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

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

会話を作成する

会話 ID を取得する

メッセージを送信する

ボットをブロック、ミュート、またはアンインストールしたユーザーを理解する

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

ウェルカム メッセージ

通知メッセージ

予定されたメッセージ

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

例

サンプル

コード サンプル

次のステップ

関連項目

その他のリソース

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

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

ウェルカムメッセージ

コードサンプル