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.
Twilio is launching a new Console. Some screenshots on this page may show the Legacy Console and therefore may no longer be accurate. We are working to update all screenshots to reflect the new Console experience. Learn more about the new Console.
Programmable Video Developers can select the geolocation of the Twilio infrastructure that serves their Rooms. Two mechanisms are available:
Understanding these mechanisms is important for creating high quality Real-Time Communication (RTC) applications.
On the Internet, latency and packet loss depend on geolocation. When the connection between a sender and a receiver spans the globe, latency and jitter are increased by the distance between the parties. Packet loss is also more likely, due to the number of routers in the connection path. This affects quality in several ways:
In order to minimize these effects, the Twilio infrastructure that serves a Room should be as close as possible to the Room's Participants. This guide provides best practices and recommendations on how to choose regions for your applications.
Programmable Video developers have the following options when working with regions:
Region ID | Location |
---|---|
gll | Global Low Latency (see section below) |
au1 | Australia |
br1 | Brazil |
de1 | Germany |
ie1 | Ireland |
in1 | India |
jp1 | Japan |
sg1 | Singapore |
us1 | US East Coast (Virginia) |
us2 | US West Coast (Oregon) |
Twilio Programmable Video regions are architected around two concepts: the Signaling Region and the Media Region.
The Signaling Region:
The Media Region:
Unless there are legal or compliance reasons, developers should select the region having less latency with a Participant as the Signaling Region of that Participant.
For the Media Region, we recommend to use the region minimizing the average latency to all the Group Room Participants. Many times it's not possible to have prior knowledge of a participant's location. In that case, a simple rule of thumb that typically works is to select the region closest to the first Participant.
Applying these recommendations may be complex and sometimes developers prefer Twilio to select the region on their behalf. This can be achieved using GLL (Global Low Latency).
Our Video SDKs use gll
as the default Signaling Region. In that case, Participants will connect to the region having minimum latency to their location. This can be overridden with Signaling Region selection, which is supported in the following SDK versions:
Twilio Video SDK | Required version |
---|---|
Android | v5.0.0-beta1+ |
iOS | v3.0.0-beta1+ |
JavaScript | v2.0.0+ |
The Signaling Region can be specified using the region
property at connect time. For example, the following snippets illustrate how to connect to de1
:
Android (v5.0.0-beta1+)
Java
1ConnectOptions connectOptions = new ConnectOptions.Builder(accessToken)2.region("de1")3.roomName("my-room")4.build();56room = Video.connect(context, connectOptions, roomListener);7
Kotlin
1val connectOptions = new ConnectOptions.Builder(accessToken)2.region("de1")3.roomName("my-room")4.build()56room = Video.connect(context, connectOptions, roomListener)7
iOS (v3.0.0-beta1+)
1let connectOptions = ConnectOptions(token: accessToken) { (builder) in2builder.region = "de1"3builder.roomName = "my-room"4}5self.room = TwilioVideoSDK.connect(with: connectOptions, delegate: self)
JavaScript (v2.0.0+)
1const { connect } = require('twilio-video');23const room = await connect(token, {4name: 'my-room',5region: 'de1'6});
Using the Console
By default, your Twilio account is configured with us1
as the Media Region. You can modify the default media region in Video/Rooms/Settings, as the following picture illustrates:
Using the Rooms API
You can override the default region specified in the console by using the Rooms REST API. This can be done by setting the MediaRegion
POST
parameter to the desired Region ID. For further information see the Room Creation Example.
Current Twilio region selection is based on two principles:
gll
then the region with minimum latency to the client is selected for signaling traffic.
gll
then the Signaling Region of the first participant connecting to the Group Room is selected for media traffic. Note, that due to this, in ad-hoc Rooms Media Region can be specified at connect time from the first Participant SDK.
Let's use an example to better illustrate how this works. Imagine a Group Room with the following participants:
us1
)
de1
)
The following table shows the actual chosen regions as a function of the specified (at the console or with the APIs) Signaling and Media Regions:
Specified Media Region | Specified Signaling Region (Alice) | Specified Signaling Region (Markus) | Chosen Media Region | Chosen Signaling Region (Alice) | Chosen Signaling Region (Markus) |
---|---|---|---|---|---|
- | - | - | us1 | us1 | de1 |
gll | - | - | us1 | us1 | de1 |
gll | gll | gll | us1 | us1 | de1 |
ie1 | - | - | ie1 | us1 | de1 |
gll | ie1 | - | ie1 | ie1 | de1 |
gll | ie1 | gll | ie1 | ie1 | de1 |
ie1 | au1 | br1 | ie1 | au1 | br1 |
Twilio's Programmable Video SDKs must communicate with Twilio's cloud. Hence, firewalls may need to be configured to allow Twilio's Signaling and Media Servers IPs:
gll
should whitelist the IP ranges in all regions.
The IP ranges and domain names assigned to every region can be found in our IP Addresses Guide.