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}

リソースのプロパティ

Names in PHP format
`sid`	sid<RM> Not PII このリソースを一意に識別する、システムによって生成された34文字の文字列です。
`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 Deprecated. 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`.
`uniqueName`	文字列 Not PII 開発者の指定したRoomの名前です。これは`in-progress`ルームでは一意です。 SDKクライアントは、Roomの接続にこの名前を使用できます。 REST APIクライアントは、ルームが`in-progress`の場合に、この名前をRoom Sidの代わりに使用してRoomとやりとりできます。
`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 Roomの長さを秒数で表します。
`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 Participantが接続すると、レコーディングを開始します。 *この機能は`peer-to-peer`ルームでは利用できません。*
`videoCodecs`	enum:video_codec[] Not PII
`mediaRegion`	文字列 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 このリソースの絶対 URL です。
`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.

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

GET /Rooms/DailyStandup

Loading Code Sample...

Next Sample

出力を表示

出力

Retrieve an in-progress Room instance by UniqueName

Will return the Room instance object for the Room DailyStandup if the room is currently in-progress. If no Room exists by the name DailyStandup, or a Room by that name is only in completed status, the above request will return an HTTP 404 response.

Retrieve an `in-progress` or `completed` Room instance by `RoomSid`

A Room's Sid property is Twilio's own canonical unique identifier for a Room. You can always use the Room Sid to retrieve the Room, whether the room is in-progress or completed.

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

GET /Rooms/RMxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Loading Code Sample...

Next Sample

出力を表示

出力

Retrieve an in-progress or completed Room instance by RoomSid

Will return the Room instance object for the Room with Sid RMxxxxxxxxxxxxxxxxxxxxxxxxxxxxx, regardless of its status. If no Room exists with that Sid, the above request will return an HTTP 404 response.

HTTP POST

Modifies a Room resource.

Supported POST parameters

Names in PHP format

Names in PHP format
`sid` 必須	post sid_like<RM> Not PII The Room Sid or name that uniquely identifies this resource.
`status` 必須	post enum:room_status Not PII Set to `completed` to end the Room.

sid

必須

post sid_like<RM> Not PII

The Room Sid or name that uniquely identifies this resource.

status

必須

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.

Loading Code Sample...

Next Sample

出力を表示

出力

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

Names in PHP format
`enableTurn` オプション	post boolean Not PII Deprecated. 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 Type of room, either `peer-to-peer`, `group-small` or `group`. Will be `group` by default.
`uniqueName` オプション	post 文字列 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` オプション	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` オプション	post http_method Not PII HTTP method Twilio should use when requesting the above URL. Defaults to `POST`.
`maxParticipants` オプション	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` オプション	post boolean Not PII 接続時にParticipantの録音を開始します。 *この機能は`peer-to-peer`ルームでは利用できません。*
`videoCodecs` オプション	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` オプション	post 文字列 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.

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

Loading Code Sample...

Next Sample

出力を表示

出力

ルームを作成する

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

Loading Code Sample...

Next Sample

出力を表示

出力

Create a Peer-to-Peer Room

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

Loading Code Sample...

Next Sample

出力を表示

出力

Create a Group Room

Example 4: Create a Small Group Room

Loading Code Sample...

Next Sample

出力を表示

出力

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.

Names in PHP format
`status` オプション	GET enum:room_status Not PII Only show Rooms with the given status: `in-progress` (default), or `completed`
`uniqueName` オプション	GET 文字列 Not PII Only show Rooms with the provided Name.
`dateCreatedAfter` オプション	GET date_time<iso8601> Not PII Only show Rooms that started on or after this date, given as `YYYY-MM-DD`.
`dateCreatedBefore` オプション	GET date_time<iso8601> Not PII Only show Rooms that started before this date, given as `YYYY-MM-DD`.