Skip to contentSkip to navigationSkip to topbar
Twilio Docs
On this page

REST API: Rooms

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.

1
https://video.twilio.com

2

Room Instance Resource

room-instance-resource page anchor

Resource URI

resource-uri page anchor
1
/v1/Rooms/{RoomNameOrSid}

2

Resource Properties

resource-properties page anchor
Property nameTypeRequiredDescriptionChild properties
sidSID<RM>

Optional

Not PII

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

Pattern: ^RM[0-9a-fA-F]{32}$Min length: 34Max length: 34
statusenum<string>

Optional

Not PII
Possible values:
in-progresscompletedfailed
dateCreatedstring<date-time>

Optional

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.

dateUpdatedstring<date-time>

Optional

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.

accountSidSID<AC>

Optional

Not PII

The SID of the Account that created the Room resource.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34
enableTurnboolean

Optional

Not PII

Deprecated, now always considered to be true.

uniqueNamestring

Optional

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

statusCallbackstring<uri>

Optional

Not PII

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

statusCallbackMethodenum<http-method>

Optional

Not PII

The HTTP method Twilio uses to call status_callback. Can be POST or GET and defaults to POST.

Possible values:
GETPOST
endTimestring<date-time>

Optional

Not PII

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

durationinteger

Optional

Not PII

The duration of the room in seconds.

typeenum<string>

Optional

Not PII
Possible values:
gopeer-to-peergroupgroup-small
maxParticipantsinteger

Optional

Not PII

The maximum number of concurrent Participants allowed in the room.

Default: 0
maxParticipantDurationinteger

Optional

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

Default: 0
maxConcurrentPublishedTracksinteger

Optional

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.

recordParticipantsOnConnectboolean

Optional

Not PII

Whether to start recording when Participants connect.

videoCodecsarray[enum<string>]

Optional

Not PII

An array of the video codecs that are supported when publishing a track in the room. Can be: VP8 and H264.

Possible values:
VP8H264
mediaRegionstring

Optional

Not PII

The region for the Room's media server. Can be one of the available Media Regions.

audioOnlyboolean

Optional

Not PII

When set to true, indicates that the participants in the room will only publish audio. No video tracks will be allowed.

emptyRoomTimeoutinteger

Optional

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.

Default: 0
unusedRoomTimeoutinteger

Optional

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.

Default: 0
largeRoomboolean

Optional

Not PII

Indicates if this is a large room.

urlstring<uri>

Optional

Not PII

The absolute URL of the resource.

linksobject<uri-map>

Optional

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:

GET /Rooms/DailyStandup
Retrieve an in-progress Room instance by UniqueNameLink to code sample: Retrieve an in-progress Room instance by UniqueName
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function fetchRoom() {

11
  const room = await client.video.v1.rooms("DailyStandup").fetch();

12


13
  console.log(room.sid);

14
}

15


16
fetchRoom();

Response

Note about this response
1
{

2
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "date_created": "2015-07-30T20:00:00Z",

4
  "date_updated": "2015-07-30T20:00:00Z",

5
  "status": "in-progress",

6
  "type": "peer-to-peer",

7
  "sid": "DailyStandup",

8
  "enable_turn": true,

9
  "unique_name": "unique_name",

10
  "max_participants": 10,

11
  "max_participant_duration": 86400,

12
  "max_concurrent_published_tracks": 0,

13
  "duration": 0,

14
  "status_callback_method": "POST",

15
  "status_callback": null,

16
  "record_participants_on_connect": false,

17
  "video_codecs": [

18
    "VP8"

19
  ],

20
  "audio_only": false,

21
  "media_region": "us1",

22
  "empty_room_timeout": 5,

23
  "unused_room_timeout": 5,

24
  "end_time": "2015-07-30T20:00:00Z",

25
  "large_room": false,

26
  "url": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

27
  "links": {

28
    "participants": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants",

29
    "recordings": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Recordings",

30
    "transcriptions": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Transcriptions",

31
    "recording_rules": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/RecordingRules"

32
  }

33
}

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:

GET /Rooms/RMxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Retrieve an in-progress or completed Room instance by RoomSidLink to code sample: Retrieve an in-progress or completed Room instance by RoomSid
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function fetchRoom() {

11
  const room = await client.video.v1

12
    .rooms("RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")

13
    .fetch();

14


15
  console.log(room.sid);

16
}

17


18
fetchRoom();

Response

