Microsoft Teams のユーザーにアクティビティ フィード通知を送信する

Microsoft Teams アクティビティ フィードは、ユーザーに変更を通知して、注意が必要な項目をトリアージできるようにします。 Teams のアクティビティ フィード通知には、次の機能が含まれます。

  • ユーザーを Tab アプリにシームレスに取り込み、Teams アクティビティ ウィンドウからアプリに追加のユーザー エンゲージメントを提供する Teams とのネイティブ統合。
  • ポップアップとサウンドを含む Teams デスクトップクライアントとモバイル クライアントのオペレーティング システム通知。
  • ユーザーに多かれ少なかれプレビュー コンテンツを表示できるカスタマイズ可能な通知コンテンツ。
  • タブ、個人用アプリ、ボット メッセージ、またはアダプティブ カードを通知にディープ リンクして、アプリとのユーザー エンゲージメントを高める機能。
  • ユーザーのグループへのバッチ通知など、複数の受信者にアクティビティ フィード通知を送信する機能。

Microsoft Graph のアクティビティ フィード通知 API を使用して、この機能をアプリに拡張できます。 これにより、豊富なエクスペリエンスを提供し、ユーザーが使用するツールとワークフローの変更を最新の状態に保つことができます。

Microsoft Graph のアクティビティ フィード通知 API では、次のユース ケースが有効になります。

  • ニュース - 新しい割り当てや新しい投稿など、最新の情報でユーザーを最新の状態に保ちます。
  • コラボレーション - 他のユーザーがファイルを共有したり、@ でコメントにメンションしたりしたときに、通知バナーにプレビューを表示します。
  • アラーム - イベントまたはタスクに関する通知をユーザーに送信します。
  • アラート - 期限が過ぎた場合や優先度の高い作業項目など、緊急または即時の注意が必要な通知を送信します。

アクティビティ フィード通知を使用して、次の操作を行うことができます。

  • 注意が必要なカスタマイズされたコンテンツについて個人に通知します。
  • タブ アプリまたは URL にリッチ コンテンツを表示します。
  • 複雑なユーザー操作をサポートします。
  • 通知を開始したユーザーから委任された通知を送信します。

Teams は、通知のローカライズを処理します。

アクティビティ フィード通知のコンポーネント

Teams のアクティビティ フィード通知は、次の図に示すように、複数の情報がまとめて表示されます。

アクター、理由、タイム スタンプ、プレビュー、トピックなど、アクティビティ フィード通知のコンポーネントを示す画像。

次の表では、コンポーネントについて説明します。

コンポーネント 説明
アバター アクティビティを開始したユーザーを表示します。
アクティビティの種類またはアプリ アイコン アクティビティの種類。 アプリ通知の場合、行アイコンはアプリ アイコンに置き換えられます。
タイトル: アクター + 理由 アクター は、アクティビティを開始したユーザーまたはアプリの名前です。 理由 はアクティビティについて説明します。
Timestamp アクティビティが発生したタイミングを示します。
テキスト プレビュー 通知の先頭から切り捨てられた行を表示します。
トピック 関連付けられたリソース、または要求本文からのトピックのテキスト値。

次の図は、Teams でのアクティビティ フィード通知の例を示しています。 この例では、ユーザーがアプリで投稿を共有しました。

Yammer アクティビティ フィード通知の画像

アクティビティ フィード通知カードの種類

次のタブには、表示できるアクティビティ フィード通知カードの種類が表示されます。 アプリによって生成された通知の場合、ユーザー ロゴはアプリ ロゴに置き換えられます。

Teams カスタム

デスクトップ Teams カスタムのアクティビティ フィード通知を示すスクリーンショット。

Windows

Windows デスクトップ Teams のアクティビティ フィード通知を示すスクリーンショット。

Mac

Mac デスクトップ Teams のアクティビティ フィード通知を示すスクリーンショット。

アクティビティ フィード通知 API を使用するための要件

