[Doc Feature] [Apps in shared channels - Notification for indirect membership update and notification for team (host/non-host)[4532183] #13010
+109
−41
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,5 @@ | ||
| --- | ||
| title: Teams Connects Shared Channels | ||
| author: surbhigupta | ||
| description: Learn about Teams Connect shared channels to securely collaborate with internal and external users in a shared space without switching tenants. | ||
| ms.author: surbhigupta | ||
|
|
@@ -8,23 +8,29 @@ ms.topic: conceptual | |
| ms.date: 04/09/2025 | ||
| --- | ||
|
|
||
| # Microsoft Teams connect shared channels | ||
|
|
||
| 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 | ||
|
|
||
| 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. | ||
|
|
||
| ## 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](../../resources/schema/manifest-schema.md#supportedchanneltypes). | ||
|
|
@@ -36,15 +42,9 @@ SupportedChannelTypes is an optional property that enables your app in non-stand | |
| ] | ||
|
There was a problem hiding this comment. I believe this is changing. Can you please sync with Gaurav to update this? |
||
| ``` | ||
|
|
||
| ## Get context for shared channels | ||
|
There was a problem hiding this comment.
There was a problem hiding this comment. Ajay has validated and confirmed that it is happening
NehaHEDAU-MSFT marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| 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,39 +60,112 @@ You can collaborate with external members outside of your organization using sha | |
|
|
||
| ## Get shared channel membership | ||
|
|
||
| Use the [List allMembers API](/graph/api/channel-list-allmembers?view=graph-rest-beta&tabs=http) to retrieve both direct and indirect members of a shared channel. | ||
|
|
||
| ### Identify direct or indirect members | ||
|
|
||
| * Direct Members: Users who are added directly to the channel, including users from other tenants (cross-tenants). | ||
|
|
||
| * 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. | ||
|
|
||
| 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. | ||
|
|
||
| |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. | | ||
|
|
||
| > [!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. | ||
|
|
||
| ## Get app notifications for direct and indirect membership changes | ||
|
|
||
| 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. [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. | ||
|
|
||
| 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). | ||
|
|
||
| ```http | ||
| `/teams/{team-id}/channels/getAllMembers?notifyOnIndirectMembershipUpdate=true&suppressNotificationWhenSharedUnsharedWithTeam=true` | ||
| ``` | ||
|
|
||
|
There was a problem hiding this comment. We also should update the new subscription that supports /shared with teams. There was a problem hiding this comment. Added the documentation for the new subscription that supports /shared with teams. We have tested and added it to the sample code. There was a problem hiding this comment. I think we should add this line in a http markdown or something similar. Also, add the the link for channel membership for easy access?https://learn.microsoft.com/en-us/graph/teams-changenotifications-channelmembership |
||
| 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) | ||
|
|
||
| ### Validate user access for membership updates | ||
|
|
||
| When an app receives a notification for an indirect membership update, it’s important to verify whether the user still has access to the shared channel as 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 is truly lost. Use the **doesUserHaveAccess** API to determine whether the user still has access to the shared channel. | ||
|
There was a problem hiding this comment. The access check is only suggested for remove member let's rephrase this since add member does not need access check. The example is perfect by the way! There was a problem hiding this comment. For add membership update notification you may add the get list of all members will refresh the member list. |
||
|
|
||
| ```http | ||
| GET /teams/{team-id}/channels/{channel-id}/doesUserHaveAccess(userId='@userid',tenantId='@TenantID',userPrincipalName='@UserPrincipalName') | ||
| ``` | ||
|
|
||
| See [doesUserHaveAccess API](/graph/api/channel-doesuserhaveaccess?view=graph-rest-beta&tabs=http) to learn more about user accesses and relevant permissions. | ||
|
|
||
| ### Handle bulk membership changes | ||
|
|
||
| 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. | ||
|
|
||
| #### 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 API after receiving a 'shared with' or 'unshared from' team notification. | ||
|
There was a problem hiding this comment. list allMembers api and use the api link whenever we are referring to use an api. |
||
|
|
||
| > [!NOTE] | ||
| > To support membership updates in shared channels, apps using resource-specific consent (RSC) must request extended permissions. | ||
| > These permissions let the app: | ||
| > | ||
| > * Access membership data (both direct and indirect members). | ||
| > * Receive and respond to membership change notifications. | ||
|
|
||
| ### Manage indirect membership in shared channels | ||
|
There was a problem hiding this comment. You may also list does user have access api since that is newly added to this list to manage membership |
||
|
|
||
| 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 [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. | ||
|
|
||
| ```http | ||
| GET /teams/{team-id}/channels/{channel-id}/sharedWithTeams | ||
| ``` | ||
|
|
||
| * 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] | ||
| > `allowedMembers` API returns only newly associated users and doesn't apply to unshared events. | ||
|
|
||
| ## Classify shared channel members as in-tenant or out-tenant | ||
|
There was a problem hiding this comment. Since we are talking about shared channel here, replace members api with allMembers api. That will show cross tenant for both direct and indirect members. Please rephrase this section as needed. |
||
|
|
||
| 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}/members | ||
| ``` | ||
|
|
||
| >[!NOTE] | ||
| > The GET API only gives you the list of direct members of the shared channel. | ||
|
|
||
| 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 | ||
| <a name='azure-ad-native-identity'></a> and determine if the member is an in-tenant or out-tenant. | ||
|
|
||
| ## Microsoft Entra native identity | ||
|
There was a problem hiding this comment. Also this section "Microsoft Entra native identity" Can you please verify if this information is correct? What context do we use this? |
||
|
|
||
|
There was a problem hiding this comment. I see a section "Apps in federated group chats with external users" I don't think this section belongs to shared channel. Can you please validate and remove? |
||
|
|
@@ -122,9 +195,10 @@ If you're developing an app for use in federated group chats with external users | |
|
|
||
| ## Code sample | ||
|
|
||
| | 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 | ||
|
|
||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.