Note about this response
1
{

2
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "date_created": "2015-07-30T20:00:00Z",

4
  "date_updated": "2015-07-30T20:00:00Z",

5
  "status": "in-progress",

6
  "type": "peer-to-peer",

7
  "sid": "RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

8
  "enable_turn": true,

9
  "unique_name": "unique_name",

10
  "max_participants": 10,

11
  "max_participant_duration": 86400,

12
  "max_concurrent_published_tracks": 0,

13
  "duration": 0,

14
  "status_callback_method": "POST",

15
  "status_callback": null,

16
  "record_participants_on_connect": false,

17
  "video_codecs": [

18
    "VP8"

19
  ],

20
  "audio_only": false,

21
  "media_region": "us1",

22
  "empty_room_timeout": 5,

23
  "unused_room_timeout": 5,

24
  "end_time": "2015-07-30T20:00:00Z",

25
  "large_room": false,

26
  "url": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

27
  "links": {

28
    "participants": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants",

29
    "recordings": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Recordings",

30
    "transcriptions": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Transcriptions",

31
    "recording_rules": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/RecordingRules"

32
  }

33
}

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

post-instance page anchor

Modifies a Room resource.

Supported POST parameters

Path parameters

path-parameters page anchor
Property nameTypeRequiredPIIDescription
sidstring
required
Not PII

The SID of the Room resource to update.

Request body parameters

request-body-parameters page anchor
Encoding type:application/x-www-form-urlencoded
SchemaExample
Property nameTypeRequiredDescriptionChild properties
statusenum<string>
required
Not PII
Possible values:
in-progresscompletedfailed

Complete a Room

complete-room page anchor

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.

Complete a RoomLink to code sample: Complete a Room
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function updateRoom() {

11
  const room = await client.video.v1

12
    .rooms("RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")

13
    .update({ status: "completed" });

14


15
  console.log(room.sid);

16
}

17


18
updateRoom();

Response

Note about this response
1
{

2
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "date_created": "2015-07-30T20:00:00Z",

4
  "date_updated": "2015-07-30T20:00:00Z",

5
  "status": "completed",

6
  "type": "peer-to-peer",

7
  "sid": "RMXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",

8
  "enable_turn": true,

9
  "unique_name": "unique_name",

10
  "max_participants": 10,

11
  "max_participant_duration": 86400,

12
  "max_concurrent_published_tracks": 10,

13
  "status_callback_method": "POST",

14
  "status_callback": null,

15
  "record_participants_on_connect": false,

16
  "video_codecs": [

17
    "VP8"

18
  ],

19
  "media_region": "us1",

20
  "audio_only": false,

21
  "empty_room_timeout": 5,

22
  "unused_room_timeout": 5,

23
  "end_time": "2015-07-30T20:00:00Z",

24
  "large_room": false,

25
  "duration": 10,

26
  "url": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

27
  "links": {

28
    "participants": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants",

29
    "recordings": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Recordings",

30
    "transcriptions": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Transcriptions",

31
    "recording_rules": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/RecordingRules"

32
  }

33
}

Rooms List Resource

rooms-list-resource page anchor

Resource URI

resource-uri-2 page anchor
1
/v1/Rooms

2

HTTP POST

post-list-resource page anchor

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

Once you create a Room, you will need to generate Access Tokens and use Twilio's client-side Video SDKs to connect to the Room. Learn more about the components of a Twilio Video app.

The Quickstart guides for each client-side SDK explain how to connect to and interact with Rooms:

  • JavaScript
  • iOS
  • Android

Supported POST parameters

post-parameters page anchor

Request body parameters

request-body-parameters-1 page anchor
Encoding type:application/x-www-form-urlencoded
SchemaExample
Property nameTypeRequiredDescriptionChild properties
enableTurnboolean

Optional

Not PII

Deprecated, now always considered to be true.

typeenum<string>

Optional

Not PII
Possible values:
gopeer-to-peergroupgroup-small
uniqueNamestring

Optional

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

statusCallbackstring<uri>

Optional

Not PII

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

statusCallbackMethodenum<http-method>

Optional

Not PII

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

Possible values:
GETPOST
maxParticipantsinteger

Optional

Not PII

The maximum number of concurrent Participants allowed in the room. The maximum allowed value is 50.

recordParticipantsOnConnectboolean

Optional

Not PII

Whether to start recording when Participants connect.

transcribeParticipantsOnConnectboolean

Optional

Not PII

Whether to start transcriptions when Participants connect. If TranscriptionsConfiguration is not provided, default settings will be used.

videoCodecsarray[enum<string>]

Optional

Not PII

An array of the video codecs that are supported when publishing a track in the room. Can be: VP8 and H264.

Possible values:
VP8H264
mediaRegionstring

Optional

Not PII

The region for the Room's media server. Can be one of the available Media Regions.

recordingRules

Optional

Not PII

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

transcriptionsConfigurationobject

Optional

Not PII

A collection of properties that describe transcription behaviour. If TranscribeParticipantsOnConnect is set to true and TranscriptionsConfiguration is not provided, default settings will be used.

audioOnlyboolean

Optional

Not PII

