Rate this page:

Voice JavaScript SDK: Edge Locations

The Twilio Client JavaScript SDK has been renamed to Twilio Voice JavaScript SDK.

Twilio Voice JavaScript SDK lets you select the specific Twilio data center edge locations used when your Twilio Device connects to Twilio. Network communication to and from Twilio will originate/terminate from the fixed, static IP address ranges listed for each edge location. Refer to these ranges if you need to configure your local network to allow communication or apply Quality of Service routing rules to communication with Twilio.

Twilio edge locations were added in version 1.11. Prior releases used a parameter named region that has now been deprecated.

Edge Location information for Twilio Voice JavaScript SDK

By default, the Twilio Voice JavaScript SDK will use Twilio's Global Low Latency (the roaming edge location) routing capability to determine which data center is closest to your user, establishing a connection through Twilio's nearest point of presence.

Global Low Latency uses latency-based DNS lookups to determine the nearest data center. You may want to override this in some cases, especially when your users are working from a fixed location and using a DNS server in another edge location.

GLL (roaming edge location) requires the upstream DNS to support RFC 7871. See GLL requirements for more information.

If you are operating a restricted network that requires allowing of media IPs, our recommendation is to specify the edge location in your application. Twilio will continue to expand our Global Low Latency (the roaming edge location) footprint in the future by adding more edges with different IP ranges and leaving the edge selection up to Global Low Latency could result in connections being established to edges that are not allowed by your infrastructure which may result in one-way audio or call set up failures.

Use any one of the available edge locations as the edge parameter. Leaving the value undefined will cause Twilio to default to its Global Low Latency routing, which cause the Device to establish its connection to the Twilio edge closest to the user.


For connectivty and bandwidth requirements including IP address list and ports see Voice Platform SDKs’ Network Connectivity Requirements

Example Usage

The examples below show two methods for setting an edge location.

Option 1 instantiates a new Twilio.Device with token and options arguments.

Option 2 instantiates a new Twilio.Device without the options argument. With this method, you can update the device options with device.updateOptions(options).

Force connections through Twilio Ireland:

Option 1:

const device = new Twilio.Device(token, { edge: "dublin" });

Option 2:

const device = new Twilio.Device(token);
device.updateOptions({ edge: "dublin" });

Force connections through Twilio US East Coast edge over your private Interconnect connection to that edge:

Option 1:

const device = new Twilio.Device(token, { edge: "ashburn-ix" });

Option 2:

const device = new Twilio.Device(token);
device.updateOptions({ edge: "ashburn-ix"});

Let Twilio choose the nearest edge:

const device = new Twilio.Device(token);

Edge Fallback

By default, the SDK automatically reconnects the WebSocket connection to the same edge location when it is unreachable, or when the SDK encounters a network error that results in a WebSocket disconnect. But if Twilio.Device.Options.edge parameter is supplied as an array of edge names, the SDK will enable automatic Edge fallback functionality. The diagram below illustrates the logic that is executed to perform the fallback.

Edge fallback diagram. See paragraph below for full details.

During initialization, the SDK will use the first edge name in the Twilio.Device.Options.edge array.

If the SDK encounters an error that results in a WebSocket disconnect with error code 1006 or 1015, the SDK will attempt reconnection to the next Edge in the array using an exponential backoff timer with an initial value of 1+random(5) and a maximum of 20 seconds. This maximum delay can be configured via Twilio.Device.Options.backoffMaxMs parameter.

If the SDK encounters an error while already connected to an edge server, the SDK will try to reconnect to the same edge once before attempting to connect to the next edge.

The following table provides common scenarios for when a fallback may occur:

Scenario Expected Behavior
Initialize with edge: [“ashburn”] This behaves exactly the same as initializing with edge: “ashburn”. In this scenario, the SDK will always attempt to reconnect to ashburn whenever the WebSocket is disconnected.
The first edge name specified in the edge array is unreachable.

• ashburn becomes unreachable
• Initialize with edge: [“ashburn”, “sydney”]
The SDK will attempt to connect to ashburn. Since ashburn is unreachable, the attempt will fail. The SDK will then attempt to connect to sydney.
All edge endpoints are unreachable, then one region becomes available after a few seconds.

