プロアクティブ インストール メッセージを送信する

  • [アーティクル]

Teams でのプロアクティブ メッセージング

プロアクティブ メッセージは、ユーザーとの会話を開始するためにボットによって開始されます。 ウェルカム メッセージの送信、アンケートや投票の実施、組織全体の通知のブロードキャストなど、さまざまな目的に対応しています。 Teams のプロアクティブ メッセージは、アドホックまたはダイアログ ベースの会話として配信できます。

メッセージの種類 説明
アドホック プロアクティブ メッセージ ボットは、会話フローを中断することなくメッセージを挿入します。
ダイアログ ベースのプロアクティブ メッセージ ボットは新しいダイアログ スレッドを作成し、会話を制御し、プロアクティブ メッセージを配信し、閉じて、前のダイアログに制御を返します。

Teams でのプロアクティブ アプリのインストール

ボットがユーザーに事前にメッセージを送信するには、個人用アプリとして、またはユーザーがメンバーであるチームにインストールする必要があります。 場合によっては、アプリをインストールしていない、または以前に操作していないユーザーに事前にメッセージを送信する必要があります。 たとえば、organizationのすべてのユーザーに重要な情報を伝える必要がある場合は、Microsoft Graph APIを使用して、ユーザー用にボットを事前にインストールできます。

アクセス許可

Microsoft Graph teamsAppInstallation リソースの種類のアクセス許可は、Microsoft Teams プラットフォーム内のすべてのユーザー (個人) またはチーム (チャネル) スコープに対するアプリのインストール ライフサイクルを管理するのに役立ちます。

アプリケーションのアクセス許可 説明
TeamsAppInstallation.ReadWriteSelfForUser.All Teams アプリは、事前のサインインや使用なしで、任意のユーザーの読み取り、インストール、アップグレード、アンインストールを行うことができます。
TeamsAppInstallation.ReadWriteSelfForTeam.All ユーザーがサインインしていない状態で、任意のチームに対して Teams アプリが自分自身を読み取り、インストール、アップグレード、アンインストールすることを許可します。

これらのアクセス許可を使用するには、次の値を持つ webApplicationInfo キーをアプリ マニフェスト (以前は Teams アプリ マニフェスト) に追加する必要があります。

  • id: Microsoft Entra アプリ ID。
  • リソース: アプリのリソース URL。

注:

  • インストールは他のユーザー向けであるため、ボットにはアプリケーションが必要であり、ユーザーが委任したアクセス許可は必要ありません。

  • Microsoft Entraテナント管理者は、アプリケーションに対するアクセス許可を明示的に付与する必要があります。 アプリケーションにアクセス許可が付与されると、Microsoft Entra テナントのすべてのメンバーが付与されたアクセス許可を取得します。

プロアクティブなボットをインストールしてメッセージングを有効にする

重要

Microsoft Graph では、organizationのアプリ ストアまたは Microsoft Teams ストアに発行されたアプリのみをインストールできます。

Teams 用のプロアクティブ メッセージング ボットを作成して発行する

作業を開始するには、organizationのアプリ ストアまたは Teams ストアにあるプロアクティブ メッセージング機能を備えた Teams用のボットが必要です。

ヒント

運用環境対応の Company Communicator アプリ テンプレートは、ブロードキャスト メッセージングを許可し、プロアクティブなボット アプリケーションを構築するための優れたスタートです。

アプリの teamsAppId を入手する

teamsAppId は次の方法で取得できます。

  • 組織のアプリ カタログから:

    Microsoft Graph ページ リファレンス:teamsApp リソースの種類

    HTTP GET リクエスト:

    GET https://graph.microsoft.com/v1.0/appCatalogs/teamsApps?$filter=externalId eq '{IdFromManifest}'

    リクエストは、アプリのカタログで生成されたアプリ ID である teamsApp オブジェクト id を返す必要があります。 これは、アプリ マニフェストで指定した ID とは異なります。

    {
  "value": [
    {
      "id": "b1c5353a-7aca-41b3-830f-27d5218fe0e5",
      "externalId": "f31b1263-ba99-435a-a679-911d24850d7c",
      "name": "Test App",
      "version": "1.0.1",
      "distributionMethod": "Organization"
    }
  ]
}

    注:

    アプリが Teams ストアにある場合、 は と同じIdFromManifestであり、teamsAppIdこの場合は をexternalId使用しないでください。

  • 個人用スコープ内のユーザーに対してアプリが既にアップロードされている場合:

    Microsoft Graph ページ リファレンス:ユーザー用にインストールされたアプリの一覧表示

    HTTP GET リクエスト:

    GET https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps?$expand=teamsApp&$filter=teamsApp/externalId eq '{IdFromManifest}'

  • チーム スコープ内のチャネルに対してアプリが既にアップロードされている場合:

    Microsoft Graph ページ リファレンス:チーム内のアプリを一覧表示する

    HTTP GET リクエスト:

    GET https://graph.microsoft.com/v1.0/teams/{team-id}/installedApps?$expand=teamsApp&$filter=teamsApp/externalId eq '{IdFromManifest}'

    ヒント

    結果の一覧を絞り込むには、 teamsApp オブジェクトの任意のフィールドをフィルター処理できます。