When set to true, indicates that the participants in the room will only publish audio. No video tracks will be allowed.

maxParticipantDurationinteger

Optional

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

emptyRoomTimeoutinteger

Optional

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

unusedRoomTimeoutinteger

Optional

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

largeRoomboolean

Optional

Not PII

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

(information)

Info

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
Create a RoomLink to code sample: Create a Room
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function createRoom() {

11
  const room = await client.video.v1.rooms.create({

12
    uniqueName: "DailyStandup",

13
  });

14


15
  console.log(room.sid);

16
}

17


18
createRoom();

Response

Note about this response
1
{

2
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "date_created": "2015-07-30T20:00:00Z",

4
  "date_updated": "2015-07-30T20:00:00Z",

5
  "status": "in-progress",

6
  "type": "peer-to-peer",

7
  "sid": "RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

8
  "enable_turn": true,

9
  "unique_name": "DailyStandup",

10
  "max_concurrent_published_tracks": 0,

11
  "max_participants": 10,

12
  "max_participant_duration": 86400,

13
  "duration": 0,

14
  "status_callback_method": "POST",

15
  "status_callback": null,

16
  "record_participants_on_connect": false,

17
  "video_codecs": [

18
    "VP8"

19
  ],

20
  "media_region": "us1",

21
  "audio_only": false,

22
  "empty_room_timeout": 5,

23
  "unused_room_timeout": 5,

24
  "end_time": "2015-07-30T20:00:00Z",

25
  "large_room": false,

26
  "url": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

27
  "links": {

28
    "participants": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants",

29
    "recordings": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Recordings",

30
    "transcriptions": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Transcriptions",

31
    "recording_rules": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/RecordingRules"

32
  }

33
}

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

example-2-create-a-room-enable-recording-and-set-a-status-callback-url page anchor
Create a Room with recordings enabledLink to code sample: Create a Room with recordings enabled
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function createRoom() {

11
  const room = await client.video.v1.rooms.create({

12
    recordParticipantsOnConnect: true,

13
    statusCallback: "http://example.org",

14
    uniqueName: "DailyStandup",

15
  });

16


17
  console.log(room.sid);

18
}

19


20
createRoom();

Response

Note about this response
1
{

2
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "date_created": "2015-07-30T20:00:00Z",

4
  "date_updated": "2015-07-30T20:00:00Z",

5
  "status": "in-progress",

6
  "type": "peer-to-peer",

7
  "sid": "RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

8
  "enable_turn": true,

9
  "unique_name": "DailyStandup",

10
  "max_concurrent_published_tracks": 0,

11
  "max_participants": 10,

12
  "max_participant_duration": 86400,

13
  "duration": 0,

14
  "status_callback_method": "POST",

15
  "status_callback": "http://example.org",

16
  "record_participants_on_connect": true,

17
  "video_codecs": [

18
    "VP8"

19
  ],

20
  "media_region": "us1",

21
  "audio_only": false,

22
  "empty_room_timeout": 5,

23
  "unused_room_timeout": 5,

24
  "end_time": "2015-07-30T20:00:00Z",

25
  "large_room": false,

26
  "url": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

27
  "links": {

28
    "participants": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants",

29
    "recordings": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Recordings",

30
    "transcriptions": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Transcriptions",

31
    "recording_rules": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/RecordingRules"

32
  }

33
}

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

example-3-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 TimeoutLink to code sample: Create a Room with a 60 Minute Empty Room Timeout
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function createRoom() {

11
  const room = await client.video.v1.rooms.create({

12
    emptyRoomTimeout: 60,

13
    uniqueName: "DailyStandup",

14
  });

15


16
  console.log(room.sid);

17
}

18


19
createRoom();

Response

Note about this response
1
{

2
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "date_created": "2015-07-30T20:00:00Z",

4
  "date_updated": "2015-07-30T20:00:00Z",

5
  "status": "in-progress",

6
  "type": "peer-to-peer",

7
  "sid": "RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

8
  "enable_turn": true,

9
  "unique_name": "DailyStandup",

10
  "max_concurrent_published_tracks": 0,

11
  "max_participants": 10,

12
  "max_participant_duration": 86400,

13
  "duration": 0,

14
  "status_callback_method": "POST",

15
  "status_callback": null,

16
  "record_participants_on_connect": false,

17
  "video_codecs": [

18
    "VP8"

19
  ],

20
  "media_region": "us1",

21
  "audio_only": false,

22
  "empty_room_timeout": 60,

23
  "unused_room_timeout": 5,

24
  "end_time": "2015-07-30T20:00:00Z",

25
  "large_room": false,

26
  "url": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

27
  "links": {

28
    "participants": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants",

29
    "recordings": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Recordings",

30
    "transcriptions": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Transcriptions",

31
    "recording_rules": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/RecordingRules"

32
  }

33
}

