Rooms

Overview

The notion of a Room is central to StreamWise VPaas Resell Platform. Intuitively, a Room represents a virtual space where end-users communicate. Technically, a Room is a computing resource that provides Real-time Communications (RTC) services to client applications through a set of APIs. A Room is a container for a set of Participants, and each Participant is a client application that connects to a Room.

A Room is a resource that can be created, read, updated, and deleted. A Room is identified by a unique id, and each Room has a set of properties that can be configured.

Room Properties

A room is a resource that can be created, read, updated, and deleted. A room is identified by a unique id, and each room has a set of properties that can be configured. Below is a list of the properties that can be used to define a room.

Room Attributes

Below is a list of the attributes that can be used to define a room.

Property	Description	Example
object	The object type	Room
id	The ID of the room	u6Yh3D
uuid	A universally unique identifier for the room	123-456-abc-edf
ulid	A universally unique lexicographically sortable identifier	123-456-abc-edf
customer_id	The ID of the customer associated with the room	u6Yh3D
account_id	The ID of the account associated with the room	u6Yh3D
subscription_id	The ID of the subscription associated with the room	u6Yh3D
room_name	The name of the room	Business Meeting
status	The status of the room	active
is_public	A boolean indicating whether the room is public	true
room_type	The type of the room	meet
slug	The slug of the room for URL purposes	business-meeting
url	The URL of the room	example.com/rooms/u6Yh3D/business-meeting
room_features	An array of features for the room	See Room Features
room_settings	An array of settings for the room	See Room Settings
room_metadata	An array of metadata for the room	See Room Metadata

Object

The object type is a string that indicates the type of object returned by the API. In this case, the object type is Room.

• Key: object
• Type: string
• Example: Room

ID

The ID is a string that uniquely identifies the room. The ID is generated by the platform and cannot be changed.

• Key: id
• Type: string
• Example: u6Yh3D

UUID

The UUID is a string that uniquely identifies the room. The UUID is generated by the platform and cannot be changed. The UUID of a room is used in most cases to uniquely identify the room across the platform and Service Providers.

• Key: uuid
• Type: string
• Example: 123-456-abc-edf

ULID

The ULID is a universally unique lexically sortable identifier. The ULID is generated by the platform and cannot be changed. The ULID provide a canonically encoded 26 character string that can be used to sort the room in chronological order (due to the time component of the ULID) or to generate time-based shard keys (due to the randomness of the ULID).

• Key: ulid
• Type: string
• Example: 123-456-abc-edf

Customer ID

The ID of the customer associated with the room.

• Key: customer_id
• Type: string
• Example: u6Yh3D

Account ID

The account_id is the id of the account associated with the room.

• Key: account_id
• Type: string
• Example: u6Yh3D

Subscription ID

The subscription_id is the id of the subscription associated with the room.

• Key: subscription_id
• Type: string
• Example: u6Yh3D

Room Name

The room_name is a human-readable string that can be used to identify the room. The name is not unique and can be changed at any time.

• Key: room_name
• Type: string
• Example: Business Meeting

Status

The status of the room is a string that indicates the status of the room. The status can be one of the following values:

• active: The room is active and can be used.

• inactive: The room is inactive and cannot be used.

• Key: status

• Type: string

• Example: active

Is Public

The is_public is a boolean that indicates if the room is public. If the room is public, it can be accessed by anyone using the url of the room. If the room is not public, it can only be accessed through Room Tokens.

Room Type

Depending on the room type, the platform will provide different features and capabilities. Each room can be created with a specific type, and the type cannot be changed after the room is created.

• Key: room_type
• Type: string
• Example: meet

The platform supports the following room types:

• video: Stream Video.
• live: Stream Live.
• meet: Stream Meet.
• simulcast: Stream Simulcast.

Stream Video

Stream Video rooms are used for video on demand services, where the customer upload a video, it is transcoded and made available to the participants to watch in the room. Rooms of type video serve as interface to watch video on demand (VoD).

Stream Live

Stream Live rooms are used for live-streaming/broadcasting video services, where there is no interaction between the broadcaster and the participants, like webinars, live broadcasts etc. Rooms of type live serve as interface to watch live streams by participants.

Meeting

Meeting rooms are used for web conferencing, meetings or there will be interaction between participants. Rooms of type meet serve as interface to participants join a meeting.

Stream Simulcast

Stream Simulcast rooms are used for retransmission, where there is nothing other than the necessary resources and settings to perform the simulcast (restream). Stream Simulcast rooms perform as broker between the ingestor (input source) and the retransmitters (output destinations).

info

Room type is based on the Service Package and respectively to the Subscription associated with the room. Your value is managed by the platform and cannot be changed.

Slug

The slug is a string that can be used to identify the room in URLs. The slug is not unique and can be changed at any time.

• Key: slug
• Type: string
• Example: business-meeting

URL

The url is a string that indicate the unique URL of the room. The URL is generated by the platform and cannot be changed. The URL is composed by the id and slug of the room.

In the case a room is public, the URL can be used to access the room without need to authenticate. If the room is not public, the URL can only be used to access the room with a Room Token.

Room Features

The room_features is a key-value collection composed of various features available for a room. These features, defined by the associated subscription, serve as a blueprint for room resources allocation. With Room Features, it becomes feasible for room owners to customize their room resources, such as participant capacity or session duration. The platform ensures to uphold the limits and quotas determined by the subscription setting.

When a room has custom resource values, the custom resource value is used instead of the resource value defined in the subscription. For example, if the subscription defines that the room can have a maximum of 100 participants, but the room has a custom resource that defines that the room can have a maximum of 50 participants, the custom resource value will be used.

info

If a feature is configured in the room but is not available in the subscription, or has a higher or different value than the subscription, the feature will be ignored.

If a room does not have a customized feature configured, the value will be inherited from the subscription.

Example

Example

Feature Name	Subscription Value	Room Value	Used Value
max_participants	100	50	50
max_duration	60	60	60
recording	true		true

info

To see the list of available features and how they can be used, see Package Features and Subscription Features.

tip

Some room settings can be used with in conjunction to features to create a unique room configuration. For example, you can use the recording feature with the auto_start_recording setting to create a room that automatically starts recording when the meeting starts.

Room Settings

The room_settings is a key-value pairs that store structured data related to room settings. These settings are used to define additional information that can be used to configure the room.

Some room settings can be freely defined, such as description, featured image, etc. Other settings are defined by the room type and your service provider.

A room's settings can be used to define parameters for the service provider. Each service provider may have its own settings.

Example

Example of available configuration parameters for a meet room with a BigBlueButton service provider.

Setting Name	Description	Type	Scope	Example
moderator_only_message	Message to be displayed when a participant tries to join the room as a moderator	string	room provider	Only moderators can join this room
auto_start_recording	Automatically start recording when the meeting starts	boolean	room provider	true

info

Some room settings can be specific for a room type or service provider, please refer to the documentation of the Room Type or Service Providers for more detail about specific settings.

Global Room Settings

The global room settings are settings that can be used in any room type or service provider. These settings are defined by the platform and can be used to configure the room. Below is a list of the current available global room settings.

Setting Name	Description	Type	Example
description	The description of the room	string	This is a business meeting room
featured_image	The featured image of the room	string	https://example.com/featured-image
hero_image	The hero image of the room	string	https://example.com/hero-image

Room Metadata

The room_metadata is a set of key-value pairs that can attached to a room. This can be useful for storing additional information or third-party data, such as a external room ID or any other information that you want to store.

The metadata is stored as a JSON object. The keys are strings and the values can be strings, numbers, booleans, or null.

Example

Example of metadata usage in a room.

Key	Type	Value	Description
room_metadata['external_billing_id']	integer	123	Third-party billing id
room_metadata['external_crm_id']	integer	456	Third-party CRM id

You may store any scalar value (string, integer, float, boolean, etc.) inside the metadata attribute. In addition, one level of nested objects or arrays are allowed.

danger

Since the room_metadata attribute is simply a key-value store (object), all write operations will overwrite the entire object, so be sure to merge existing data on your end when performing updates.

Room Tokens

A room token is a unique string that allows the owner of a room to control user access and participation in the room. A room token can be used to identify a user as a moderator, attendee, or guest.

Each room can have unlimited tokens associated with it. Each token is provided with a set of attributes that define the type of access that will be granted in the room. The token attributes can be used to define the role of the token, the expiration date, the last usage date, etc.

Room Token Attributes

Below is a list of the attributes that can be used to define a room token.

Attribute Name	Description	Type	Example
token	The token string	string	1234567890
role	The role of the token	string	moderator
expires_at	The expiration date of the token	datetime	2021-01-01T00:00:00Z
last_usage	The last usage date of the token	datetime	2021-01-01T00:00:00Z

Token

The token attribute is the unique string used in the URL to identify the room access. The token is generated by the platform and cannot be changed.

• Key: token
• Type: string
• Example: 1234567890

Role

The role attribute is a string that indicates the role of the token. The role can be one of the following values:

• moderator: The token is a Moderator token.

• attendee: The token is a Attendee token.

• guest: The token is a Guest token.

• Key: role

• Type: string

• Example: moderator

Expires At

The expires_at attribute is a datetime that indicates the expiration date of the token. If configured with future date, the token will be valid until the expiration date. If configured with a past date, the token will be invalid. If not set, the token will never expire.

• Key: expires_at
• Type: datetime or null
• Example: 2021-01-01T00:00:00Z

Last Usage

The last_usage attribute is a datetime that indicates the last usage date of the token. The last usage date is updated every time the token is used to access the room.

• Key: last_usage
• Type: datetime or null
• Example: 2021-01-01T00:00:00Z

info

The last_usage attribute is updated every time the token is used to access the room. If the token is not used, the last_usage attribute will not be updated. If the token is used multiple times, the last_usage attribute will be updated with the last usage date, so do not use this attribute to count the number of times the token was used.

Moderator Token

Moderators tokens is defined by the Room Token role moderator. When room is accessed with a moderator token, the user will be granted moderator access to the room. This privileges will allow the user to manage the room resources and participants. Depending on the room type and Service Provider, the privileges will be extended to the service provider too, given the user the ability to manage the service provider resources and participants.

• Key: role
• Value: moderator

Usage Example

Consider the following scenario:

A room of type meet with a BigBlueButton service provider is accessed with a moderator token. The user will be granted as moderator in the room. After start the meeting and get redirect to BigBlueButton, the user will be granted as moderator in the BigBlueButton meeting too. This will allow the user to manage the BigBlueButton meeting resources and participants.

Attendee Token

Attendee tokens is defined by the Room Token role attendee. When room is accessed with a attendee token, the user will be granted attendee access to the room. This privileges will allow the user to join the room as a participant. Depending on the room type and Service Provider, the privileges will be extended to the service provider too, given the user the ability to join the service provider as a participant.

• Key: role
• Value: attendee

Usage Example

Consider the following scenario:

A room of type meet with a BigBlueButton service provider is accessed with a attendee token. The user will be granted as attendee in the room. After start the meeting and get redirect to BigBlueButton, the user will be granted as attendee in the BigBlueButton meeting too. This will allow the user to join the BigBlueButton meeting as a participant.

Guest Token

Guest tokens is defined by the Room Token role guest. When room is accessed with a guest token, the user will be granted guest access to the room. This privileges will allow the user to join the room as a guest. Depending on the room type and Service Provider, the privileges will be extended to the service provider too, given the user the ability to join the service provider as a guest.

• Key: role
• Value: guest

Usage Example

Consider the following scenario:

A room of type meet with a BigBlueButton service provider is accessed with a guest token. The user will be granted as guest in the room. After start the meeting and get redirect to BigBlueButton, the user will be granted as guest in the BigBlueButton meeting too. This will allow the user to join the BigBlueButton meeting as a guest.

Using Room Tokens

Creating Room Tokens

Each Room can have multiple unique tokens with different roles. To create a room token, you need to use the API room token endpoint POST /rooms/{room_id}/tokens with parameters to define the token attributes.

Request Example

POST /rooms/{room_id}/tokens

{
    "role": "moderator",
    "expires_at": "2021-01-01"
}

Response Example

{
  "id": "u6Yh3D",
  "token": "1234567890",
  "role": "moderator",
  "url": "example.com/rooms/{room_id}/{room_slug}?token=1234567890",
  "expires_at": "2021-01-01T00:00:00Z",
  "last_usage": null
}

note

To see more about the Room Token creation, please refer to the API Reference.

Fetching Room Tokens

There is basically two ways to retrieve the room tokens. The first is to use the API room endpoint GET /rooms/{room_id}/tokens to retrieve all the tokens associated with the room.

The second way is using the include query when fetching the room. This will include the tokens associated with the room in the response.

note

For all API method and more information about include query please refer to the API Reference.

Using Room Tokens

To use a room token, you need to append the token string to the room URL. For example, if the room URL is example.com/rooms/u6Yh3D/business-meeting, you need to append the token string to the URL like this example.com/rooms/u6Yh3D/business-meeting?token=1234567890. When fetching the token object from a room, a url attribute with appended token string will be provided.

{
  //..
  "url": "example.com/rooms/u6Yh3D/business-meeting?token=1234567890",
  //...
}

Sharing the URL with the token string will allow the user to access the room with the privileges defined by the token.

About Public Rooms

A public room is a room that can be accessed by anyone using the url of the room. Public rooms are useful for scenarios where you want to allow anyone to join the room without having to authenticate. Basically public rooms can accept guest participants without using of Room Tokens.

When a room is created, it is not public by default. To make a room public, you need to set the is_public attribute to true.

If a room is indicated as public, a guest token will be created and automatically assigned to users that join the room without a token.

Public rooms can be useful for scenarios where you want to allow anyone to join the room without need to manage individual guest tokens or when the individual access control is not required like broadcasting or streaming scenarios.

When a room is not public, access will only occur through individual access tokens. Non-public rooms can still be accessed by guests by creating a token with this access level.

note

To learn more about room access control, see Room Tokens.

Room Access Codes

The room access code is a string that can be used to authenticate a participant in the room, use this as a pin/password room.

Each room can have unlimited access codes associated with it. Each access code is provided with a set of attributes that define the type of access that will be granted in the room. Access code attributes can be used to define the type of access, expiration date, date of last use, etc.

Room Access Code Attributes

Below is a list of the attributes that can be used to define a room access code.

Attribute Name	Description	Type	Example
code	The code string	string	1234567890
role	The role of the code	string	moderator
expires_at	The expiration date of the code	datetime	2021-01-01T00:00:00Z
last_usage	The last usage date of the code	datetime	2021-01-01T00:00:00Z

Code

The code attribute is an unencrypted, unique string per room used to authenticate a participant in the room. Her value can be set by the user or generated by the platform.

unencrypted data

The code attribute is not encrypted and can be seen by anyone with access to the room. Do not use sensitive information as the value of the code attribute.

Role

The role attribute is a string that indicates the role of the code. The role can be one of the following values:

• moderator: The code is a Moderator code.
• attendee: The code is a Participant code.
• guest: The code is a Guest code.

Important Note

An access code can only be used with a Room Token that has the same role. For example, an access code with the role moderator can only be used with a Room Token with the role moderator. If a Room Token with a different role is used, the access code will be rejected.

Expires At

The expires_at attribute is a datetime that indicates the expiration date of the code. If configured with future date, the code will be valid until the expiration date. If configured with a past date, the code will be invalid. If not set, the code will never expire.

Last Usage

The last_usage attribute is a datetime that indicates the last usage date of the code. The last usage date is updated every time the code is used to access the room.

note

The last_usage attribute is updated every time the code is used to access the room. If the code is not used, the last_usage attribute will not be updated. If the code is used multiple times, the last_usage attribute will be updated with the last usage date, so do not use this attribute to count the number of times the code was used.

Moderator Access Code

The moderator access code defined by the attribute moderator. When user authenticate with a moderator access code, they will be the respective role in the room.

Attendee Access Code

The participant access code defined by the attribute attendee. When user authenticate with an attendee access code, they will be the respective role in the room.

Guest Access Code

The guest access code defined by the attribute guest. When user authenticate with a guest access code, they will be the respective role in the room.

Room Status

During the use of a room, the platform will collect information about the state of the room and make this information available in real time.

The endpoint GET /rooms/{room_id}/status is a resource that provides real-time information about the state of a room in the system. It indicates whether a room is currently active (ongoing/online) or not. The status messages and information available will vary based on the type of room and the service provider being used. For instance, a room could be in an "active" state, indicating that there are ongoing activities within it, or it could be in an "inactive" state, suggesting that there are no current activities.

The information available in the room status may vary depending on the type of room and the service provider being used, for example, a room_type meet room with the BigBlueButton service provider will provide room information such as number of participants, number of moderators, number of guests, etc. A room_type video room with the Vimeo service provider will provide room information like number of views, number of comments, number of likes, etc.

Room Users

Rooms can have multiple users associated with them. Each room can have only one owner defined and as default the owner is the default customer user owner.

Rooms users can have different permissions associated with them. The permissions define what the user can do in the room. For example, a user can have the permission to edit the room, or just see the room details.

Permissions are define individually for each room user. The permissions are defined by the room or account owner or by system administrators.

info

Please refer to the Users section for more information about users.

Room Limits and Quotas

Any room can have limits and quotas set on it. These limits and quotas are used to control the resource usage of the room by the customer, enforcing restrictions in determined resources like the number of participants, the duration of the room, the storage used, etc. You can use this limits as part of billing or subscription plans.

Available features and there limits will always depend on what resources the Subscription has, but some room quotas and limits can be managed by Room Features and Room Settings, please refer to there documentation for more details.

Room Management

Platform administrators can manage rooms using the API or the platform administration interface. Administrators can create, edit, delete and list rooms on behalf of customers.

tip

For more information about the Room Management API, please refer to the API Reference.

Room Creation

Creating rooms can be done by platform administrators that has the need permissions granted through the API or the platform administration interface. To create a room, you need to use the API room endpoint POST /rooms with parameters to define the room attributes.

Rooms List

Rooms can be listed by platform administrators that has the need permissions granted through the API or the platform administration interface. To list rooms, you need to use the API room endpoint GET /rooms with query parameters to define room search filters.

API Queries

For all API method and more information about query parameters please refer to the API Resources.

Rooms Details

Rooms can be fetched by platform administrators that has the need permissions granted through the API or the platform administration interface. To fetch a room details, you need to use the API room endpoint GET /rooms/{room_id}.

Rooms Editing

Rooms can be edited by platform administrators that has the need permissions granted through the API or the platform administration interface. To edit a room, you need to use the API room endpoint PATCH /rooms/{room_id} with parameters to define the room attributes.

Rooms Deletion

Rooms can be deleted by platform administrators that has the need permissions granted through the API or the platform administration interface. To delete a room, you need to use the API room endpoint DELETE /rooms/{room_id}.

Room Tokens

Rooms tokens can be created, fetched, edited and deleted by platform administrators that has the need permissions granted through the API or the platform administration interface. To manage room tokens, you need to use the API room token endpoint POST /rooms/{room_id}/tokens, GET /rooms/{room_id}/tokens, PATCH /rooms/{room_id}/tokens/{token_id} and DELETE /rooms/{room_id}/tokens/{token_id}.

Room Access Codes

Rooms access codes can be created, fetched, edited and deleted by platform administrators that has the need permissions granted through the API or the platform administration interface. To manage room access codes, you need to use the API room access code endpoint POST /rooms/{room_id}/access-codes, GET /rooms/{room_id}/access-codes, PATCH /rooms/{room_id}/access-codes/{code_id} and DELETE /rooms/{room_id}/access-codes/{code_id}.