Groups (Private Channels)

Groups (or private rooms) are closed rooms, and users can join only if added to the private room. With the Groups API, you can:

• Create and manage the status of private channels—archive, unarchive, encrypt, set announcements, and more.

• Add and remove members in private channels.

• Update members’ roles in private channels.

• View information such as members, integrations, messages, and files.

For more details, refer to the Collaborate Using Rooms user guide.

The group object

Group endpoints return a group object. A trimmed example from Get Group Information:

{
  "group": {
    "_id": "ByehQjC44FwMeiLbX",
    "name": "testing",
    "t": "p",
    "msgs": 0,
    "usersCount": 2,
    "u": { "_id": "HKKPmF8rZh45GMHWH", "username": "marc.anp" },
    "broadcast": false,
    "encrypted": false,
    "ro": false,
    "ts": "2020-05-21T13:16:24.749Z"
  },
  "success": true
}

Fields you use most often:

• _id: The room ID. Pass it as roomId in requests; most group endpoints also accept roomName.

• t: The room type — always p for a private group. Public channels are c.

• encrypted: Whether end-to-end encryption is on for the group.

• u: The user who created the group.

Common workflows

Set up a private space for a team

1. Create the group with a name and initial members.

2. Invite more users as the team grows.

3. Enable encryption if the conversation needs end-to-end protection.

Moderate a group

1. Add an owner or moderator to delegate control.

2. Set the group read-only or set an announcement to steer the conversation.

3. Remove a user when needed.

Wind a group down

1. Archive the group to freeze it while keeping its history, or convert it to a team.

2. Delete the group to remove it permanently.

Conventions

• Most endpoints accept either roomId or roomName. Using roomId is safer because group names can change.

• Creating groups requires the create-p permission. You can only see and manage groups you are a member of, unless you hold admin-level room permissions.

• List endpoints such as Get Groups support count, offset, sort, and query query parameters.

• These endpoints manage private channels only. For public channels, use the Channels API.