Create room

POST /v1/Rooms

Video rooms with one or more participants

Body

  • AudioOnly boolean

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

  • Configures how long (in minutes) a room will remain active after last participant leaves. Valid values range from 1 to 60 minutes (no fractions).

  • EnableTurn boolean

    Deprecated, now always considered to be true.

  • LargeRoom boolean

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

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

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

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

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

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

  • StatusCallback string(uri)

    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.

  • StatusCallbackMethod string(http-method)

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

    Values are HEAD, GET, POST, PATCH, PUT, or DELETE.

  • Type string

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

    Values are go, peer-to-peer, group, or group-small.

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

  • Configures how long (in minutes) a room will remain active if no one joins. Valid values range from 1 to 60 minutes (no fractions).

  • VideoCodecs array[string]

    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

    Values are VP8 or H264.

Responses

  • Created

    Hide response attributes Show response attributes object
    • account_sid string | null

      The SID of the Account that created the resource

      Minimum length is 34, maximum length is 34. Format should match the following pattern: ^AC[0-9a-fA-F]{32}$.

    • audio_only boolean | null

      Indicates whether the room will only contain audio track participants for group rooms.

    • date_created string(date-time) | null

      The ISO 8601 date and time in GMT when the resource was created

    • date_updated string(date-time) | null

      The ISO 8601 date and time in GMT when the resource was last updated

    • duration integer | null

      The duration of the room in seconds

    • empty_room_timeout integer | null

      The time a room will remain active after last participant leaves.

    • enable_turn boolean | null

      Enable Twilio's Network Traversal TURN service

    • end_time string(date-time) | null

      The UTC end time of the room in UTC ISO 8601 format

    • large_room boolean | null

      Indicates if this is a large room.

    • The maximum number of published tracks allowed in the room at the same time

    • The maximum number of seconds a Participant can be connected to the room

    • max_participants integer | null

      The maximum number of concurrent Participants allowed in the room

    • media_region string | null

      The region for the media server in Group Rooms

    • Whether to start recording when Participants connect

    • sid string | null

      The unique string that identifies the resource

      Minimum length is 34, maximum length is 34. Format should match the following pattern: ^RM[0-9a-fA-F]{32}$.

    • status string | null

      The status of the room

      Values are in-progress, completed, or failed.

    • status_callback string(uri) | null

      The URL to send status information to your application

    • status_callback_method string(http-method) | null

      The HTTP method we use to call status_callback

      Values are HEAD, GET, POST, PATCH, PUT, or DELETE.

    • type string | null

      The type of room

      Values are go, peer-to-peer, group, or group-small.

    • unique_name string | null

      An application-defined string that uniquely identifies the resource

    • unused_room_timeout integer | null

      The time a room will remain active when no one joins.

    • url string(uri) | null

      The absolute URL of the resource

    • video_codecs array[string] | null

      An array of the video codecs that are supported when publishing a track in the room

      Values are VP8 or H264.

POST /v1/Rooms
curl \
 -X POST https://video.twilio.com/v1/Rooms \
 --user "username:password" \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -d 'AudioOnly=true&EmptyRoomTimeout=42&EnableTurn=true&LargeRoom=true&MaxParticipantDuration=42&MaxParticipants=42&MediaRegion=string&RecordParticipantsOnConnect=true&StatusCallback=https%3A%2F%2Fexample.com&StatusCallbackMethod=HEAD&Type=go&UniqueName=string&UnusedRoomTimeout=42&VideoCodecs=VP8'
Request example
{
  "AudioOnly": true,
  "EmptyRoomTimeout": 42,
  "EnableTurn": true,
  "LargeRoom": true,
  "MaxParticipantDuration": 42,
  "MaxParticipants": 42,
  "MediaRegion": "string",
  "RecordParticipantsOnConnect": true,
  "StatusCallback": "https://example.com",
  "StatusCallbackMethod": "HEAD",
  "Type": "go",
  "UniqueName": "string",
  "UnusedRoomTimeout": 42,
  "VideoCodecs": [
    "VP8"
  ]
}
Request examples
{
  "AudioOnly": true,
  "EmptyRoomTimeout": 42,
  "EnableTurn": true,
  "LargeRoom": true,
  "MaxParticipantDuration": 42,
  "MaxParticipants": 42,
  "MediaRegion": "string",
  "RecordParticipantsOnConnect": true,
  "StatusCallback": "https://example.com",
  "StatusCallbackMethod": "HEAD",
  "Type": "go",
  "UniqueName": "string",
  "UnusedRoomTimeout": 42,
  "VideoCodecs": [
    "VP8"
  ]
}
Response examples (201)
{
  "account_sid": "string",
  "audio_only": true,
  "date_created": "2023-05-04T09:42:00+00:00",
  "date_updated": "2023-05-04T09:42:00+00:00",
  "duration": 42,
  "empty_room_timeout": 42,
  "enable_turn": true,
  "end_time": "2023-05-04T09:42:00+00:00",
  "large_room": true,
  "links": {},
  "max_concurrent_published_tracks": 42,
  "max_participant_duration": 42,
  "max_participants": 42,
  "media_region": "string",
  "record_participants_on_connect": true,
  "sid": "string",
  "status": "in-progress",
  "status_callback": "https://example.com",
  "status_callback_method": "HEAD",
  "type": "go",
  "unique_name": "string",
  "unused_room_timeout": 42,
  "url": "https://example.com",
  "video_codecs": [
    "VP8"
  ]
}
Response examples (201)
{
  "account_sid": "string",
  "audio_only": true,
  "date_created": "2024-05-04T09:42:00+00:00",
  "date_updated": "2024-05-04T09:42:00+00:00",
  "duration": 42,
  "empty_room_timeout": 42,
  "enable_turn": true,
  "end_time": "2024-05-04T09:42:00+00:00",
  "large_room": true,
  "links": {},
  "max_concurrent_published_tracks": 42,
  "max_participant_duration": 42,
  "max_participants": 42,
  "media_region": "string",
  "record_participants_on_connect": true,
  "sid": "string",
  "status": "in-progress",
  "status_callback": "https://example.com",
  "status_callback_method": "HEAD",
  "type": "go",
  "unique_name": "string",
  "unused_room_timeout": 42,
  "url": "https://example.com",
  "video_codecs": [
    "VP8"
  ]
}