Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

REST API: Rooms


(warning)

Warning

This page is for reference only. We are no longer onboarding new customers to Programmable Video. Existing customers can continue to use the product until December 5, 2024(link takes you to an external page).
We recommend migrating your application to the API provided by our preferred video partner, Zoom. We've prepared this migration guide(link takes you to an external page) to assist you in minimizing any service disruption.


Overview

overview page anchor

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.


_10
https://video.twilio.com

Contents

contents page anchor


_10
/v1/Rooms/{RoomNameOrSid}

Resource properties
sidtype: SID<RM>Not PII

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


statustype: enum<STRING>Not PII

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

Possible values:
in-progresscompletedfailed

date_createdtype: string<DATE TIME>Not PII

The date and time in GMT when the resource was created specified in ISO 8601(link takes you to an external page) format.


date_updatedtype: string<DATE TIME>Not PII

The date and time in GMT when the resource was last updated specified in ISO 8601(link takes you to an external page) format.


account_sidtype: SID<AC>Not PII

The SID of the Account(link takes you to an external page) that created the Room resource.


enable_turntype: booleanNot PII

Deprecated, now always considered to be true.


unique_nametype: stringNot 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(link takes you to an external page) 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_callbacktype: string<URI>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(link takes you to an external page) for more info.


status_callback_methodtype: enum<HTTP METHOD>Not PII

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

Possible values:
HEADGETPOSTPATCHPUTDELETE

end_timetype: string<DATE TIME>Not PII

The UTC end time of the room in ISO 8601(link takes you to an external page) format.


durationtype: integerNot PII

The duration of the room in seconds.


typetype: enum<STRING>Not PII

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

Possible values:
gopeer-to-peergroupgroup-small

max_participantstype: integerNot PII

The maximum number of concurrent Participants allowed in the room.


max_participant_durationtype: integerNot 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_trackstype: integerNot 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(link takes you to an external page) for more details. If it is set to 0 it means unconstrained.


record_participants_on_connecttype: booleanNot PII

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


video_codecstype: string[]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

Possible values:
VP8H264

media_regiontype: stringNot PII

The region for the media server in Group Rooms. Can be: one of the available Media Regions(link takes you to an external page). This feature is not available in peer-to-peer rooms.


audio_onlytype: booleanNot 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_timeouttype: integerNot 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_timeouttype: integerNot 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.


large_roomtype: booleanNot PII

Indicates if this is a large room.


urltype: string<URI>Not PII

The absolute URL of the resource.


linkstype: object<URI MAP>Not PII

The URLs of related resources.

HTTP GET

get-instance page anchor

Returns a single Room resource represented by {RoomNameOrSid} .

Retrieve an in-progress Room instance by UniqueName

get-by-unique-name page anchor

You can retrieve an in-progress Room instance object using the Room's UniqueName, assuming the UniqueName does not contain any reserved characters(link takes you to an external page) 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:


_10
GET /Rooms/DailyStandup

Retrieve an in-progress Room instance by UniqueName

retrieve-an-in-progress-room-instance-by-uniquename page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.video.v1.rooms('DailyStandup')
_10
.fetch()
_10
.then(room => console.log(room.uniqueName));

Output

_32
{
_32
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"date_created": "2015-07-30T20:00:00Z",
_32
"date_updated": "2015-07-30T20:00:00Z",
_32
"status": "in-progress",
_32
"type": "peer-to-peer",
_32
"sid": "RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"enable_turn": true,
_32
"unique_name": "unique_name",
_32
"max_participants": 10,
_32
"max_participant_duration": 86400,
_32
"max_concurrent_published_tracks": 0,
_32
"duration": 0,
_32
"status_callback_method": "POST",
_32
"status_callback": null,
_32
"record_participants_on_connect": false,
_32
"video_codecs": [
_32
"VP8"
_32
],
_32
"audio_only": false,
_32
"media_region": "us1",
_32
"empty_room_timeout": 5,
_32
"unused_room_timeout": 5,
_32
"end_time": "2015-07-30T20:00:00Z",
_32
"large_room": false,
_32
"url": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"links": {
_32
"participants": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants",
_32
"recordings": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Recordings",
_32
"recording_rules": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/RecordingRules"
_32
}
_32
}

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

