Menu

Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

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 to 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

Names in Node.js format
sid
sid<RM> Not PII

A system-generated 34-character string that uniquely identifies this resource.

status
enum:room_status Not PII

A string representing the status of the Room. It can be one of in-progress, failed or completed.

dateCreated
date_time<iso8601> Not PII

The date that this resource was created, given as a UTC ISO 8601 Timestamp.

dateUpdated
date_time<iso8601> Not PII

The date that this resource was last updated, given as a UTC ISO 8601 Timestamp.

accountSid
sid<AC> Not PII

The unique ID of the Account associated with this Room.

enableTurn
boolean Not PII

Enable Twilio's Network Traversal TURN service. TURN service is used when direct peer-to-peer media connections cannot be established due to firewall restrictions. When used, TURN bandwidth usage is billed according to Network Traversal Service rates. This setting only applies to Rooms with type peer-to-peer.

uniqueName
string Not PII

A developer-supplied Name of the Room. This 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.

statusCallback
url Not PII

A URL that Twilio sends asynchronous webhook requests to on every Room event. See Status Callbacks for details.

statusCallbackMethod
http_method Not PII

HTTP method Twilio should use when requesting the above URL.

endTime
date_time<iso8601> Not PII

The end time of the Room, given as a UTC ISO 8601 Timestamp.

duration
integer? Not PII

The duration of the Room in seconds.

type
enum:room_type Not PII

Type of Room, either peer-to-peer, group-small or group. Will be group by default.

maxParticipants
integer Not PII

Maximum number of concurrent Participants allowed in the Room.

recordParticipantsOnConnect
boolean Not PII

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

videoCodecs
enum:video_codec[] Not PII

mediaRegion
string Not PII

Region for the media server in Group Rooms. See the available Media RegionsThis feature is not available in peer-to-peer rooms.

url
url Not PII

The absolute URL for this resource.

links
uri_map Not PII

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

              Names in Node.js format
              sid
              Required
              post sid_like<RM> Not PII

              The Room Sid or name that uniquely identifies this resource.

              status
              Required
              post enum:room_status Not PII

              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.

                    
                    
                    
                    

                    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

                    Names in Node.js format
                    enableTurn
                    Optional
                    post boolean Not PII

                    Use Twilio Network Traversal for TURN service. Defaults to true. Only applicable to Rooms with type peer-to-peer.

                    type
                    Optional
                    post enum:room_type Not PII

                    Type of room, either peer-to-peer, group-small or group. Will be group by default.

                    uniqueName
                    Optional
                    post string Not PII

                    Name of the Room. This is unique for in-progress rooms. If not provided, Room name will be set to the Room Sid.

                    statusCallback
                    Optional
                    post url Not PII

                    A URL that Twilio sends asynchronous webhook requests to on every room event. If not provided, status callback events will not be dispatched.

                    statusCallbackMethod
                    Optional
                    post http_method Not PII

                    HTTP method Twilio should use when requesting the above URL. Defaults to POST.

                    maxParticipants
                    Optional
                    post integer Not PII

                    Maximum number of Participants in the Room. Peer-to-peer rooms can have a maximum of 10 Participants. Small Group rooms can have a max of 4 Participants. Group rooms can have a max of 50 Participants

                    recordParticipantsOnConnect
                    Optional
                    post boolean Not PII

                    Start Participant recording when connected. This feature is not available in peer-to-peer rooms.

                    videoCodecs
                    Optional
                    post enum:video_codec[] Not PII

                    An array of video codecs supported when publishing a Track in the Room. VP8 and H264 codecs are supported. This feature is not available in peer-to-peer rooms

                    mediaRegion
                    Optional
                    post string Not PII

                    Region for the media server in Group Rooms. Default region is us1. See the list of available Media Regions.This feature is not available in peer-to-peer rooms.

                    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"

                          
                          
                          
                          
                                
                                
                                
                                
                                      
                                      
                                      
                                      
                                            
                                            
                                            
                                            

                                            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.

                                            Names in Node.js format
                                            status
                                            Optional
                                            get enum:room_status Not PII

                                            Only show Rooms with the given status.

                                            uniqueName
                                            Optional
                                            get string Not PII

                                            Only show Rooms with the provided Name.

                                            dateCreatedAfter
                                            Optional
                                            get date_time<iso8601> Not PII

                                            Only show Rooms that started on or after this date, given as YYYY-MM-DD.

                                            dateCreatedBefore
                                            Optional
                                            get date_time<iso8601> Not PII

                                            Only show Rooms that started before this date, given as YYYY-MM-DD.

                                                  
                                                  
                                                  
                                                  

                                                  Returns a list containing any Rooms with the name DailyStandup.

                                                  Filter Rooms by Status

                                                        
                                                        
                                                        
                                                        
                                                              
                                                              
                                                              
                                                              
                                                              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 browsing the Twilio tag on Stack Overflow.