Rooms

With the Rooms API, you can:

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

For details, you can refer to the Room Options user guide.

The room object

Rooms endpoints work with any room type through one shared object. 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",
    "lm": "2024-09-20T12:27:53.356Z"
  },
  "success": true
}

Fields you use most often:

• _id: The room ID, passed as roomId in requests. Rooms endpoints identify rooms by ID, not name.

• t: The room type — c public channel, p private group, d direct message, l livechat. Rooms endpoints accept all types.

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

• lm: The timestamp of the last message.

Common workflows

Share a file in a room

1. Upload the media file to get a file ID.

2. Send the uploaded file to the room as a message.

3. Delete the uploaded file if you need to withdraw it.

Organize a busy room

1. Create a discussion to branch a topic into its own room.

2. Mark the room as favorite and tune its notifications.

3. Mute a user who is disrupting the conversation.

Clean up or retire a room

1. Clear room history for a time range, or export the room first to keep a record.

2. Archive the room, or delete it permanently.

Conventions

• These endpoints work across all room types. Type-specific management lives in the Channels, Groups, and Teams APIs.

• Rooms endpoints identify rooms by roomId. Use Get Rooms to list the rooms you belong to and find IDs.

• Administrative actions such as clearing history or viewing any room require permissions like clean-channel-history or admin room access; each endpoint page lists its requirements.