get-by-sid page anchor

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:


_10
GET /Rooms/RMxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Retrieve an in-progress or completed Room instance by RoomSid

retrieve-an-in-progress-or-completed-room-instance-by-roomsid page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.video.v1.rooms('RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.fetch()
_10
.then(room => console.log(room.uniqueName));

Output

_32
{
_32
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"date_created": "2015-07-30T20:00:00Z",
_32
"date_updated": "2015-07-30T20:00:00Z",
_32
"status": "in-progress",
_32
"type": "peer-to-peer",
_32
"sid": "RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"enable_turn": true,
_32
"unique_name": "unique_name",
_32
"max_participants": 10,
_32
"max_participant_duration": 86400,
_32
"max_concurrent_published_tracks": 0,
_32
"duration": 0,
_32
"status_callback_method": "POST",
_32
"status_callback": null,
_32
"record_participants_on_connect": false,
_32
"video_codecs": [
_32
"VP8"
_32
],
_32
"audio_only": false,
_32
"media_region": "us1",
_32
"empty_room_timeout": 5,
_32
"unused_room_timeout": 5,
_32
"end_time": "2015-07-30T20:00:00Z",
_32
"large_room": false,
_32
"url": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"links": {
_32
"participants": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants",
_32
"recordings": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Recordings",
_32
"recording_rules": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/RecordingRules"
_32
}
_32
}

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.

Modifies a Room resource.

Supported POST parameters

URI parameters
Sidtype: stringNot PII
Path Parameter

The SID of the Room resource to update.


Request body parameters
Statustype: enum<STRING>Not PII
Required

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

Possible values:
in-progresscompletedfailed

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.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.video.v1.rooms('RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.update({status: 'completed'})
_10
.then(room => console.log(room.uniqueName));

Output

_32
{
_32
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"date_created": "2015-07-30T20:00:00Z",
_32
"date_updated": "2015-07-30T20:00:00Z",
_32
"status": "completed",
_32
"type": "peer-to-peer",
_32
"sid": "RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"enable_turn": true,
_32
"unique_name": "unique_name",
_32
"max_participants": 10,
_32
"max_participant_duration": 86400,
_32
"max_concurrent_published_tracks": 10,
_32
"status_callback_method": "POST",
_32
"status_callback": null,
_32
"record_participants_on_connect": false,
_32
"video_codecs": [
_32
"VP8"
_32
],
_32
"media_region": "us1",
_32
"audio_only": false,
_32
"empty_room_timeout": 5,
_32
"unused_room_timeout": 5,
_32
"end_time": "2015-07-30T20:00:00Z",
_32
"large_room": false,
_32
"duration": 10,
_32
"url": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"links": {
_32
"participants": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants",
_32
"recordings": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Recordings",
_32
"recording_rules": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/RecordingRules"
_32
}
_32
}



_10
/v1/Rooms

Create a new Room with an HTTP POST to the Rooms list resource.

Supported POST parameters

post-parameters page anchor
Request body parameters
EnableTurntype: booleanNot PII

Deprecated, now always considered to be true.


Typetype: enum<STRING>Not PII

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

Possible values:
gopeer-to-peergroupgroup-small

UniqueNametype: stringNot 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(link takes you to an external page) 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.


StatusCallbacktype: string<URI>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(link takes you to an external page) for more info.


StatusCallbackMethodtype: enum<HTTP METHOD>Not PII

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

Possible values:
HEADGETPOSTPATCHPUTDELETE

MaxParticipantstype: integerNot 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.


RecordParticipantsOnConnecttype: booleanNot PII

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


VideoCodecstype: string[]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

Possible values:
VP8H264

MediaRegiontype: stringNot PII

The region for the media server in Group Rooms. Can be: one of the available Media Regions(link takes you to an external page). This feature is not available in peer-to-peer rooms.


RecordingRulestype: objectNot PII

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


AudioOnlytype: booleanNot 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.


MaxParticipantDurationtype: integerNot 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).


EmptyRoomTimeouttype: integerNot 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).


