This documentation 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, 2026.
We recommend migrating your application to the API provided by our preferred video partner, Zoom. We've prepared this migration guide to assist you in minimizing any service disruption.
Overview
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.
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.
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.
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 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.
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
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.
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.
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, assuming the UniqueName does not contain any reserved characters 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
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl
_16
// Download the helper library from https://www.twilio.com/docs/node/install
_16
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_16
_16
// Find your Account SID and Auth Token at twilio.com/console
_16
// and set the environment variables. See http://twil.io/secure
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.
For example:
_10
GET /Rooms/RMxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Retrieve an in-progress or completed Room instance by RoomSid
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl
_18
// Download the helper library from https://www.twilio.com/docs/node/install
_18
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_18
_18
// Find your Account SID and Auth Token at twilio.com/console
_18
// and set the environment variables. See http://twil.io/secure
Will return the Room instance object for the Room with SidRMxxxxxxxxxxxxxxxxxxxxxxxxxxxxx, regardless of its status. If no Room exists with that Sid, the above request will return an HTTP 404 response.
The new status of the resource. Set to completed to end the room.
Possible values:
in-progresscompletedfailed
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.
Complete a Room
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl
_18
// Download the helper library from https://www.twilio.com/docs/node/install
_18
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_18
_18
// Find your Account SID and Auth Token at twilio.com/console
_18
// and set the environment variables. See http://twil.io/secure
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.
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.
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.
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
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).
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 a Room
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl
_18
// Download the helper library from https://www.twilio.com/docs/node/install
_18
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_18
_18
// Find your Account SID and Auth Token at twilio.com/console
_18
// and set the environment variables. See http://twil.io/secure
Example 5: Create a Room with a 60 minute empty room timeout
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
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl
_19
// Download the helper library from https://www.twilio.com/docs/node/install
_19
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_19
_19
// Find your Account SID and Auth Token at twilio.com/console
_19
// and set the environment variables. See http://twil.io/secure
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
Retrieve a list of Rooms by Status
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl
_19
// Download the helper library from https://www.twilio.com/docs/node/install
_19
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_19
_19
// Find your Account SID and Auth Token at twilio.com/console
_19
// and set the environment variables. See http://twil.io/secure