メッセージ受信者に対してボットが現在インストールされているかどうかを確認する

メッセージ受信者に対してボットが現在インストールされているかどうかを確認するには、次のようにします。

Microsoft Graph ページ リファレンス:ユーザー用にインストールされたアプリの一覧表示

HTTP GET リクエスト:

GET https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps?$expand=teamsApp&$filter=teamsApp/id eq '{teamsAppId}'

要求は次を返します。

  • アプリがインストールされていない場合は空の配列。
  • アプリがインストールされている場合は、単一 の teamsAppInstallation オブジェクトを持つ配列。

サイトにアプリ パーツをインストールします。

アプリは次のようにインストールできます。

Microsoft Graph ページ リファレンス:ユーザー用アプリのインストール

HTTP POST リクエスト

POST https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps
Content-Type: application/json

{
   "teamsApp@odata.bind" : "https://graph.microsoft.com/v1.0/appCatalogs/teamsApps/{teamsAppId}"
}

ユーザーが Microsoft Teams を実行している場合は、アプリのインストールが直ちに行われます。 インストールされているアプリを表示するには、再起動が必要になる場合があります。

会話 chatId を取得する

アプリがユーザー用にインストールされると、ボットはプロアクティブ メッセージをconversationUpdate送信するために必要な情報を含むイベント通知を受け取ります。

Microsoft Graph ページ リファレンス:チャットを取得する

  1. アプリの {teamsAppInstallationId} が必要です。 持っていない場合は、次を使用します。

    HTTP GET リクエスト:

    GET https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps?$expand=teamsApp&$filter=teamsApp/id eq '{teamsAppId}'

    応答の id プロパティは teamsAppInstallationId です。

  2. 次の要求を行って、chatId をフェッチします。

    HTTP GET 要求 (アクセス許可):TeamsAppInstallation.ReadWriteSelfForUser.All

    GET https://graph.microsoft.com/v1.0/users/{user-id}/teamwork/installedApps/{teamsAppInstallationId}/chat

    応答の id プロパティは chatId です。

    次のリクエストで chatId を取得することもできますが、より広範な Chat.Read.All 権限が必要です。

    HTTP GET 要求 (アクセス許可):Chat.Read.All

    GET https://graph.microsoft.com/v1.0/users/{user-id}/chats?$filter=installedApps/any(a:a/teamsApp/id eq '{teamsAppId}')

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

ボットは、ユーザーまたはチームに対してボットが追加され、すべてのユーザー情報を受信した後に プロアクティブ メッセージを送信 できます。

コード スニペット

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

public async Task<int> SendNotificationToAllUsersAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
   int msgSentCount = 0;

   // Send notification to all the members.
   foreach (var conversationReference in _conversationReferences.Values)
   {
       await turnContext.Adapter.ContinueConversationAsync(_configuration["MicrosoftAppId"], conversationReference, BotCallback, cancellationToken);
       msgSentCount++;
   }

   return msgSentCount;
}

private async Task BotCallback(ITurnContext turnContext, CancellationToken cancellationToken)
{
    // Sends an activity to the sender of the incoming activity.
   await turnContext.SendActivityAsync("Proactive hello.");
}

コード サンプル

サンプルの名前 説明 .NET Node.js
アプリのプロアクティブ インストールとプロアクティブ通知の送信 このサンプルは、ユーザー向けのアプリのプロアクティブなインストールを使用し、Microsoft Graph API を呼び出してプロアクティブな通知を送信する方法を示しています。 表示 表示

追加のコード サンプル

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

関連項目