UnusedRoomTimeouttype: integerNot 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).


LargeRoomtype: booleanNot PII

When set to true, indicated that this is the large room.

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"

create-room page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.video.v1.rooms.create({uniqueName: 'DailyStandup'})
_10
.then(room => console.log(room.sid));

Output

_32
{
_32
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"date_created": "2015-07-30T20:00:00Z",
_32
"date_updated": "2015-07-30T20:00:00Z",
_32
"status": "in-progress",
_32
"type": "peer-to-peer",
_32
"sid": "RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"enable_turn": true,
_32
"unique_name": "DailyStandup",
_32
"max_concurrent_published_tracks": 0,
_32
"max_participants": 10,
_32
"max_participant_duration": 86400,
_32
"duration": 0,
_32
"status_callback_method": "POST",
_32
"status_callback": null,
_32
"record_participants_on_connect": false,
_32
"video_codecs": [
_32
"VP8"
_32
],
_32
"media_region": "us1",
_32
"audio_only": false,
_32
"empty_room_timeout": 5,
_32
"unused_room_timeout": 5,
_32
"end_time": "2015-07-30T20:00:00Z",
_32
"large_room": false,
_32
"url": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"links": {
_32
"participants": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants",
_32
"recordings": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Recordings",
_32
"recording_rules": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/RecordingRules"
_32
}
_32
}

Example 2: Create a Peer-to-Peer Room called SalesMeeting with the Status Callback URL set

example-2-create-a-peer-to-peer-room-called-salesmeeting-with-the-status-callback-url-set page anchor

Create a Peer-to-Peer Room

create-a-peer-to-peer-room page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_14
// Download the helper library from https://www.twilio.com/docs/node/install
_14
// Find your Account SID and Auth Token at twilio.com/console
_14
// and set the environment variables. See http://twil.io/secure
_14
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_14
const authToken = process.env.TWILIO_AUTH_TOKEN;
_14
const client = require('twilio')(accountSid, authToken);
_14
_14
client.video.v1.rooms
_14
.create({
_14
statusCallback: 'http://example.org',
_14
type: 'peer-to-peer',
_14
uniqueName: 'SalesMeeting'
_14
})
_14
.then(room => console.log(room.sid));

Output

_32
{
_32
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"date_created": "2015-07-30T20:00:00Z",
_32
"date_updated": "2015-07-30T20:00:00Z",
_32
"status": "in-progress",
_32
"type": "peer-to-peer",
_32
"sid": "RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"enable_turn": true,
_32
"unique_name": "SalesMeeting",
_32
"max_concurrent_published_tracks": 0,
_32
"max_participants": 10,
_32
"max_participant_duration": 86400,
_32
"duration": 0,
_32
"status_callback_method": "POST",
_32
"status_callback": "http://example.org",
_32
"record_participants_on_connect": false,
_32
"video_codecs": [
_32
"VP8"
_32
],
_32
"media_region": "us1",
_32
"audio_only": false,
_32
"empty_room_timeout": 5,
_32
"unused_room_timeout": 5,
_32
"end_time": "2015-07-30T20:00:00Z",
_32
"large_room": false,
_32
"url": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"links": {
_32
"participants": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants",
_32
"recordings": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Recordings",
_32
"recording_rules": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/RecordingRules"
_32
}
_32
}

Example 3: Create a Group Room, enable Recording, and set a Status Callback URL

example-3-create-a-group-room-enable-recording-and-set-a-status-callback-url page anchor

Create a Group Room with recordings enabled

create-a-group-room-with-recordings-enabled page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_15
// Download the helper library from https://www.twilio.com/docs/node/install
_15
// Find your Account SID and Auth Token at twilio.com/console
_15
// and set the environment variables. See http://twil.io/secure
_15
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_15
const authToken = process.env.TWILIO_AUTH_TOKEN;
_15
const client = require('twilio')(accountSid, authToken);
_15
_15
client.video.v1.rooms
_15
.create({
_15
recordParticipantsOnConnect: true,
_15
statusCallback: 'http://example.org',
_15
type: 'group',
_15
uniqueName: 'DailyStandup'
_15
})
_15
.then(room => console.log(room.sid));

Output

_32
{
_32
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"date_created": "2015-07-30T20:00:00Z",
_32
"date_updated": "2015-07-30T20:00:00Z",
_32
"status": "in-progress",
_32
"type": "group",
_32
"sid": "RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"enable_turn": true,
_32
"unique_name": "DailyStandup",
_32
"max_participants": 50,
_32
"max_participant_duration": 86400,
_32
"max_concurrent_published_tracks": 170,
_32
"duration": 0,
_32
"status_callback_method": "POST",
_32
"status_callback": "http://example.org",
_32
"record_participants_on_connect": true,
_32
"video_codecs": [
_32
"VP8"
_32
],
_32
"media_region": "us1",
_32
"audio_only": false,
_32
"empty_room_timeout": 5,
_32
"unused_room_timeout": 5,
_32
"end_time": "2015-07-30T20:00:00Z",
_32
"large_room": false,
_32
"url": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"links": {
_32
"participants": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants",
_32
"recordings": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Recordings",
_32
"recording_rules": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/RecordingRules"
_32
}
_32
}

Example 4: Create an Audio-Only Group Room

example-4-create-an-audio-only-group-room page anchor

Create an Audio-Only Group Room

create-an-audio-only-group-room page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_14
// Download the helper library from https://www.twilio.com/docs/node/install
_14
// Find your Account SID and Auth Token at twilio.com/console
_14
// and set the environment variables. See http://twil.io/secure
_14
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_14
const authToken = process.env.TWILIO_AUTH_TOKEN;
_14
const client = require('twilio')(accountSid, authToken);
_14
_14
client.video.v1.rooms
_14
.create({
_14
audioOnly: true,
_14
uniqueName: 'Audio-Only Call',
_14
type: 'group'
_14
})
_14
.then(room => console.log(room.sid));

Output

_32
{
_32
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"date_created": "2015-07-30T20:00:00Z",
_32
"date_updated": "2015-07-30T20:00:00Z",
_32
"status": "in-progress",
_32
"type": "group",
_32
"sid": "RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"enable_turn": true,
_32
"unique_name": "Audio-Only Call",
_32
"max_concurrent_published_tracks": 0,
_32
"max_participants": 10,
_32
"max_participant_duration": 86400,
_32
"duration": 0,
_32
"status_callback_method": "POST",
_32
"status_callback": null,
_32
"record_participants_on_connect": false,
_32
"video_codecs": [
_32
"VP8"
_32
],
_32
"media_region": "us1",
_32
"audio_only": true,
_32
"empty_room_timeout": 5,
_32
"unused_room_timeout": 5,
_32
"end_time": "2015-07-30T20:00:00Z",
_32
"large_room": false,
_32
"url": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"links": {
_32
"participants": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants",
_32
"recordings": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Recordings",
_32
"recording_rules": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/RecordingRules"
_32
}
_32
}

Example 5: Create a Room with a 60 minute empty room timeout

example-5-create-a-room-with-a-60-minute-empty-room-timeout page anchor

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.

Create a Room with a 60 Minute Empty Room Timeout

create-a-room-with-a-60-minute-empty-room-timeout page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.video.v1.rooms
_10
.create({uniqueName: 'DailyStandup', emptyRoomTimeout: 60})
_10
.then(room => console.log(room.sid));

Output

