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.
This guide introduces the concept of a Twilio Video Room and discusses how to create Rooms via the REST API and via client-side Room creation ("ad-hoc Rooms").
RTC (Real-Time Communication) services are typically architected in two layers:
In Twilio Programmable Video, signaling and media exchange takes place between clients and the Twilio's cloud, which orchestrates the communication and media sharing with the other users connected to the Room.
A Twilio Video Room is the virtual space where end users communicate. The Room resource provides:
Video Rooms are based on a publish/subscribe model. A Participant can publish audio, video, and data tracks to the Room. The other Participants can then subscribe to such tracks to start receiving the media information.
The following picture illustrates the architecture of a Group Room.
Clients only need to publish their media tracks once to the SFU, which clones and routes the media to the correct subscribers. Because of this, upstream bandwidth and battery consumption are independent of the number of Participants in the Room.
There are two ways to create Rooms: The Rooms REST API and Ad-hoc Rooms.
Developers can create Rooms by POST
ing an HTTP message to Twilio. The Rooms REST API documentation provides reference information as well as examples on how this can be done for all Room types. Creating Rooms through the REST API should only be done when the additional flexibility the API provides is needed; otherwise, using Ad-hoc Rooms will help your application scale more effectively. For more information, see the Guide to Scaling Applications.
Rooms created using the REST API comply with the following:
Rooms can also be created just-in-time when the first Participant connects. When a Room is created that way, we say it is an ad-hoc Room. This is the recommended way of creating rooms, because Ad-hoc Rooms allow you to create many Rooms in a short period of time, and they allow you to create a Room without having to make a REST API call. You can scale with REST API Room creation, but you will have a limitation around burst creation of Rooms. For more information on this, see the Guide to Scaling Applications.
In order to use ad-hoc Rooms, developers must enable Client-side Room Creation in the Twilio Console Room Settings:
Ad-hoc rooms will be configured based on the Room settings you have configured in the Twilio Console. Before enabling Client-side Room Creation, you should verify that the additional settings in the Console accurately represent the settings for the Rooms that you would like to create. For example, you should make sure that Room Type represents the type of Room you would like all ad-hoc Rooms to be; when an ad-hoc room is created, it follows the configuration settings in the Twilio Console.
Make sure to press Save when you are doing making changes to the configuration in the Twilio Console.
Once that's done, a Room with the specified type will be created as soon as a Participant SDK connects. For example, the following code snippet illustrates how to do this in JavaScript:
1connect('$TOKEN', {name: 'myFancyRoomName' }).then(room => {2console.log(`Successfully joined a Room: ${room}`);3room.on('participantConnected', participant => {4console.log(`A remote Participant connected: ${participant}`);5});6}, error => {7console.error(`Unable to connect to Room: ${error.message}`);8});
Notice that a Room name must be specified. Names of active Rooms must be unique. Subsequent Participants connecting with that name will join that Room instead of creating a new one.
Ad-hoc Rooms comply with the following:
The following table illustrates the main differences between Ad-hoc Rooms and Rooms created using the REST API:
REST Rooms | Ad-hoc Rooms | |
---|---|---|
Room creation method | POST request | SDK connect primitive |
Room creation time | When POST is received | When first participant connects |
First join timeout | Configurable, 5 minutes by default | NA |
Last leave timeout | Configurable, 5 minutes by default | 0 |
Max Participant duration | 24 hours | 24 hours |
Max Room Duration | 24 hours | 24 hours |
Want to get started with Rooms? The following links may help you: