REST API: Rooms
Overview
The Programmable Video Rooms resource represents a communications session among multiple endpoints using one of Twilio’s Programmable Video SDKs. Connected users (Participants) can share video and audio Tracks with the Room, and receive video and audio Tracks from other Participants in the Room.
The Rooms resource lets you dynamically create and complete Rooms, and configure a Room’s topology and behavior. Use this API to set Room properties such as its name, type, TURN configuration, webhook status callback URL, and the maximum number of Participants.
All Programmable Video REST API resources use the following base URL.
https://video.twilio.com
Contents
Room Instance Resource
Resource URI
/v1/Rooms/{RoomNameOrSid}
Resource Properties
Resource Properties in REST API format | |
---|---|
sid
|
The unique string that we created to identify the Room resource. |
status
|
The status of the room. Can be: |
date_created
|
The date and time in GMT when the resource was created specified in ISO 8601 format. |
date_updated
|
The date and time in GMT when the resource was last updated specified in ISO 8601 format. |
account_sid
|
The SID of the Account that created the Room resource. |
enable_turn
|
Deprecated, now always considered to be true. |
unique_name
|
An application-defined string that uniquely identifies the resource. It can be used as a |
status_callback
|
The URL we call using the |
status_callback_method
|
The HTTP method we use to call |
end_time
|
The UTC end time of the room in ISO 8601 format. |
duration
|
The duration of the room in seconds. |
type
|
The type of room. Can be: |
max_participants
|
The maximum number of concurrent Participants allowed in the room. |
max_participant_duration
|
The maximum number of seconds a Participant can be connected to the room. The maximum possible value is 86400 seconds (24 hours). The default is 14400 seconds (4 hours). |
max_concurrent_published_tracks
|
The maximum number of published audio, video, and data tracks all participants combined are allowed to publish in the room at the same time. Check Programmable Video Limits for more details. If it is set to 0 it means unconstrained. |
record_participants_on_connect
|
Whether to start recording when Participants connect. This feature is not available in |
video_codecs
|
An array of the video codecs that are supported when publishing a track in the room. Can be: |
media_region
|
The region for the media server in Group Rooms. Can be: one of the available Media Regions. This feature is not available in |
audio_only
|
When set to true, indicates that the participants in the room will only publish audio. No video tracks will be allowed. Group rooms only. |
empty_room_timeout
|
Specifies how long (in minutes) a room will remain active after last participant leaves. Can be configured when creating a room via REST API. For Ad-Hoc rooms this value cannot be changed. |
unused_room_timeout
|
Specifies how long (in minutes) a room will remain active if no one joins. Can be configured when creating a room via REST API. For Ad-Hoc rooms this value cannot be changed. |
url
|
The absolute URL of the resource. |
links
|
The URLs of related resources. |
HTTP GET
Returns a single Room resource represented by {RoomNameOrSid}
.
Retrieve an in-progress
Room instance by UniqueName
You can retrieve an in-progress
Room instance object using the Room’s UniqueName
, assuming the UniqueName
does not contain any reserved characters that would need to be URL encoded. This makes it easier to interact with Twilio’s REST API without having to keep track of Twilio’s Room SID identifiers.
For example:
GET /Rooms/DailyStandup
Will return the Room instance object for the Room DailyStandup
if the room is currently in-progress
. If no Room exists by the name DailyStandup
, or a Room by that name is only in completed
status, the above request will return an HTTP 404 response.
Retrieve an in-progress
or completed
Room instance by RoomSid
A Room’s Sid
property is Twilio’s own canonical unique identifier for a Room. You can always use the Room Sid
to retrieve the Room, whether the room is in-progress
or completed
.
For example:
GET /Rooms/RMxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Will return the Room instance object for the Room with Sid
RMxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
, regardless of its status. If no Room exists with that Sid, the above request will return an HTTP 404 response.
HTTP POST
Modifies a Room resource.
Supported POST parameters
Parameters in REST API format | |
---|---|
sid
Path
|
The SID of the Room resource to update. |
status
Required
|
The new status of the resource. Set to |
Complete a Room
Update a Room’s status to completed
with the following request to end the Room. All connected
Participants will be immediately disconnected from the Room.
Rooms List Resource
Resource URI
/v1/Rooms
HTTP POST
Create a new Room with an HTTP POST to the Rooms list resource.
Supported POST parameters
Parameters in REST API format | |
---|---|
enable_turn
Optional
|
Deprecated, now always considered to be true. |
type
Optional
|
The type of room. Can be: |
unique_name
Optional
|
An application-defined string that uniquely identifies the resource. It can be used as a |
status_callback
Optional
|
The URL we should call using the |
status_callback_method
Optional
|
The HTTP method we should use to call |
max_participants
Optional
|
The maximum number of concurrent Participants allowed in the room. Peer-to-peer rooms can have up to 10 Participants. Small Group rooms can have up to 4 Participants. Group rooms can have up to 50 Participants. |
record_participants_on_connect
Optional
|
Whether to start recording when Participants connect. This feature is not available in |
video_codecs
Optional
|
An array of the video codecs that are supported when publishing a track in the room. Can be: |
media_region
Optional
|
The region for the media server in Group Rooms. Can be: one of the available Media Regions. This feature is not available in |
recording_rules
Optional
|
A collection of Recording Rules that describe how to include or exclude matching tracks for recording |
audio_only
Optional
|
When set to true, indicates that the participants in the room will only publish audio. No video tracks will be allowed. Group rooms only. |
max_participant_duration
Optional
|
The maximum number of seconds a Participant can be connected to the room. The maximum possible value is 86400 seconds (24 hours). The default is 14400 seconds (4 hours). |
empty_room_timeout
Optional
|
Configures how long (in minutes) a room will remain active after last participant leaves. Valid values range from 1 to 60 minutes (no fractions). |
unused_room_timeout
Optional
|
Configures how long (in minutes) a room will remain active if no one joins. Valid values range from 1 to 60 minutes (no fractions). |
Note: Rooms created via the REST API exist for five minutes to allow the first Participant to connect. If no Participants join within five minutes, the Room times out and a new Room must be created.
Example 1: Create a Room called "DailyStandup"
Example 5: Create a Room with a 60 minute empty room timeout
By default, a Room will end five minutes after the last participant disconnects from the Room. You can configure this to be a different value up to 60 minutes when you create the Room via the REST API. The value is specified in minutes.
The example below demonstrates configuring the Room's empty room timeout value. Note that you can also configure with the Room's unused room timeout value in the same way. The unused room timeout determines how long to wait before ending the Room if no participants join.
Once a Room is created, generate an Access Token containing the Room name and use one of Twilio’s Video SDKs to connect to the Room.
For example, using the JavaScript SDK:
Twilio.Video.connect('$AccessTokenContainingRoomName').then(function(room) {
console.log('Successfully joined a Room: ', room);
}, function(error) {
console.error('Unable to connect to Room: ' + error.message);
});
HTTP GET
Returns a list of Room resources created in the given account. The list includes paging information.
List Filters
The following GET query string parameters allow you to limit the list returned. Note, parameters are case-sensitive.
Parameters in REST API format | |
---|---|
status
Optional
|
Read only the rooms with this status. Can be: |
unique_name
Optional
|
Read only rooms with the this |
date_created_after
Optional
|
Read only rooms that started on or after this date, given as |
date_created_before
Optional
|
Read only rooms that started before this date, given as |
Returns a list containing any completed
Rooms with the name DailyStandup
. Note that the status
parameter defaults to in-progress
. If no status
is provided, this endpoint will return a list containing only in-progress
rooms with the name DailyStandup
.
Filter Rooms by Status
Need some help?
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.