_32
{
_32
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"date_created": "2015-07-30T20:00:00Z",
_32
"date_updated": "2015-07-30T20:00:00Z",
_32
"status": "in-progress",
_32
"type": "peer-to-peer",
_32
"sid": "RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"enable_turn": true,
_32
"unique_name": "DailyStandup",
_32
"max_concurrent_published_tracks": 0,
_32
"max_participants": 10,
_32
"max_participant_duration": 86400,
_32
"duration": 0,
_32
"status_callback_method": "POST",
_32
"status_callback": null,
_32
"record_participants_on_connect": false,
_32
"video_codecs": [
_32
"VP8"
_32
],
_32
"media_region": "us1",
_32
"audio_only": false,
_32
"empty_room_timeout": 60,
_32
"unused_room_timeout": 5,
_32
"end_time": "2015-07-30T20:00:00Z",
_32
"large_room": false,
_32
"url": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"links": {
_32
"participants": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants",
_32
"recordings": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Recordings",
_32
"recording_rules": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/RecordingRules"
_32
}
_32
}

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:


_10
Twilio.Video.connect('$AccessTokenContainingRoomName').then(function(room) {
_10
console.log('Successfully joined a Room: ', room);
_10
}, function(error) {
_10
console.error('Unable to connect to Room: ' + error.message);
_10
});

Returns a list of Room resources created in the given account. The list includes paging information.

The following GET query string parameters allow you to limit the list returned. Note, parameters are case-sensitive.

URI parameters
Statustype: enum<STRING>Not PII
Query Parameter

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

Possible values:
in-progresscompletedfailed

UniqueNametype: stringNot PII
Query Parameter

Read only rooms with the this unique_name.


DateCreatedAftertype: string<DATE TIME>Not PII
Query Parameter

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


DateCreatedBeforetype: string<DATE TIME>Not PII
Query Parameter

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


PageSizetype: integerNot PII
Query Parameter

How many resources to return in each list page. The default is 50, and the maximum is 1000.


Pagetype: integerNot PII
Query Parameter

The page index. This value is simply for client state.


PageTokentype: stringNot PII
Query Parameter

The page token. This is provided by the API.

Filter Rooms by UniqueName

filter-by-unique-name page anchor

Retrieve a list of Rooms by UniqueName

retrieve-a-list-of-rooms-by-uniquename page anchor

Retrieve a list of completed Rooms by UniqueName

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_14
// Download the helper library from https://www.twilio.com/docs/node/install
_14
// Find your Account SID and Auth Token at twilio.com/console
_14
// and set the environment variables. See http://twil.io/secure
_14
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_14
const authToken = process.env.TWILIO_AUTH_TOKEN;
_14
const client = require('twilio')(accountSid, authToken);
_14
_14
client.video.v1.rooms
_14
.list({
_14
uniqueName: 'DailyStandup',
_14
status: 'completed',
_14
limit: 20
_14
})
_14
.then(rooms => rooms.forEach(r => console.log(r.sid)));

Output

_45
{
_45
"rooms": [
_45
{
_45
"sid": "RM4070b618362c1682b2385b1f9982833c",
_45
"status": "completed",
_45
"date_created": "2017-04-03T22:21:49Z",
_45
"date_updated": "2017-04-03T22:21:51Z",
_45
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_45
"type": "peer-to-peer",
_45
"enable_turn": true,
_45
"unique_name": "RM4070b618362c1682b2385b1f9982833c",
_45
"status_callback": null,
_45
"status_callback_method": "POST",
_45
"end_time": "2017-04-03T22:21:51Z",
_45
"duration": 2,
_45
"max_participants": 10,
_45
"max_participant_duration": 86400,
_45
"max_concurrent_published_tracks": 10,
_45
"record_participants_on_connect": false,
_45
"video_codecs": [
_45
"VP8"
_45
],
_45
"media_region": "us1",
_45
"audio_only": false,
_45
"empty_room_timeout": 5,
_45
"unused_room_timeout": 5,
_45
"large_room": false,
_45
"url": "https://video.twilio.com/v1/Rooms/RM4070b618362c1682b2385b1f9982833c",
_45
"links": {
_45
"participants": "https://video.twilio.com/v1/Rooms/RM4070b618362c1682b2385b1f9982833c/Participants",
_45
"recordings": "https://video.twilio.com/v1/Rooms/RM4070b618362c1682b2385b1f9982833c/Recordings",
_45
"recording_rules": "https://video.twilio.com/v1/Rooms/RM4070b618362c1682b2385b1f9982833c/RecordingRules"
_45
}
_45
}
_45
],
_45
"meta": {
_45
"page": 0,
_45
"page_size": 50,
_45
"first_page_url": "https://video.twilio.com/v1/Rooms?Status=completed&PageSize=50&Page=0",
_45
"previous_page_url": "https://video.twilio.com/v1/Rooms?Status=completed&PageSize=50&Page=0",
_45
"url": "https://video.twilio.com/v1/Rooms?Status=completed&PageSize=50&Page=0",
_45
"next_page_url": "https://video.twilio.com/v1/Rooms?Status=completed&PageSize=50&Page=1",
_45
"key": "rooms"
_45
}
_45
}

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