• ashburn, sydney, and dublin becomes unreachable
• Initialize with edge: [“ashburn”, “sydney”, “dublin”]
• sydney becomes available, and the rest of the regions are still unreachable
The SDK will attempt to connect to ashburn. Since ashburn is unreachable, the attempt will fail. The SDK will then attempt sydney and will fail again. Then dublin will be attempted and fail. Once the SDK reaches the last edge name, it will loop back to the first edge name ashburn, and will keep cycling through the edge names until one edge endpoint becomes available. If sydney becomes available, the SDK will be connected to sydney once the loop reaches it.
All edges are available and the edge the SDK is connected to suddenly becomes unreachable.

• Initialize with edge: [“ashburn”, “sydney”, “dublin”]
• SDK is now connected to ashburn.
• ashburn goes down and becomes unreachable
If you are connected to ashburn and it suddenly becomes unreachable, the SDK will attempt to connect to ashburn once. If the attempt fails, the SDK will attempt to connect to the next edge, which is sydney.

It’s important to note that “unreachable” in these scenarios means the SDK failed to establish a WebSocket connection to the edge endpoint which resulted in error code 1006 or 1015. The error code 1015 is a WebSocket close event which is raised when the connection fails to perform a TLS handshake. This happens if the server certificate is invalid or cannot be verified. While the error code 1006 is raised when the connection was dropped unexpectedly and there is no close frame received from the server. The following are common issues that causes 1006:

  • The domain name cannot be resolved by the DNS
  • The network cannot reach the endpoint due to, for example, a misconfigured firewall
  • The client becomes offline due to, for example, the local device losing network connectivity
  • In an unlikely and very rare scenario, the Edge and standby servers are down

Edge Fallback and Signaling Reconnection

Signaling connectivity loss is the loss of the signaling websocket, and it usually only occurs when a user experiences a change in network during a call. As of v2.1.0 of the Voice JavaScript SDK, signaling reconnection is fully supported. A Twilio.Device will now attempt to reconnect to a lost websocket for up to 30 seconds.

Users relying on edge fallback, along with a small subset of customers using the 'roaming' edge, will not automatically benefit from this feature without additional configuration.

Who needs to opt in and why?

There are two groups that will need to opt in to this feature via the DeviceOptions.maxCallSignalingTimeoutMs property:

  1. Users relying on edge fallback by setting the DeviceOptions.edge property to an array of edges
  2. Users using the 'roaming' edge who could reasonably expect latency to an edge to change mid-call. Examples: You use a VPN with a geographic location different from your actual location, or your location experiences equal latency between two or more edge locations.

A lost websocket connection can only be reestablished on its original edge. The default edge fallback behavior of the SDK will cause the Twilio.Device to a connection to the original edge one time, and if that attempt fails, it will attempt a connection on the next edge in the DeviceOptions.edge array. If it connects to a new edge, however, reestablishing that lost websocket connection is no longer possible. This will cause the call to disconnect.

If you're not experiencing much signaling connectivity loss, or if signaling reconnection support isn't a priority for your use case, you don't need to do anything differently.

If you rely on edge fallback and you want to benefit from signaling reconnection support, you are able to opt in via the DeviceOptions.maxCallSignalingTimeoutMs property included in v2.1.0+ of the SDK.

Opt in to signaling reconnection spport

You can temporarily pause edge fallback during these signaling reconnection attempts using the DeviceOptions.maxCallSignalingTimeoutMs property. This property sets how long your device should try to reconnect to the original edge during signaling reconnection attempts.

Since the Twilio.Device can attempt to restore signaling connectivity for up to 30 seconds (30000 milliseconds), you likely will want to set your DeviceOptions.maxCallSignalingTimeoutMs property to 30000. This means that your Twilio.Device will not try to connect to any other edge during the entirey of the reconnection attempt.

const deviceOptions = { 
  edge: ['ashburn', 'sydney'],
  maxCallSignalingTimeoutMs: 30000

const device = new Twilio.Device(token, deviceOptions);
Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Community Forums or browsing the Twilio tag on Stack Overflow.


        Thank you for your feedback!

        We are always striving to improve our documentation quality, and your feedback is valuable to us. Please select the reason(s) for your feedback or provide additional information about how we can improve:

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!

        Refer us and get $10 in 3 simple steps!

        Step 1

        Get link

        Get a free personal referral link here

        Step 2

        Give $10

        Your user signs up and upgrade using link

        Step 3

        Get $10

        1,250 free SMSes
        OR 1,000 free voice mins
        OR 12,000 chats
        OR more