HTTP GET

get-list-resource page anchor

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

List Filters

get-list-filters page anchor

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

Query parameters

query-parameters page anchor
Property nameTypeRequiredPIIDescription
statusenum<string>

Optional

Not PII

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

Possible values:
in-progresscompletedfailed
uniqueNamestring

Optional

Not PII

Read only rooms with the this unique_name.

dateCreatedAfterstring<date-time>

Optional

Not PII

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

dateCreatedBeforestring<date-time>

Optional

Not PII

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

pageSizeinteger<int64>

Optional

Not PII

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

Minimum: 1Maximum: 1000
pageinteger

Optional

Not PII

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

Minimum: 0
pageTokenstring

Optional

Not PII

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 UniqueNameLink to code sample: Retrieve a list of Rooms by UniqueName
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function listRoom() {

11
  const rooms = await client.video.v1.rooms.list({

12
    status: "completed",

13
    uniqueName: "DailyStandup",

14
    limit: 20,

15
  });

16


17
  rooms.forEach((r) => console.log(r.sid));

18
}

19


20
listRoom();

Response

Note about this response
1
{

2
  "rooms": [],

3
  "meta": {

4
    "page": 0,

5
    "page_size": 50,

6
    "first_page_url": "https://video.twilio.com/v1/Rooms?PageSize=50&Page=0",

7
    "previous_page_url": null,

8
    "url": "https://video.twilio.com/v1/Rooms?PageSize=50&Page=0",

9
    "next_page_url": null,

10
    "key": "rooms"

11
  }

12
}

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 StatusLink to code sample: Retrieve a list of Rooms by Status
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function listRoom() {

11
  const rooms = await client.video.v1.rooms.list({

12
    status: "completed",

13
    limit: 20,

14
  });

15


16
  rooms.forEach((r) => console.log(r.sid));

17
}

18


19
listRoom();

Response

Note about this response
1
{

2
  "rooms": [],

3
  "meta": {

4
    "page": 0,

5
    "page_size": 50,

6
    "first_page_url": "https://video.twilio.com/v1/Rooms?PageSize=50&Page=0",

7
    "previous_page_url": null,

8
    "url": "https://video.twilio.com/v1/Rooms?PageSize=50&Page=0",

9
    "next_page_url": null,

10
    "key": "rooms"

11
  }

12
}

Using multiple list filters

multiple-list-filters page anchor
Retrieve a list of completed RoomsLink to code sample: Retrieve a list of completed Rooms
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function listRoom() {

11
  const rooms = await client.video.v1.rooms.list({

12
    status: "completed",

13
    uniqueName: "DailyStandup",

14
    limit: 20,

15
  });

16


17
  rooms.forEach((r) => console.log(r.sid));

18
}

19


20
listRoom();

Response

Note about this response
1
{

2
  "rooms": [],

3
  "meta": {

4
    "page": 0,

5
    "page_size": 50,

6
    "first_page_url": "https://video.twilio.com/v1/Rooms?PageSize=50&Page=0",

7
    "previous_page_url": null,

8
    "url": "https://video.twilio.com/v1/Rooms?PageSize=50&Page=0",

9
    "next_page_url": null,

10
    "key": "rooms"

11
  }

12
}
Configure the maximum Participant durationLink to code sample: Configure the maximum Participant duration
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function createRoom() {

11
  const room = await client.video.v1.rooms.create({

12
    maxParticipantDuration: 86400,

13
    uniqueName: "DailyStandup",

14
  });

15


16
  console.log(room.sid);

17
}

18


19
createRoom();

Response

Note about this response
1
{

2
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "date_created": "2015-07-30T20:00:00Z",

4
  "date_updated": "2015-07-30T20:00:00Z",

5
  "status": "in-progress",

6
  "type": "peer-to-peer",

7
  "sid": "RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

8
  "enable_turn": true,

9
  "unique_name": "DailyStandup",

10
  "max_concurrent_published_tracks": 0,

11
  "max_participants": 10,

12
  "max_participant_duration": 86400,

13
  "duration": 0,

14
  "status_callback_method": "POST",

15
  "status_callback": null,

16
  "record_participants_on_connect": false,

17
  "video_codecs": [

18
    "VP8"

19
  ],

20
  "media_region": "us1",

21
  "audio_only": false,

22
  "empty_room_timeout": 5,

23
  "unused_room_timeout": 5,

24
  "end_time": "2015-07-30T20:00:00Z",

25
  "large_room": false,

26
  "url": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

27
  "links": {

28
    "participants": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Participants",

29
    "recordings": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Recordings",

30
    "transcriptions": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Transcriptions",

31
    "recording_rules": "https://video.twilio.com/v1/Rooms/RMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/RecordingRules"

32
  }

33
}