アクティビティ フィード API は 、Teams アプリで動作します。 アクティビティ フィード通知を送信するための要件を次に示します。

  • Teams アプリ マニフェストには、セクションにMicrosoft Entraアプリ ID が追加されているwebApplicationInfo必要があります。 詳細については、「 マニフェスト スキーマ」を参照してください。
  • アクティビティ通知は、アプリ マニフェストで宣言されたアクティビティの種類の有無にかかわらず送信できます。
    • 既定では、マニフェストでセクションを宣言 activities せずにアクティビティ通知 API を使用できます。 アクティビティの systemDefault 種類は予約されており、アクティビティ フィード通知の行に Actor+Reason 自由形式のテキストを指定できます。 詳細については、「 カスタマイズ可能なアクティビティ フィード通知を送信する」を参照してください。

      注:

      アクティビティの種類は systemDefault パブリック プレビューでのみ使用できます。

    • 従来のモードでテンプレート化された通知を送信する場合は、[ アクティビティ] セクション でアクティビティの種類を宣言する必要があります。 詳細については、「 マニフェスト スキーマ」を参照してください。
  • Teams アプリは、受信者に対して、個人または チーム にインストールするか、自分が参加している チャット にインストールする必要があります。 詳細については、「 Teams アプリのインストール」を参照してください。

アクセス許可

委任されたアクセス許可またはアプリケーションのアクセス許可を使用して、アクティビティ通知を送信できます。 アプリケーションのアクセス許可を使用する場合は、アクセス許可によってユーザーがアクティビティ通知を送信することに同意できるため、リソース固有のTeamsActivity.Send.User同意 (RSC) を使用することをお勧めします。 Teams アプリ マニフェスト スキーマで RSC アクセス許可を宣言する必要があります。

Teams アプリ マニフェストの更新

このセクションでは、アクティビティ フィード通知を実装するために Teams アプリ マニフェストに対して行う必要がある変更について説明します。 Teams アプリ マニフェストのバージョン1.7以上を使用する必要があります。

"$schema": "https://developer.microsoft.com/json-schemas/teams/v1.7/MicrosoftTeams.schema.json",
"manifestVersion": "1.7",

webApplicationInfo 更新プログラム

アプリ マニフェスト webApplicationInfo プロパティのMicrosoft Entraidresource情報を更新する必要があります。

"webApplicationInfo":
{
    "id": "a3111f15-658e-457c-9689-fd20fe907330",
    "resource": "https://contosoapp.com"
}
パラメーター 説明
id string Microsoft Entra (クライアント ID)。
resource string Azure AD アプリに関連付けられているリソース。 これは、Microsoft Entra 管理センター アプリ登録の概要の応答またはリダイレクト URI とも呼ばれます。

注:

同じスコープ内の複数の Teams アプリ (チーム、チャット、またはユーザー) が同じMicrosoft Entra アプリを使用すると、エラーが発生する可能性があります。 一意のMicrosoft Entra アプリを使用していることを確認します。

アクティビティの更新

ユーザー アクティビティ フィードを activities 投稿するには、アプリ マニフェストで プロパティを定義する必要があります。

"activities":
{
  "activityTypes": [
    {
      "type": "taskCreated",
      "description": "Task Created Activity",
      "templateText": "{actor} created task {taskId} for you"
    },
    {
      "type": "approvalRequired",
      "description": "Deployment requires your approval",
      "templateText": "{actor} created a new deployment {deploymentId}"
    }
  ]
}
パラメーター 説明
type string 型は、特定のマニフェストで一意である必要があります。
説明 string 人間が判読できる簡単な説明。 説明は Microsoft Teams クライアントに表示されます。
templateText string アクティビティ通知のテンプレート テキスト。 パラメーターを中かっこで囲んでカプセル化することで、パラメーターを {}宣言できます。