filter-by-status page anchor

Retrieve a list of Rooms by Status

retrieve-a-list-of-rooms-by-status page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.video.v1.rooms.list({status: 'completed', limit: 20})
_10
.then(rooms => rooms.forEach(r => console.log(r.sid)));

Output

_45
{
_45
"rooms": [
_45
{
_45
"sid": "RM4070b618362c1682b2385b1f9982833c",
_45
"status": "completed",
_45
"date_created": "2017-04-03T22:21:49Z",
_45
"date_updated": "2017-04-03T22:21:51Z",
_45
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_45
"type": "peer-to-peer",
_45
"enable_turn": true,
_45
"unique_name": "RM4070b618362c1682b2385b1f9982833c",
_45
"status_callback": null,
_45
"status_callback_method": "POST",
_45
"end_time": "2017-04-03T22:21:51Z",
_45
"duration": 2,
_45
"max_participants": 10,
_45
"max_participant_duration": 86400,
_45
"max_concurrent_published_tracks": 10,
_45
"record_participants_on_connect": false,
_45
"video_codecs": [
_45
"VP8"
_45
],
_45
"media_region": "us1",
_45
"audio_only": false,
_45
"empty_room_timeout": 5,
_45
"unused_room_timeout": 5,
_45
"large_room": false,
_45
"url": "https://video.twilio.com/v1/Rooms/RM4070b618362c1682b2385b1f9982833c",
_45
"links": {
_45
"participants": "https://video.twilio.com/v1/Rooms/RM4070b618362c1682b2385b1f9982833c/Participants",
_45
"recordings": "https://video.twilio.com/v1/Rooms/RM4070b618362c1682b2385b1f9982833c/Recordings",
_45
"recording_rules": "https://video.twilio.com/v1/Rooms/RM4070b618362c1682b2385b1f9982833c/RecordingRules"
_45
}
_45
}
_45
],
_45
"meta": {
_45
"page": 0,
_45
"page_size": 50,
_45
"first_page_url": "https://video.twilio.com/v1/Rooms?Status=completed&PageSize=50&Page=0",
_45
"previous_page_url": "https://video.twilio.com/v1/Rooms?Status=completed&PageSize=50&Page=0",
_45
"url": "https://video.twilio.com/v1/Rooms?Status=completed&PageSize=50&Page=0",
_45
"next_page_url": "https://video.twilio.com/v1/Rooms?Status=completed&PageSize=50&Page=1",
_45
"key": "rooms"
_45
}
_45
}

Using multiple list filters

multiple-list-filters page anchor

Retrieve a list of completed Rooms

retrieve-a-list-of-completed-rooms page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_14
// Download the helper library from https://www.twilio.com/docs/node/install
_14
// Find your Account SID and Auth Token at twilio.com/console
_14
// and set the environment variables. See http://twil.io/secure
_14
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_14
const authToken = process.env.TWILIO_AUTH_TOKEN;
_14
const client = require('twilio')(accountSid, authToken);
_14
_14
client.video.v1.rooms
_14
.list({
_14
status: 'completed',
_14
uniqueName: 'DailyStandup',
_14
limit: 20
_14
})
_14
.then(rooms => rooms.forEach(r => console.log(r.sid)));

