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 Reconnection States and Events and provides guidance on how to use them effectively in your Twilio Video applications. Whenever there are disruptions in network connectivity, the Twilio Video SDK will attempt to re-establish the signaling and media connections to the Room. The Reconnection States and Events can be used by the application logic to update its user interface accordingly.
The Room.state
property represents the status of the application's signaling and media connections to the Room and its Participants. When the application joins a Room, it will transition to the "connected" state. Similarly, when the application disconnects from a Room, it will transition to the "disconnected" state. Apart from these basic states, there are two Reconnection Events:
reconnecting - when the application is trying to re-establish its signaling and/or media connections to the Room. When the Room transitions to this state, it will emit the "reconnecting" event as follows:
1room.on('reconnecting', error => {2assert.equal(room.state, 'reconnecting');3if (error.code === 53001) {4console.log('Reconnecting your signaling connection!', error.message);5} else if (error.code === 53405) {6console.log('Reconnecting your media connection!', error.message);7}8/* Update the application UI here */9});
reconnected - when the application has successfully re-established its signaling and media connections to the Room. The Room will transition to the "connected" state and will emit the "reconnected" event as follows:
1room.on('reconnected', () => {2assert.equal(room.state, 'connected');3console.log('Reconnected your signaling and media connections!');4/* Update the application UI here */5});
If the application fails to re-establish its signaling connection to the Room, then the Room transitions to the "disconnected" state, and emits the "disconnected" event as follows:
1room.on('disconnected', (room, error) => {2assert.equal(room.state, 'disconnected');3if (error.code === 20104) {4console.log('Signaling reconnection failed due to expired AccessToken!');5} else if (error.code === 53000) {6console.log('Signaling reconnection attempts exhausted!');7} else if (error.code === 53002) {8console.log('Signaling reconnection took too long!');9}10});
The RemoteParticipant.state
property represents the status of the RemoteParticipant's signaling connection to the Room. When the RemoteParticipant joins a Room, it will transition to the "connected" state. Similarly, when the RemoteParticipant disconnects from a Room, it will transition to the "disconnected" state. Apart from these basic states, there are two Reconnection Events:
reconnecting - when the RemoteParticipant is trying to re-establish its signaling connection to the Room. When the RemoteParticipant transitions to this state, it will emit the "reconnecting" event as follows:
1remoteParticipant.on('reconnecting', () => {2assert.equal(remoteParticipant.state, 'reconnecting');3console.log(`${remoteParticipant.identity} is reconnecting the signaling connection to the Room!`);4/* Update the RemoteParticipant UI here */5});
participantReconnecting - alternative Room-level event for RemoteParticipant's "reconnecting" event.
1room.on('participantReconnecting', remoteParticipant => {2assert.equals(remoteParticipant.state, 'reconnecting');3console.log(`${remoteParticipant.identity} is reconnecting the signaling connection to the Room!`);4/* Update the RemoteParticipant UI here */5});
reconnected - when the RemoteParticipant has successfully re-established its signaling connection to the Room. The Remote transitions to the "connected" state and will emit the "reconnected" event as follows:
1remoteParticipant.on('reconnected', () => {2assert.equals(remoteParticipant.state, 'connected');3console.log(`${remoteParticipant.identity} has reconnected the signaling connection to the Room!`);4/* Update the RemoteParticipant UI here */5});
participantReconnected - alternative Room-level event for RemoteParticipant's "reconnected" event.
1room.on('participantReconnected', remoteParticipant => {2assert.equals(remoteParticipant.state, 'connected');3console.log(`${remoteParticipant.identity} has reconnected the signaling connection to the Room!`);4/* Update the RemoteParticipant UI here */5});
Reconnection States and Events | Twilio Video SDK versions |
---|---|
Media Reconnection (Room) | twilio-video.js@1.9.0+ |
Media + Signaling Reconnection (Room) | twilio-video.js@2.0.0+ |
Signaling Reconnection (RemoteParticipant) | twilio-video.js@2.1.0+ |
Media + Signaling Reconnection (RemoteParticipant) | Coming Soon |
Let's say that you have created an AccessToken that is valid for 1 hour and then use it to join a Room. After 1 hour and 15 minutes, due to some network disruption or handoff, the Twilio Video SDK attempts to reconnect to the Room. Because the AccessToken is expired at this time, the reconnection will fail, and you will be disconnected from the Room. In order to prevent this from happening, make sure that you create AccessTokens that are valid for the maximum allowed session duration, which is currently 24 hours (86,400 seconds).
If you are concerned that this AccessToken can be re-used later by a malicious actor, you can scope the AccessToken to a particular Room and an identity, thereby making sure that no one can re-use the AccessToken to join another Room even though it is still valid in terms of its Time-To-Live.
1const AccessToken = require('twilio').jwt.AccessToken;23/**4* Create an AccessToken that is valid for 24 hours.5*/6const token = new AccessToken(7'your_twilio_account_sid',8'your_twilio_api_key',9'your_twilio_api_secret',10{ ttl: 86400 });1112/**13* Scope the AccessToken to a particular identity.14*/15token.identity = 'alice';1617/**18* Scope the AccessToken to a particular Room.19*/20token.addGrant(new VideoGrant({21room: 'my-room'22}));