In this guide, we’ll walk you through different concepts to help you manage rooms in your product. Understanding these concepts will help you build experiences that are core to multiplayer products such as share dialogs, paginated overview pages, custom permission flows, and more.
You can call the API Endpoints to manage the rooms.
You can assign custom
metadata to your room. For example, if you have
different types of room experiences, you can store that type as
would then come handy when building an overview page listing all the rooms where
metadata could be used as a filter, making it easy for people to find
what they’re looking for.
One way to edit
metadata is to use the
create room API. In this
example we’re creating a new room with a custom
roomType property, and setting
it to "whiteboard":
We can then use the
get rooms API to retrieve a
list of rooms containing the "whiteboard"
Metadata can be also be used within a number of our other APIs.
Rooms can have different permission types assigned at three different levels: default, groups, and users. The system is flexible enough to enable you to build a permission system that fits your needs. With that, you can build invite flows that drive more people to your product.
Different permission types can be applied:
Full access. Enables people to view and edit the room.
Read access with presence. Enables people to edit their presence, but only
view the room’s storage.
You can also use our APIs to access this information, as well as set it, as we’ll detail below.
Permission types can be applied at three different levels:
Each level further down will override access levels defined above, for example a
room with private access will allow a user with
room:write access to enter.
defaultAccesses level is used to set the default permissions of the entire
When used in our APIs, this property takes an array, with an empty array
signifying no access. Add permission types to this array to define the default
access level to your room.
We can use the create room API to create a new room with public access levels:
The default permission types can later be modified with the update room API, in this example turning the room private:
Default accesses can be also be used within a number of our other APIs.
groupsAccesses level is used to set the default permissions of any given
group within room.
Groups are represented by a
groupId—a custom string that represents a
selection of users in your app. Groups can be attached to a user by passing an
groupId values in
In our APIs you can then set group accesses by using the
groupId as the key,
and an array of permissions as the value.
To allow an "engineering" group access to view a room, and modify their
presence, we can use the
update room API with
engineering as a
To remove a group’s permissions, we can use the
update room API
again, and set the permission type to
Group accesses can be also be used within a number of our other APIs.
usersAccesses level is used to set permissions of any give user within a
To use this, first a user is given a
Then, if you want the user with the
userId id to make edits, set
usersAccesses when creating or updating a room.
To create an invitation system, we can use the
update room API and
use an email address as a
To check a user’s assigned permission types for this room, we can then use the
get room API and
User accesses can be also be used within a number of our other APIs.