Manage the life cycle of private channels in Microsoft Teams

Here you'll find the guidance you need to manage the life cycle of private channels in your organization.

Important

If you're using the PowerShell steps in this article to manage private channels, you must install and use the Teams PowerShell public preview module from the PowerShell Gallery. For steps on how to install the module, see Install Microsoft Teams PowerShell. The latest General Availability Teams PowerShell module doesn't support managing private channels.

Set whether team members can create private channels

Team owners can turn off or turn on the ability for members to create private channels in team settings. To do this, on the Settings tab for the team, turn off or turn on Allow members to create private channels.

As an admin, you can use Graph API to control whether members can create private channels in specific teams. Here's an example.

PATCH /teams/<team_id>​
{"memberSettings": ​
  {​
    "allowCreatePrivateChannels": false​
  }​
}

Set whether users in your organization can create private channels

As an admin, you can set policies by using the Microsoft Teams admin center or PowerShell to control which users in your organization are allowed to create private channels.

Using the Microsoft Teams admin center

Use teams policies to set which users in your organization are allowed to create private channels. To learn more, see Manage teams policies in Teams.

Using PowerShell

Use CsTeamsChannelsPolicy to set which users in your organization are allowed to create private channels. Set the AllowPrivateChannelCreation parameter to true to allow users who are assigned the policy to create private channels. Setting the parameter to false turns off the ability to create private channels for users who are assigned the policy.

To learn more, see New-CsTeamsChannelsPolicy.

Create a private channel on behalf of a team owner

As an admin, you can use PowerShell or Graph API to create a private channel on behalf of a team owner. For example, you may want to do this if your organization wants to centralize creation of private channels.

Using PowerShell

New-TeamChannel –GroupId <Group_Id> –MembershipType Private –DisplayName "<Channel_Name>" –Owner <Owner_UPN>

Using Graph API

POST /teams/{id}/channels​
{ "membershipType": "Private",​
  "displayName": "<Channel_Name>",​
  "members":[{    ​
           "@odata.type":"#microsoft.graph.aadUserConversationMember",​
           "user@odata.bind":"https://graph.microsoft.com/beta/users('<user_id>')",​
           "roles":["owner"]​
            }]

Get a list of all private channel messages

You may want to get a list of all messages and replies posted in a private channel for archiving and auditing purposes. Here's how to use Graph API to do this.

GET /teams/{id}/channels/{id}/messages​
GET /teams/{id}/channels/{id}/messages/{id}/replies/{id}

Find SharePoint URLs for all private channels in a team

Whether you're looking to perform eDiscovery or legal hold on files in a private channel or looking to build a custom app that places files in specific private channels, you'll want a way to query the unique SharePoint site collections that are created for each private channel.

As an admin, you can use PowerShell or Graph APIs commands to query these URLs.

Using PowerShell

  1. Install and connect to the SharePoint Online Management Shell with your admin account.

  2. Run the following, where <group_id> is the Group ID of the team. (You can easily find the Group ID in the link to the team.)

    $sites = get-sposite -template "teamchannel#0"
    $groupID = "<group_id>"
    foreach ($site in $sites) {$x= Get-SpoSite -Identity
    $site.url -Detail; if ($x.RelatedGroupId -eq $groupID)
    {$x.RelatedGroupId;$x.url}}
    

Using Graph API

You can try these commands through Graph Explorer.

  1. Use the following to get the list of private channel IDs for a given team, where <group_id> is the group ID of the team. You'll need this in subsequent calls. (You can easily find the group ID in the link to the team).

    Request

    GET https://graph.microsoft.com/beta/teams/<group_id>/channels?$filter=membershipType eq 'private'
    

    Response

    HTTP/1.1 200 OK
    Content-type: application/json
    Content-length:
    
    {
      "value": [
        {
          "description": "description-value",
          "displayName": "display-name-value",
          "id": "channel_id",
          "membershipType": "membership-type-value",
          "isFavoriteByDefault": false,
          "webUrl": "webUrl-value",
          "email": "email-value"
        }
      ]
    }
    
  2. For each private channel which you want to get the SharePoint URL, make the following request, where <channel_id> is the channel ID.

    Request

    GET https://graph.microsoft.com/beta/teams/<group_id>/channels/<channel_id>/filesFolder
    

    Response

    HTTP/1.1 200 OK
    Content-type: application/json
    Content-length:
    
    {
      "value": [
        {
          "description": "description-value",
          "displayName": "display-name-value",
          "id": "channel_id",
          "membershipType": "membership-type-value",
          "isFavoriteByDefault": false,
          "webUrl": "webUrl-value",
          "email": "email-value"
        }
      ]
    }
    

List and update roles of owners and members in a private channel

You may want to list out the owners and members of a private channel to decide whether you need to promote certain members of the private channel to an owner. This can happen when you have owners of private channels who have left the organization and the private channel requires admin help to claim ownership of the channel.

As an admin, you can use the Microsoft Teams admin center, PowerShell, or Graph API to perform these actions.

Using the Microsoft Teams admin center

To learn how to manage team members using the Microsoft Teams admin center, see Manage teams in the Microsoft Teams admin center.

Using PowerShell

  1. Run the following, where <group_id> is the group ID of the team and <channel_name> is the channel name.

    Get-TeamChannelUser -GroupId <group_id> -DisplayName "<channel_name>" 
    
  2. Promote a member to an owner.

    Add-TeamChannelUser -GroupId <group_id> -DisplayName "<channel_name>" -User <UPN> -Role Owner
    

Using Graph API

You can try these commands through Graph Explorer.

  1. Use the following, where <group_id> is the group ID of the team and <channel_id> is the channel ID.

    Request

    GET https://graph.microsoft.com/beta/teams/<group_id>/channels/<channel_id>/members
    

    Response

    HTTP/1.1 200 OK Content-type: application/json
    Content-length: 
    {
          "@odata.context": "https://graph.microsoft.com/beta/$metadata#teams({group_id}')/channels('{channel_id}')/members",
          "@odata.count": 2,
          "value": [
              {
                  "@odata.type": "#microsoft.graph.aadUserConversationMember",
                  "id": "id-value",
                  "roles": [],
                  "displayName": "display-name-value",
                  "userId": "userId-value",
                  "email": "email-value"
              },
              {
                  "@odata.type": "#microsoft.graph.aadUserConversationMember",
              "id": "id-value",
              "roles": ["owner"],
              "displayName": "display-name-value",
              "userId": "userId-value",
              "email": "email-value"
              }
          ]
    }
    
  2. Use the following to promote the member to an owner, where <group_id>, <channel_id>, and <id> are returned from the previous call. Note that <id> and <userId> returned from the previous call aren't the same and aren't interchangeable. Make sure you use <id>.

    Request

    PATCH 
    https://graph.microsoft.com/beta/teams/<group_id>/channels/<channel_id>/members/<id>
    
    {
    "@odata.type": "#microsoft.graph.aadUserConversationMember",
    "roles": ["owner"]
    }
    

    Response

    HTTP/1.1 200 OK
    Content-type: application/json
    
    {
      "@odata.context": "https://graph.microsoft.com/beta/$metadata#teams('{group_id}')/channels('{channel_id}')/members/$entity",
      "@odata.type": "#microsoft.graph.aadUserConversationMember",
      "id": "id-value",
      "roles": ["owner"],
      "displayName": "display-name-value",
      "userId": "userId-value",
      "email": "email-value"
     }