Rooms

Conversations take place in rooms. Rocket.Chat has different types of rooms that can be used for different purposes. For more information, see the Collaborate Using Rooms section.

The room object

Every conversation container — channel, private group, direct message, team main room, or omnichannel conversation — is a room and shares one object shape. A trimmed example from Get Room Information:

{
  "room": {
    "_id": "66ed2dba40141d95f32c292b",
    "name": "new-channel",
    "t": "p",
    "msgs": 3,
    "usersCount": 2,
    "u": { "_id": "C38WSSzrGd2NCjzqJ", "username": "test.cat" },
    "teamId": "66c82d78237405fc05fc1ef1",
    "ro": false,
    "default": false,
    "ts": "2024-09-20T08:09:30.417Z"
  },
  "success": true
}

Fields you use most often:

• _id: The room ID, passed as roomId or rid in requests.

• t: The room type — c public channel, p private group, d direct message, l livechat. The type decides which API manages the room: Channels for c, Groups for p, and the Rooms API for actions that work across all types.

• teamId: Set when the room belongs to a team.

• u: The user who created the room.

This API section includes the following:

Groups API

• 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.

Channels API

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

• Add and remove members in public channels.

• Update members’ roles in public channels.

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

Rooms API

• Perform general room actions—send files, change settings, export room details, and more.

• Create and view room discussions.

• Mark a room as favorite, mute and unmute users, and view other details.

Teams API

• Create public and private teams.

• Manage team members by adding and removing them, and updating member information.

• Convert a team to a channel and add rooms to a team.

Directory API

• Search the workspace directory for users, channels, and teams.

• The actions that you can perform and the details you can view depend on your role and permissions. Additional required permissions are stated in the endpoint descriptions.

• You can learn more about the properties associated with rooms from the Room schema definition.

Common workflows

Invite people to a room with an invite link

1. Find or create an invite for the room, setting how many days it lasts and how many times it can be used.

2. Share the invite link; the recipient joins by using the invite token.

3. List the invites and delete an invite when it should stop working.

Track a user's read state across rooms

1. Get all subscriptions to see every room the user is in, with unread counts and alerts.

2. Mark a room as read or unread to update it.

Conventions

• Endpoints reference rooms by roomId (also seen as rid); Channels and Groups endpoints usually accept roomName too. IDs are safer because names can change.

• Type-specific management lives in the Channels, Groups, and Teams APIs; the Rooms API works across all room types.

• A subscription is the per-user view of a room — unread counts, alerts, and preferences — managed through the Subscriptions API.

• List endpoints support count, offset, sort, and query query parameters.