Output

_45
{
_45
"rooms": [
_45
{
_45
"sid": "RM4070b618362c1682b2385b1f9982833c",
_45
"status": "completed",
_45
"date_created": "2017-04-03T22:21:49Z",
_45
"date_updated": "2017-04-03T22:21:51Z",
_45
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_45
"type": "peer-to-peer",
_45
"enable_turn": true,
_45
"unique_name": "RM4070b618362c1682b2385b1f9982833c",
_45
"status_callback": null,
_45
"status_callback_method": "POST",
_45
"end_time": "2017-04-03T22:21:51Z",
_45
"duration": 2,
_45
"max_participants": 10,
_45
"max_participant_duration": 86400,
_45
"max_concurrent_published_tracks": 10,
_45
"record_participants_on_connect": false,
_45
"video_codecs": [
_45
"VP8"
_45
],
_45
"media_region": "us1",
_45
"audio_only": false,
_45
"empty_room_timeout": 5,
_45
"unused_room_timeout": 5,
_45
"large_room": false,
_45
"url": "https://video.twilio.com/v1/Rooms/RM4070b618362c1682b2385b1f9982833c",
_45
"links": {
_45
"participants": "https://video.twilio.com/v1/Rooms/RM4070b618362c1682b2385b1f9982833c/Participants",
_45
"recordings": "https://video.twilio.com/v1/Rooms/RM4070b618362c1682b2385b1f9982833c/Recordings",
_45
"recording_rules": "https://video.twilio.com/v1/Rooms/RM4070b618362c1682b2385b1f9982833c/RecordingRules"
_45
}
_45
}
_45
],
_45
"meta": {
_45
"page": 0,
_45
"page_size": 50,
_45
"first_page_url": "https://video.twilio.com/v1/Rooms?Status=completed&PageSize=50&Page=0",
_45
"previous_page_url": "https://video.twilio.com/v1/Rooms?Status=completed&PageSize=50&Page=0",
_45
"url": "https://video.twilio.com/v1/Rooms?Status=completed&PageSize=50&Page=0",
_45
"next_page_url": "https://video.twilio.com/v1/Rooms?Status=completed&PageSize=50&Page=1",
_45
"key": "rooms"
_45
}
_45
}

Configure the maximum Participant duration

configure-the-maximum-participant-duration page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_13
// Download the helper library from https://www.twilio.com/docs/node/install
_13
// Find your Account SID and Auth Token at twilio.com/console
_13
// and set the environment variables. See http://twil.io/secure
_13
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_13
const authToken = process.env.TWILIO_AUTH_TOKEN;
_13
const client = require('twilio')(accountSid, authToken);
_13
_13
client.video.v1.rooms
_13
.create({
_13
uniqueName: 'DailyStandup',
_13
maxParticipantDuration: 86400
_13
})
_13
.then(room => console.log(room.sid));

Output

_32
{
_32
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"date_created": "2015-07-30T20:00:00Z",
_32
"date_updated": "2015-07-30T20:00:00Z",
_32
"status": "in-progress",
_32
"type": "peer-to-peer",
_32
"sid": "RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"enable_turn": true,
_32
"unique_name": "DailyStandup",
_32
"max_concurrent_published_tracks": 0,
_32
"max_participants": 10,
_32
"max_participant_duration": 86400,
_32
"duration": 0,
_32
"status_callback_method": "POST",
_32
"status_callback": null,
_32
"record_participants_on_connect": false,
_32
"video_codecs": [
_32
"VP8"
_32
],
_32
"media_region": "us1",
_32
"audio_only": false,
_32
"empty_room_timeout": 5,
_32
"unused_room_timeout": 5,
_32
"end_time": "2015-07-30T20:00:00Z",
_32
"large_room": false,
_32
"url": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_32
"links": {
_32
"participants": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Participants",
_32
"recordings": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Recordings",
_32
"recording_rules": "https://video.twilio.com/v1/Rooms/RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/RecordingRules"
_32
}
_32
}


Rate this page: