Microsoft Teams の bot を使用した予防的なメッセージングProactive messaging using a bot in Microsoft Teams

事前メッセージとは、ユーザーが会話を開始せずに、Microsoft Teams ユーザーに送信されるメッセージのことです。A proactive message is a message sent to a Microsoft Teams user without a user initiating the conversation. Microsoft Teams のカスタムアプリは、ボットを使用して、積極的なメッセージをユーザーに送信できます。Custom apps in Microsoft Teams can send proactive messages to users using a bot. ただし、そのためには、bot を個人用アプリとしてインストールするか、またはユーザーがメンバーになっているチームにインストールする必要があります。However, to do so, the bot needs to be installed either as a personal app, or in a team that the user is a member of. この要件は、Teams アプリがインストールされているかもしれませんが、ユーザーのグループに積極的にメッセージを表示する必要があるシナリオでは、この要件を超える可能性があります。This requirement can be prohibitive in scenarios where you need to proactively message a group of users that might or might not have the Teams app installed.

この記事では、microsoft Graph を Microsoft Teams アプリと組み合わせてユーザー用のアプリをインストールした後、Teams アプリを使用して、アプリを手動でインストールすることなく、それらのユーザーに対して積極的なメッセージを送信する方法について説明します。This article outlines how you can combine Microsoft Graph with a Microsoft Teams app to install the app for your users and then use your Teams app to send them a proactive message, without requiring them to manually install the app.

大まかにするには、次のことを行う必要があります。At a high level, you'll need to:

Teams アプリと bot を作成するCreate your Teams app and bot

メッセージを送信できるボットを備えた Microsoft Teams アプリをまだ持っていない場合は、作成する必要があります。If you do not already have a Microsoft Teams app with a bot that can send the message, you'll need to create one. Teams プラットフォームのドキュメントの「 teams アプリに bot を追加する 」を参照してください。See Add bots to Teams apps in the Teams platform documentation. 予防的なメッセージングのボットを作成する方法の詳細については、「 bot 向けの予防的なメッセージング」を参照してください。For specifics about creating a bot for proactive messaging, see Proactive messaging for bots.

アプリの開始点として、 会社の Communicator アプリテンプレート を使用することもできます。You can also use the Company Communicator app template as a good starting point for your app. このアプリテンプレートは、会社全体のメッセージを作成、スケジュール、および配布できる、運用に対応した Microsoft Teams アプリです。This app template is a production-ready Microsoft Teams app capable of creating, scheduling, and distributing company-wide messages.

アプリを作成するときには、アプリケーションマニフェストで使用しているをメモしておいてください。これは、 id 後の手順でアプリをインストールするために必要になります。When creating your app, make sure that you take note of the id you use in your application manifest; you'll need it to install the app in a subsequent step.

大規模な組織でこれを実行している場合は、ボットからのウェルカムメッセージが調整される可能性があります。If you're doing this for a large organization, the welcome messages from your bot might get throttled. 可能な場合は、バッチ処理でインストールを実行し、ボットにバックオフ機能を実装します。If possible, perform the installations in batches, and implement back-off functionality in your bot. 詳細については、「 処理率の制限」を参照してください。For details, see handling rate limiting.

テナントのアプリカタログにアプリを展開するDeploy your app to your tenant app catalog

Microsoft Graph では、テナントのアプリカタログに追加されたアプリ、または公開されている Microsoft Teams アプリストアで利用できるアプリのみをインストールできます。Microsoft Graph can only install apps that have been added to your tenant app catalog, or are available in the public Microsoft Teams app store. 新しいアプリで作業している場合は、 テナントのアプリカタログであることを確認する必要があります。If you're working with a new app, you'll need to make sure it is tenant app catalog.

ユーザー用のアプリをインストールするInstall the app for your users

Teams アプリをユーザー向けにインストールするには、まず、Microsoft Graph アプリケーションに適切なアクセス許可があることを確認する必要があります。そのためには、Teams アプリをインストールするのには、ユーザーによる書き込みを必要とします。To install the Teams app for your users, you'll first need to ensure that your Microsoft Graph application has the right permissions – you'll need User.ReadWrite.All or Directory.ReadWrite.All to install the Teams app. これ以降の手順についても説明します。You'll also need Chat.Read.All for a subsequent step. 両方のアクセス許可に管理者の同意が必要であり、アプリを自分以外のユーザーにインストールするため、ユーザーが委任するのではなく、アプリケーションのアクセス許可を使用する必要があります。Both permissions will require admin consent, and you'll need to use application permissions rather than user delegated because you will be installing apps to users other than yourself.

アプリが既にインストールされているかどうかを確認するCheck to see if the app is already installed

最初に、次の例に示すように、Teams アプリがインストールするユーザーに対して既にインストールされているかどうかを確認します。First, you'll want to check to see if your Teams app is already installed for the users you want to install it from, as shown in the example.

GET /users/{user-id}/teamwork/installedApps?$expand=teamsAppDefinition&$filter=teamsAppDefinition/teamsAppId eq '{teamsAppid}'

{teamsAppId}は、以前に作成した id Teams アプリのマニフェストのです。Where {teamsAppId} is the id in the Teams app manifest that you made note of previously. これは、Microsoft Graph の通話とは異なる場合があることに注意 appid して botId ください。Note that this might be different from your appid for Microsoft Graph calls, and from your botId. ユーザー用のアプリを手動でインストールして、そのユーザーに対して呼び出しをテストして、正しい値が得られていることを確認すると便利な場合があり id ます。You might find it useful to manually install the app for a user and test the call against that user to ensure that you've got the correct id value.

アプリがインストールされていない場合は空の配列、または既にインストールされている場合は1つの teamsAppInstallation を持つ配列が返されます。The call will return an empty array if the app is not installed, or an array with a single teamsAppInstallation if it is already installed.

アプリをインストールするInstall the app

そのユーザーに対してアプリがまだインストールされていない場合は、次の例に示すようにインストールできます。If the app is not already installed for that user, you can then install it as shown in the following example.

POST /users/{user-id}/teamwork/installedApps
   "teamsApp@odata.bind" : "{teamsAppid}"

詳細については、「 Install app for user」を参照してください。For more information, see Install app for user.

ユーザーが Microsoft Teams を実行している場合は、アプリのインストールがすぐに表示されないかもしれません。インストールを確認するには、アプリを再起動する必要があるかもしれません。If the user has Microsoft Teams running, they might or might not see the app installation right away – they might need to restart the app to see the installation.

チャットスレッド ID を取得するGet the chat thread ID

アプリがユーザーに対してインストールされると、bot は、 conversationUpdate 事前メッセージを送信するために必要な情報を含むイベントを取得します。When the app is installed for the user, the bot will get a conversationUpdate event that will contain the necessary information for it to send the proactive message. 詳細については、「 Bot イベント」を参照してください。For more information, see Bot events.

を紛失した場合は、次のよう chatThreadId に呼び出して検索することができます。If you lose the chatThreadId, you can find it again by calling:

GET /users/{user-id}/chats?$filter=installedApps/any(a:a/teamsApp/id eq '{teamsAppid}')

結果の id プロパティは、CHATTHREAD id です。The id property of the result is the chatThread ID.

メッセージを送信するSending the message

Bot が必要な情報を持っているので、 予防的なメッセージを送信することができます。Now that your bot has the necessary information, you can send a proactive message.

C# のサンプルC# sample

「」を参照してください (分岐に注意してください)。See (note the branch). 興味深いコードは InstallAppToAllUsers()GraphService.cs内にあります。Interesting code is in InstallAppToAllUsers() in GraphService.cs.