Menu

Expand
Rate this page:

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
sid<RM> Not PII

The unique string that we created to identify the Room resource.

status
enum:room_status Not PII

The status of the room. Can be: in-progress, failed, or completed.

date_created
date_time<iso8601> Not PII

The date and time in GMT when the resource was created specified in ISO 8601 format.

date_updated
date_time<iso8601> Not PII

The date and time in GMT when the resource was last updated specified in ISO 8601 format.

account_sid
sid<AC> Not PII

The SID of the Account that created the Room resource.

enable_turn
boolean Not PII

Deprecated, now always considered to be true.

unique_name
string Not PII

An application-defined string that uniquely identifies the resource. It can be used as a room_sid in place of the resource's sid in the URL to address the resource, assuming it does not contain any reserved characters that would need to be URL encoded. This value is unique for in-progress rooms. SDK clients can use this name to connect to the room. REST API clients can use this name in place of the Room SID to interact with the room as long as the room is in-progress.

status_callback
url Not PII

The URL we call using the status_callback_method to send status information to your application on every room event. See Status Callbacks for more info.

status_callback_method
http_method Not PII

The HTTP method we use to call status_callback. Can be POST or GET and defaults to POST.

end_time
date_time<iso8601> Not PII

The UTC end time of the room in ISO 8601 format.

duration
integer? Not PII

The duration of the room in seconds.

type
enum:room_type Not PII

The type of room. Can be: go, peer-to-peer, group-small, or group. The default value is group.

max_participants
integer Not PII

The maximum number of concurrent Participants allowed in the room.

max_participant_duration
integer Not PII

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
integer? Not PII

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
boolean Not PII

Whether to start recording when Participants connect. This feature is not available in peer-to-peer rooms.

video_codecs
enum:video_codec[] Not PII

An array of the video codecs that are supported when publishing a track in the room. Can be: VP8 and H264. This feature is not available in peer-to-peer rooms

media_region
string Not PII

The region for the media server in Group Rooms. Can be: one of the available Media Regions. This feature is not available in peer-to-peer rooms.

audio_only
boolean Not PII

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
integer Not PII

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
integer Not PII

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
url Not PII

The absolute URL of the resource.

links
uri_map Not PII

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
Loading Code Sample...
        
        

        Retrieve an in-progress Room instance by UniqueName

        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
        Loading Code Sample...
              
              

              Retrieve an in-progress or completed Room instance by RoomSid

              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
              post sid_like<RM> Not PII

              The SID of the Room resource to update.

              status
              Required
              post enum:room_status Not PII

              The new status of the resource. Set to completed to end the room.

              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.

              Loading Code Sample...
                    
                    

                    Complete a 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
                    post boolean Not PII

                    Deprecated, now always considered to be true.

                    type
                    Optional
                    post enum:room_type Not PII

                    The type of room. Can be: go, peer-to-peer, group-small, or group. The default value is group.

                    unique_name
                    Optional
                    post string Not PII

                    An application-defined string that uniquely identifies the resource. It can be used as a room_sid in place of the resource's sid in the URL to address the resource, assuming it does not contain any reserved characters that would need to be URL encoded. This value is unique for in-progress rooms. SDK clients can use this name to connect to the room. REST API clients can use this name in place of the Room SID to interact with the room as long as the room is in-progress.

                    status_callback
                    Optional
                    post url Not PII

                    The URL we should call using the status_callback_method to send status information to your application on every room event. See Status Callbacks for more info.

                    status_callback_method
                    Optional
                    post http_method Not PII

                    The HTTP method we should use to call status_callback. Can be POST or GET.

                    max_participants
                    Optional
                    post integer Not PII

                    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
                    post boolean Not PII

                    Whether to start recording when Participants connect. This feature is not available in peer-to-peer rooms.

                    video_codecs
                    Optional
                    post enum:video_codec[] Not PII

                    An array of the video codecs that are supported when publishing a track in the room. Can be: VP8 and H264. This feature is not available in peer-to-peer rooms

                    media_region
                    Optional
                    post string Not PII

                    The region for the media server in Group Rooms. Can be: one of the available Media Regions. This feature is not available in peer-to-peer rooms.

                    recording_rules
                    Optional
                    post object Not PII

                    A collection of Recording Rules that describe how to include or exclude matching tracks for recording

                    audio_only
                    Optional
                    post boolean Not PII

                    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
                    post integer Not PII

                    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
                    post integer Not PII

                    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
                    post integer Not PII

                    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"

                    Loading Code Sample...
                          
                          

                          Create a Room

                          Loading Code Sample...
                                
                                

                                Create a Peer-to-Peer Room

                                Loading Code Sample...
                                      
                                      

                                      Create a Group Room with recordings enabled

                                      Loading Code Sample...
                                            
                                            

                                            Create an Audio-Only Group Room

                                            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.

                                            Loading Code Sample...
                                                  
                                                  

                                                  Create a Room with a 60 Minute Empty Room Timeout

                                                  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
                                                  get enum:room_status Not PII

                                                  Read only the rooms with this status. Can be: in-progress (default) or completed

                                                  unique_name
                                                  Optional
                                                  get string Not PII

                                                  Read only rooms with the this unique_name.

                                                  date_created_after
                                                  Optional
                                                  get date_time<iso8601> Not PII

                                                  Read only rooms that started on or after this date, given as YYYY-MM-DD.

                                                  date_created_before
                                                  Optional
                                                  get date_time<iso8601> Not PII

                                                  Read only rooms that started before this date, given as YYYY-MM-DD.

                                                  Loading Code Sample...
                                                        
                                                        
                                                        Retrieve a list of completed Rooms by UniqueName

                                                        Retrieve a list of Rooms by UniqueName

                                                        Retrieve a list of completed Rooms by UniqueName

                                                        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

                                                        Loading Code Sample...
                                                              
                                                              

                                                              Retrieve a list of Rooms by Status

                                                              Loading Code Sample...
                                                                    
                                                                    

                                                                    Retrieve a list of completed Rooms

                                                                    Loading Code Sample...
                                                                          
                                                                          

                                                                          Configure the maximum Participant duration

                                                                          Rate this page:

                                                                          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.

                                                                          Loading Code Sample...
                                                                                
                                                                                
                                                                                

                                                                                Thank you for your feedback!

                                                                                Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

                                                                                Sending your feedback...
                                                                                🎉 Thank you for your feedback!
                                                                                Something went wrong. Please try again.

                                                                                Thanks for your feedback!

                                                                                thanks-feedback-gif