diff --git a/msteams-platform/TOC.yml b/msteams-platform/TOC.yml index f56bd432b06..0e9fe800611 100644 --- a/msteams-platform/TOC.yml +++ b/msteams-platform/TOC.yml @@ -521,7 +521,7 @@ displayName: Teams Store apps approved by Microsoft for mobile - name: Apps for shared channels href: concepts/build-and-test/shared-channels.md - displayName: Cross-tenant notifications, context for shared channel, apps and permissions in shared channels + displayName: Cross-tenant notifications, context for shared channel, apps and permissions in shared channels, notifications for indirect membership - name: Send activity feed notifications href: /graph/teams-send-activityfeednotifications?toc=/microsoftteams/platform/toc.json&bc=/microsoftteams/platform/breadcrumb/toc.json displayName: activity feed, notification, customize notification diff --git a/msteams-platform/concepts/build-and-test/shared-channels.md b/msteams-platform/concepts/build-and-test/shared-channels.md index cfa50647ee8..cf8c635ccb6 100644 --- a/msteams-platform/concepts/build-and-test/shared-channels.md +++ b/msteams-platform/concepts/build-and-test/shared-channels.md @@ -8,23 +8,29 @@ ms.topic: conceptual ms.date: 04/09/2025 --- -# Microsoft Teams Connect shared channels +# Microsoft Teams connect shared channels -Microsoft Teams Connect shared channels allow members of a channel to collaborate with users across other teams and organizations. You can create and share a shared channel with: +Teams connect shared channels, which facilitates secure collaboration seamlessly. Allow external members outside of your organization to collaborate with internal users in Teams without changing their user context. You can create and share a shared channel with: -* Members of another team within the same organization. -* Individuals within the same organization. -* Individuals and other teams of other organizations. +* Members of another team within the same organization +* Individuals within the same organization +* Individuals and other teams of other organizations + +Shared channels ensure: + +* Enhanced user experience through cross-tenants collaboration +* Secure granular access control +* Real-time membership syncing + +A sample illustration showing shared channel membership is as follows: + +:::image type="content" source="~/assets/images/app-fundamentals/shared-channels-teams.png" alt-text="Diagram shows Team B from organization A and Team C from organization B collaborating in a shared channel as Team A."::: > [!NOTE] > > * Tab apps in shared channels are available in [Government Community Cloud (GCC), GCC High, Department of Defense (DoD)](../cloud-overview.md#teams-app-capabilities), and [Teams operated by 21Vianet](../sovereign-cloud.md) environments. > * SharePoint and the SharePoint pages apps aren't supported for shared channels in GCC, GCC High, DoD, and Teams operated by 21Vianet environments. -Teams Connect shared channels facilitate secure collaboration seamlessly. Allow external users outside of your organization to collaborate with internal users in Teams without changing their user context. Enhance user experience unlike using guest accounts, for example, the members must sign out of Teams and sign in again using a guest account. Teams applications extend the powerful collaboration space. - -:::image type="content" source="~/assets/images/app-fundamentals/shared-channels-teams.png" alt-text="Diagram shows Team B from organization A and Team C from organization B collaborating in a shared channel as Team A."::: - ## Enable your app for shared channels SupportedChannelTypes is an optional property that enables your app in non-standard channels. If your app supports the team scope and the property is defined, Teams enables your app in each channel type accordingly. Private and shared channels are supported. For more information, see [supportedChannelTypes](/microsoft-365/extensibility/schema/root#supportedchanneltypes). @@ -36,15 +42,9 @@ SupportedChannelTypes is an optional property that enables your app in non-stand ] ``` -> [!NOTE] -> -> * If your app supports the team scope, it functions in standard channels, regardless of what values are defined in this property. -> * Your app might need to account for the unique properties of each of these channel types in order to function properly. -> * Only **tabs** are currently supported in **private** and **shared** channels in Microsoft Teams. - ## Get context for shared channels -When the content UX is loaded in a shared channel, use the data received from `getContext` call for shared channel changes. `getContext` call publishes two new properties, `hostTeamGroupID` and `hostTenantID`, which are used to retrieve channel membership using Microsoft Graph APIs. `hostTeam` is the team that creates the shared channel. +When the content UX is loaded in a shared channel, use the data received from `getContext` call for shared channel changes. `getContext` call publishes two new properties, `ownerGroupID` and `ownerTenantID`, which are used to retrieve channel membership using Microsoft Graph APIs. `hostTeam` is the team that creates the shared channel. For more information to enable your tab, see: @@ -60,71 +60,129 @@ You can collaborate with external members outside of your organization using sha ## Get shared channel membership -You can get direct shared channel membership by using the `hostTeamGroupID` from `getContext` and following these steps: +Use the [List allMembers API](/graph/api/channel-list-allmembers?view=graph-rest-beta&tabs=http&preserve-view=true) to retrieve both direct and indirect members of a shared channel. -1. Get direct members with [GET channel members API](/graph/api/channel-list-members?view=graph-rest-beta&tabs=http&preserve-view=true) API. +### Identify direct or indirect members - ```http - GET /teams/{host-team-group-id}/channels/{channel-id}/members - ``` +* Direct Members: Users who are added directly to the channel, including users from other tenants (cross-tenants). -2. Get each shared team with GET `sharedWithTeams` API. +* Indirect Members: Users who are members of the team, with which the channel is shared, including teams in the same tenant or in a cross-tenant. - ```http - GET /teams/{host-team-group-id}/channels/{channel-id}/sharedWithTeams - ``` +Additionally, you can identify whether a member of a shared channel is direct or indirect by checking the **@microsoft.graph.originalSourceMembershipUrl** annotation. This property identifies the source of a member’s access to a shared channel, as shown in the following table. -3. Use GET members of each shared team (Team X) with GET `sharedWithTeams` API. +|Member Type |Annotation Present? |Description | +|---------|---------|---------| +|Direct Member | **Yes** | The user is added directly to the shared channel. | +|Indirect Member| **Yes** | The user accesses the shared channel through another team. The *@microsoft.graph.originalSourceMembershipUrl* property includes a URL that points to the source team and indicates that the user is an indirect member of the shared channel. | - ```http - GET /teams/{host-team-group-id}/channels/{channel-id}/sharedWithTeams/{teamX}/members - ``` +> [!NOTE] +> You might receive duplicate notifications when a member is added to a shared channel. This scenario can happen if the member is already part of the shared channel directly or through another linked team. Use the **List allMembers API** to view all the direct and indirect members. +> Ignore the notification if the member already exists; either directly or indirectly. -## Classify members in the shared channel as in-tenant or out-tenant +## Get app notifications for direct and indirect membership changes -You can classify members as in-tenant or out-tenant by comparing `tenantID` of the member or team with `hostTeamTenantID` as follows: +Apps installed in shared channels receive notifications when users are added to or removed from a team that shares the channel. To receive these notifications, you must: -1. Get the member you wish to compare. +1. [Install the app](../deploy-and-publish/apps-upload.md) in a host team and enable it for the shared channel. +1. Create a valid Microsoft Graph change notification subscription to monitor associated team membership changes and shared or unshared events using supported APIs. - ```http - GET /teams/{host-team-group-id}/channels/{channel-id}/members - ``` +To receive both direct and indirect member update notifications, you must include both the query string parameters when creating a subscription. If the query strings aren't provided, the subscription only delivers notifications for direct member updates. To learn more, see [Channel membership access](/graph/teams-changenotifications-channelmembership). -2. Use `getContext`, compare the `tenantID` of the member to the `hostTenantID` property. +```http +`/teams/{team-id}/channels/getAllMembers?notifyOnIndirectMembershipUpdate=true&suppressNotificationWhenSharedUnsharedWithTeam=true` +``` - +This subscription enables apps to monitor membership changes in shared channels and its associated teams. For more information on how to create a Microsoft Graph change notification subscription, see [Create a subscription.](/graph/teams-changenotifications-teammembership) -## Microsoft Entra native identity +### Validate user access for membership updates + +When an app receives a 'member removed' notification for an indirect membership update, it’s important to verify whether the user is removed from the shared channel, especially since the same user might have both direct and indirect membership. For example, if a user is removed from a team that shares a channel, the app should confirm whether the user's access to the shared channel is revoked. +Use the **doesUserHaveAccess** API to determine whether the user is removed from the shared channel. +See [doesUserHaveAccess API](/graph/api/channel-doesuserhaveaccess?view=graph-rest-beta&tabs=http&preserve-view=true) to learn more about user accesses and relevant permissions. + +```http +GET /teams/{team-id}/channels/{channel-id}/doesUserHaveAccess(userId='@userid',tenantId='@TenantID',userPrincipalName='@UserPrincipalName') +``` + +When a member receives a 'member added' notification for an indirect membership update, +See [allMembers API](/graph/api/channel-list-allmembers?view=graph-rest-beta&branch=pr-en-us-27360&tabs=http&preserve-view=true), to refresh the list of all member. + +```http +GET /teams/{team-id}/channels/{channel-id}/allMembers +``` -Apps must function cross-tenants in installation and usage. The following table lists the channel types and their corresponding group IDs: +### Handle bulk membership changes -|Channel type| groupId | hostTeamGroupId | -|----------|---------|-----------------| -|Regular | Team Microsoft Entra group ID | Team Microsoft Entra group ID | -|Shared | Empty | Host Team Microsoft Entra group ID | +If there are bulk membership changes, Teams curbs individual membership update notifications when a channel is shared or unshared with a team. This feature reduces notification volume and improves performance. -## Apps in federated group chats with external users +#### Use sharedWithTeams Subscription for Bulk Membership Changes + +To reduce notification overload during membership updates, such as when a shared channel is added to or removed from a team with thousands of members, use the new SharedWithTeams subscription resource: + +`/teams/{team-id}/channels/{channel-id}/sharedWithTeams` + +The sharedWithTeams subscription sends a single notification when a channel is shared or unshared with a team. It avoids thousands of per-user notifications and improves performance for apps that monitor membership changes. Ensure that you update the shared channel member list using the [allMembers](/graph/api/channel-list-allmembers?branch=main&branchFallbackFrom=pr-en-us-13010&view=graph-rest-1.0&tabs=http&preserve-view=true) API after receiving a 'shared with' or 'unshared from' team notification. > [!NOTE] +> To support membership updates in shared channels, apps using resource-specific consent (RSC) must request extended permissions. +> These permissions let the app: > -> * Apps in federated group chats with external users aren't available in [Government Community Cloud (GCC), GCC High, Department of Defense (DoD)](../cloud-overview.md#teams-app-capabilities), and [Teams operated by 21Vianet](~/concepts/sovereign-cloud.md) environments. -> * Apps aren't supported in one-on-one chats, channels, or meetings with external users. +> * Access membership data (both direct and indirect members). +> * Receive and respond to membership change notifications. + +### Manage indirect membership in shared channels + +You can manage indirect membership in shared channels using the following Microsoft Graph APIs: + +* Use [allMembers](/graph/api/channel-list-allmembers?branch=main&branchFallbackFrom=pr-en-us-13010&view=graph-rest-1.0&tabs=http&preserve-view=true) API to retrieve all users who are members of a specific channel. + + ```http + GET /teams/{team-id}/channels/{channel-id}/allMembers + ``` + +* Use [doesUserHaveAccess API](/graph/api/channel-doesuserhaveaccess?view=graph-rest-beta&tabs=http&preserve-view=true) API to determine whether the user is removed from the channel and view all user accesses and relevant permissions. + + ```http + GET /teams/{team-id}/channels/{channel-id}/doesUserHaveAccess(userId='@userid',tenantId='@TenantID',userPrincipalName='@UserPrincipalName') + ``` -Teams supports the use of apps in federated group chats with external users. These users can't add, update, or remove apps from the group chat. Only the host of the group chat can add, update, or remove apps. However, all members of the chat, including external users, can use apps under the following conditions: +* Use [sharedWithTeams](/graph/api/sharedwithchannelteaminfo-list?branch=main&branchFallbackFrom=pr-en-us-13010&view=graph-rest-1.0&tabs=http&preserve-view=true) API to list all teams a channel is shared with. -* The tenant admin of the group chat host's organization and the tenant admin of the external user's organization must allow the use of the app in federated group chats. For more information, see [Teams apps for external attendees or guests from outside an organization](/microsoftteams/apps-external-users). -* The app allows access to external users in federated group chats. + ```http + GET /teams/{team-id}/channels/{channel-id}/sharedWithTeams + ``` -If you're developing an app for use in federated group chats with external users, register your app as a multitenant app in Microsoft Entra ID. This action allows users across multiple organizations to access your app. +* Use the [allowedMembers](/graph/api/sharedwithchannelteaminfo-list-allowedmembers?branch=main&branchFallbackFrom=pr-en-us-13010&view=graph-rest-1.0&tabs=http&preserve-view=true) API to retrieve users from a shared team who can access a shared channel. + + ```http + GET /teams/{team-id}/channels/{channel-id}/sharedWithTeams/{sharewithteamsId}/allowedMembers + ``` > [!NOTE] -> If you want to test the [code sample](#code-sample) with an external user in a federated group chat, you must first add the external user as a guest to your tenant. For more information, see [Quickstart: Add a guest user and send an invitation](/entra/external-id/b2b-quickstart-add-guest-users-portal). After adding the user to the tenant, go to the federated group chat and add the guest to test the app. +> `allowedMembers` API returns only newly associated users and doesn't apply to unshared events. + +## Classify shared channel members as in-tenant or out-tenant + +You can classify members as in-tenant or out-tenant by comparing the `TenantId` of the member or team with `ownerTenantId` as follows: + +1. Get the TenantId of the member you wish to compare. + + ```http + GET /teams/{host-team-group-id}/channels/{channel-id}/allMembers + ``` + +2. Call microsoftTeams.app.getContext() in your tab from the Teams JavaScript client library (**TeamsJS SDK**). + The getContext() call returns context of the shared channel, which contains the details such as **displayName**, **membershipType**, **ownerGroupId** , and **ownerTenantId**. + +3. Compare the `TenantId` of the member to the `ownerTenantId` property + and determine if the member is an in-tenant or out-tenant. ## Code sample -| Sample name | Description | Node.js | -|-------------|-------------|------|----| -| Teams Conversation Bot | This sample app displays the names of the members in a federated group chat with external users. |[View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/bot-feed-members/nodejs/)| +| Sample name | Description | .NET | Node.js | Python | +|-------------|-------------|------|----|------|----| +| Teams Conversation Bot | This sample app displays the names of the members in a federated group chat with external users.| NA |[View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/bot-feed-members/nodejs/) | NA | +| Membership change notification | The sample application demonstrates how to send notifications for shared channel events in Microsoft Teams. Scenarios include users being added, removed, or membership being updated and when channel is shared or unshared with a team. | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/membershipChangeNotificationNodejs/samples/graph-membership-change-notification/csharp) |[View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/membershipChangeNotificationNodejs/samples/graph-membership-change-notification/nodejs) | [View](https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/membershipChangeNotificationNodejs/samples/graph-membership-change-notification/python) | ## See also diff --git a/msteams-platform/whats-new.md b/msteams-platform/whats-new.md index 74e9246e7eb..df3acf50f85 100644 --- a/msteams-platform/whats-new.md +++ b/msteams-platform/whats-new.md @@ -38,10 +38,6 @@ Teams platform features that are available to all app developers.
**2025 September** -* ***September 18, 2025***: [Teams AI library is now generally available for JavaScript and C#. It provides a simplified SDK, support for Model Context Protocol (MCP), Agent-to-Agent communication (A2A), and streamlined tools to enable developers to build intelligent agents for Teams](/microsoftteams/platform/teams-ai-library/welcome). - -:::column-end::: -:::row-end:::