注:

  • actor は、常に呼び出し元の名前を受け取る特殊なパラメーターです。 委任された呼び出しでは、 actor はユーザーの名前です。 アプリケーションのみの呼び出しでは、Teams アプリの名前を受け取ります。

  • 予約済み systemDefault アクティビティの種類は、マニフェストの activities セクションで指定しないでください。 予約済みアクティビティの種類は、アクティビティ フィード通知の行に Actor+Reason 自由形式のテキストを提供できます。 詳細については、「 カスタマイズ可能なアクティビティ フィード通知を送信する」を参照してください。

承認の更新

"authorization": 
{ 
  "permissions": { 
    "resourceSpecific": [ 
      {
        "type": "Application", 
         "name": "TeamsActivity.Send.User" 
      }, 
      { 
        "type": "Application",
        "name": "TeamsActivity.Send.Group"
      }, 
      { 
        "type": "Application", 
        "name": "TeamsActivity.Send.Chat" 
      } 
    ] 
  }
} 

パラメーター 説明
type 文字列 リソース固有の同意 (RSC) アクセス許可の種類。
name string RSC アクセス許可の名前。 詳細については、「サポートされている RSC アクセス許可」を参照してください。

Teams アプリをインストールする

Teams アプリは、チーム、チャット、またはユーザーに個人的にインストールでき、複数の方法で配布できます。 詳細については、「 Teams アプリの配布方法」を参照してください。 通常、 サイドローディング は開発目的で推奨されます。 開発後は、1 つのテナントに配布するか、すべてのテナントに配布するかに基づいて、適切な配布方法を選択できます。

Teams アプリインストール API を使用して、Teams アプリのインストールを管理することもできます。

アクティビティ フィード通知をユーザーに送信する

注:

iOS クライアントと Android クライアントでアクティビティ フィード通知を表示するには、アプリを許可リストに含める必要があります。 サポートされているのはサード パーティ製アプリのみです。

Teams アプリはユーザー、チーム、チャットにインストールできるため、通知は 3 つのコンテキストで送信できます。 各コンテキストで通知を送信する方法の詳細については、次のトピックを参照してください。

さらに、通知は一度に最大 100 人のユーザーに一括で送信できます。 詳細については、次のトピックを参照してください。

各シナリオでサポートされるトピックの詳細については、特定の API を参照してください。 カスタム テキスト ベースのトピックは、すべてのシナリオでサポートされています。

注:

アクティビティ アイコンは、要求が行われるコンテキストに基づいています。 委任されたアクセス許可で要求が行われた場合、ユーザーの写真がアバターとして表示され、Teams アプリ アイコンがアクティビティ アイコンとして表示されます。 アプリケーションのみのコンテキストでは、Teams アプリ アイコンがアバターとして使用され、アクティビティ アイコンは省略されます。

例 1: チャットで作成されたタスクについてユーザーに通知する

次の例は、チャットで作成された新しいタスクのアクティビティ フィード通知を送信する方法を示しています。 この場合、Teams アプリは ID chatId を使用してチャットにインストールする必要があり、ユーザー 569363e2-4e49-4661-87f2-16f245c5d66a もチャットの一部である必要があります。

要求

POST https://graph.microsoft.com/v1.0/chats/{chatId}/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "entityUrl",
        "value": "https://graph.microsoft.com/v1.0/chats/{chatId}"
    },
    "activityType": "taskCreated",
    "previewText": {
        "content": "New Task Created"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
        "userId": "569363e2-4e49-4661-87f2-16f245c5d66a"
    },
    "templateParameters": [
        {
            "name": "taskId",
            "value": "12322"
        }
    ]
}

応答

HTTP/1.1 204 No Content

例 2: チームで作成されたタスクについてユーザーに通知する

次の例は、チームのアクティビティ フィード通知を送信する方法を示しています。 この例では、チームの所有者に、注意が必要な新しいタスクについて通知します。

要求

POST https://graph.microsoft.com/v1.0/teams/{teamId}/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "entityUrl",
        "value": "https://graph.microsoft.com/v1.0/teams/{teamId}"
    },
    "activityType": "taskCreated",
    "previewText": {
        "content": "New Task Created"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
        "userId": "569363e2-4e49-4661-87f2-16f245c5d66a"
    },
    "templateParameters": [
        {
            "name": "taskId",
            "value": "12322"
        }
    ]
}

応答

HTTP/1.1 204 No Content

例 3: カスタム トピックを使用してイベントについてユーザーに通知する

前の例に示したように、さまざまなチームやチャットの側面にリンクできます。 ただし、チームの一部ではない側面にリンクする場合や、Microsoft Graph が表していない場合、または名前をカスタマイズする場合は、 の topic ソースを に text 設定し、カスタム値を渡すことができます。 また、webUrlソースを としてtext使用topicする場合は、 が必要です。

前に示した Yammer 通知の例では、Microsoft Graph では Yammer のリソースがサポートされていないため、カスタム トピックが使用されています。

注:

webUrl は、Microsoft Teams ドメイン (teams.microsoft.com など) で始まる必要があります。

要求

POST https://graph.microsoft.com/v1.0/teams/{teamId}/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "text",
        "value": "Deployment Approvals Channel",
        "webUrl": "https://teams.microsoft.com/l/message/19:448cfd2ac2a7490a9084a9ed14cttr78c@thread.skype/1605223780000?tenantId=c8b1bf45-3834-4ecf-971a-b4c755ee677d&groupId=d4c2a937-f097-435a-bc91-5c1683ca7245&parentMessageId=1605223771864&teamName=Approvals&channelName=Azure%20DevOps&createdTime=1605223780000"
    },
    "activityType": "approvalRequired",
    "previewText": {
        "content": "New deployment requires your approval"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
        "userId": "569363e2-4e49-4661-87f2-16f245c5d66a"
    },
    "templateParameters": [
        {
            "name": "deploymentId",
            "value": "6788662"
        }
    ]
}

応答

HTTP/1.1 204 No Content

例 4: イベントについてチーム メンバーに通知する

次の例は、すべてのチーム メンバーにアクティビティ フィード通知を送信する方法を示しています。 この例では、新しいイベントについてチーム メンバーに通知します。

要求

POST https://graph.microsoft.com/v1.0/teams/7155e3c8-175e-4311-97ef-572edc3aa3db/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "text",
        "value": "Weekly Virtual Social",
        "webUrl": "https://teams.microsoft.com/l/message/19:448cfd2ac2a7490a9084a9ed14cttr78c@thread.skype/1605223780000?tenantId=c8b1bf45-3834-4ecf-971a-b4c755ee677d&groupId=d4c2a937-f097-435a-bc91-5c1683ca7245&parentMessageId=1605223771864&teamName=Approvals&channelName=Azure%20DevOps&createdTime=1605223780000"
    },
    "previewText": {
        "content": "It will be fun!"
    },
    "activityType": "eventCreated",
    "recipient": {
        "@odata.type": "microsoft.graph.teamMembersNotificationRecipient",
        "teamId": "7155e3c8-175e-4311-97ef-572edc3aa3db"
    }
}

応答

HTTP/1.1 204 No Content

例 5: イベントについてチャネル・メンバーに通知する

次の例は、すべてのチャネル メンバーにアクティビティ フィード通知を送信する方法を示しています。 次の使用例は、チャネル メンバーに新しいイベントについて通知します。

要求

POST https://graph.microsoft.com/v1.0/teams/7155e3c8-175e-4311-97ef-572edc3aa3db/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "text",
        "value": "Weekly Virtual Social",
        "webUrl": "https://teams.microsoft.com/l/message/19:448cfd2ac2a7490a9084a9ed14cttr78c@thread.skype/1605223780000?tenantId=c8b1bf45-3834-4ecf-971a-b4c755ee677d&groupId=d4c2a937-f097-435a-bc91-5c1683ca7245&parentMessageId=1605223771864&teamName=Approvals&channelName=Azure%20DevOps&createdTime=1605223780000"
    },
    "previewText": {
        "content": "It will be fun!"
    },
    "activityType": "eventCreated",
    "recipient": {
        "@odata.type": "microsoft.graph.channelMembersNotificationRecipient",
        "teamId": "7155e3c8-175e-4311-97ef-572edc3aa3db",
        "channelId": "19:0ea5de04de4743bcb4cd20cb99235d99@thread.tacv2"
    }
}

応答

HTTP/1.1 204 No Content

例 6: イベントについてチャット メンバーに通知する

次の例は、すべてのチャット メンバーにアクティビティ フィード通知を送信する方法を示しています。 この例では、新しいイベントについてチャット メンバーに通知します。

要求

POST https://graph.microsoft.com/v1.0/chats/19:d65713bc498c4a428c71ef9353e6ce20@thread.v2/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "text",
        "value": "Weekly Virtual Social",
        "webUrl": "https://teams.microsoft.com/l/message/19:448cfd2ac2a7490a9084a9ed14cttr78c@thread.skype/1605223780000?tenantId=c8b1bf45-3834-4ecf-971a-b4c755ee677d&groupId=d4c2a937-f097-435a-bc91-5c1683ca7245&parentMessageId=1605223771864&teamName=Approvals&channelName=Azure%20DevOps&createdTime=1605223780000"
    },
    "previewText": {
        "content": "It will be fun!"
    },
    "activityType": "eventCreated",
    "recipient": {
        "@odata.type": "microsoft.graph.chatMembersNotificationRecipient",
        "chatId": "19:d65713bc498c4a428c71ef9353e6ce20@thread.v2"
    }
}

応答

HTTP/1.1 204 No Content

例 7: 保留中の財務承認要求について複数のユーザーに通知する

次の例は、アクティビティ フィード通知を複数のユーザーに一括で送信する方法を示しています。 この例では、保留中の財務承認要求について複数の利害関係者に通知します。

要求

POST https://graph.microsoft.com/v1.0/teamwork/sendActivityNotificationToRecipients
Content-Type: application/json

{
    "topic": {
        "source": "entityUrl",
        "value": "https://graph.microsoft.com/v1.0/appCatalogs/teamsApps/{teamsAppId}"
    },
    "activityType": "pendingFinanceApprovalRequests",
    "previewText": {
        "content": "Internal spending team has a pending finance approval requests"
    },
    "recipients": [
        {
            "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
            "userId": "569363e2-4e49-4661-87f2-16f245c5d66a"
        },
        {
            "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
            "userId": "ab88234e-0874-477c-9638-d144296ed04f"
        },
        {
            "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
            "userId": "01c64f53-69aa-42c7-9b7f-9f75195d6bfc"
        }
    ],
    "templateParameters": [
        {
            "name": "pendingRequestCount",
            "value": "5"
        }
    ] 
}

応答

HTTP/1.1 202 Accepted

例 8: systemDefault アクティビティの種類を使用してユーザーに通知を送信する

次の例は、マニフェストでアクティビティの種類を定義せずに、チームのアクティビティ通知を送信する方法を示しています。 自由形式のテキストを提供する柔軟性があります。 詳細については、「 予約済みアクティビティの種類」を参照してください。

注:

アクティビティの種類は systemDefault パブリック プレビューでのみ使用できます。

次の使用例は、チーム所有者に少し休憩を取るように通知します。 をvaluetemplateParameters変更して、さまざまなシナリオの通知をカスタマイズします。

要求

POST https://graph.microsoft.com/v1.0/teams/{teamId}/sendActivityNotification
Content-Type: application/json

{
    "topic": {
        "source": "entityUrl",
        "value": "https://graph.microsoft.com/v1.0/teams/{teamId}"
    },
    "activityType": "systemDefault",
    "previewText": {
        "content": "Take a break"
    },
    "recipient": {
        "@odata.type": "microsoft.graph.aadUserNotificationRecipient",
        "userId": "569363e2-4e49-4661-87f2-16f245c5d66a"
    },
    "templateParameters": [
        {
            "name": "systemDefaultText",
            "value": "You need to take a short break"
        }
    ]
}

応答

HTTP/1.1 204 No Content

予約済みアクティビティの種類

アクティビティの systemDefault 種類は予約されており、 アクティビティの宣言中にマニフェストで使用することはできません。 アクティビティの種類を使用すると、次の systemDefault ことができます。

  • アプリ マニフェストでアクティビティの種類を定義せずに、新しいシナリオを簡単にテストしたり、アクティビティ フィード通知 API をすばやく試したりできます。
  • ストア アプリの場合は、アプリ マニフェストでアクティビティの種類を絶えず調整する必要がないため、時間を節約し、プロセスを合理化します。 アクティビティの systemDefault 種類は、get-go から使用する準備が整いました。

アクティビティの種類では systemDefault 、次のことができないことに注意してください。

  • マニフェストによって提供される組み込みのローカライズ機能を利用します。
  • アクティビティの種類を使用してカスタマイズ可能な通知を systemDefault 送信します。 ユーザーは、Microsoft Teams クライアント設定のトグルを使用してアプリからのすべての通知をオフにできます。これにより、アプリとそのユーザー間の通信が妨げられる可能性があります。

マニフェストにはアクティビティ テンプレートが必要なため、定期的な通知と大量の通知のバッチに対してテンプレート化された通知を引き続きお勧めします。

予約済みアクティビティの種類は systemDefault 、アプリのマニフェストに一覧表示されているアクティビティの種類に関係なく、引き続き使用できます。

通知のアラート方法をカスタマイズする

Microsoft Teams ユーザーは、フィードに表示される通知をバナーとしてカスタマイズできます。 アクティビティ フィード API を介して生成された通知もカスタマイズできます。 ユーザーは、Microsoft Teams の設定を使用して通知する方法を選択できます。 次のスクリーンショットに示すように、ユーザーが選択できる Teams アプリが一覧に表示されます。

[カスタム] オプションが強調表示されている Teams の通知設定のスクリーンショット

ユーザーは、次の例に示すように、アプリの横にある [編集] を選択し、通知をカスタマイズできます。 description Teams アプリ マニフェストのフィールドが表示されます。

Teams アプリのバナーとフィードにカスタマイズされた通知を示すスクリーンショット

FAQ

Teams アプリをインストールする必要があるユーザー

ターゲット ユーザーには、通知を送信している Teams アプリがインストールされている必要があります。

ユーザーは自分に通知を送信できますか?

いいえ。ユーザーは自分に通知を送信できません。 このシナリオでは、アプリケーションのアクセス許可を使用します。

Teams アプリは、ユーザーに通知を表示する方法を制御できますか?

いいえ。通知設定を変更できるのはユーザーだけです。

アプリをインストールしました。ユーザー アカウントに通知設定が表示されないのはなぜですか?

設定は、Teams アプリが最初の通知を送信した後に表示されます。 これにより、ユーザーに表示される設定の数が減ります。

409 (競合) エラーが発生し始めました。どのように解決すればよいですか?

Conflictエラーは、主に、同じスコープ (チーム、チャット、ユーザーなど) にインストールされている複数の Teams アプリがマニフェストのセクションでwebApplicationInfo同じMicrosoft Entra appId を持っている場合に発生します。 これが発生すると、 のような Found multiple applications with the same Microsoft Entra App ID 'Your Microsoft Entra AppId'.エラーが発生します。 一意の Teams アプリに一意のMicrosoft Entra アプリを使用していることを確認します。 同じ Teams アプリを複数のスコープ (チーム + ユーザーなど) にインストールできます。