REST API: Rooms

概要

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

Room Instance Resource

リソースURI

/v1/Rooms/{RoomNameOrSid}

リソースのプロパティ

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. Whether to 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. This setting only applies to rooms with type `peer-to-peer`.
`unique_name`	文字列 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. 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: `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.
`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`	文字列 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.*
`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. This makes it easier to interact with Twilio's REST API without having to keep track of Twilio's Room SID identifiers.

たとえば、次のようになります。

GET /Rooms/DailyStandup

Loading Code Sample...

Next Sample

Show sample response

Example JSON API response

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.

たとえば、次のようになります。

GET /Rooms/RMxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Loading Code Sample...

Next Sample

Show sample response

Example JSON API response

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` 必須	post enum:room_status Not PII The new status of the resource. Set to `completed` to end the room.

Parameters in REST API format

sid

Path

post sid_like<RM> Not PII

The SID of the Room resource to update.

status

必須

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

Next Sample

Show sample response

Example JSON API response

Complete a Room

Rooms List 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` オプション	post boolean Not PII Deprecated. Whether to 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. This setting only applies to rooms with type `peer-to-peer`.
`type` オプション	post enum:room_type Not PII The type of room. Can be: `peer-to-peer`, `group-small`, or `group`. The default value is `group`.
`unique_name` オプション	post 文字列 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. 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` オプション	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` オプション	post http_method Not PII The HTTP method we should use to call `status_callback`. Can be `POST` or `GET`.
`max_participants` オプション	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` オプション	post boolean Not PII Whether to start recording when Participants connect. *This feature is not available in `peer-to-peer` rooms.*
`video_codecs` オプション	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` オプション	post 文字列 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.*

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.

例1: 「DailyStandup」という名前のRoomを作成します

Loading Code Sample...

Next Sample

Show sample response

Example JSON API response

ルームを作成する

例2: `SalesMeeting`という名前で、Network Traversal Service TURNをオフにし、ステータスコールバックURLを設定したRoomを作成します。

Loading Code Sample...

Next Sample

Show sample response

Example JSON API response

Create a Peer-to-Peer Room

例3: Group Roomを作成し、レコーディングをオンにし、ステータスコールバックURLを設定します。

Loading Code Sample...

Next Sample

Show sample response

Example JSON API response

Create a Group Room

Example 4: Create a Small Group Room

Loading Code Sample...

Next Sample

Show sample response

Example JSON API response

Create a Small Group Room

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.

リストフィルター

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

Parameters in REST API format
`status` オプション	GET enum:room_status Not PII Read only the rooms with this status. Can be: `in-progress` (default) or `completed`
`unique_name` オプション	GET 文字列 Not PII Read only rooms with the this `unique_name`.
`date_created_after` オプション	GET date_time<iso8601> Not PII Read only rooms that started on or after this date, given as `YYYY-MM-DD`.
`date_created_before` オプション	GET date_time<iso8601> Not PII Read only rooms that started before this date, given as `YYYY-MM-DD`.