Reconnection States and Events

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.

• Room Reconnection States and Events
• RemoteParticipant Reconnection States and Events
• Availability
• Preventing Reconnection Failure due to Expired AccessToken
• Handling Browser Session Termination and Page Navigation

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:

1
room.on('reconnecting', error => {
2
  assert.equal(room.state, 'reconnecting');
3
  if (error.code === 53001) {
4
    console.log('Reconnecting your signaling connection!', error.message);
5
  } else if (error.code === 53405) {
6
    console.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:

1
room.on('reconnected', () => {
2
  assert.equal(room.state, 'connected');
3
  console.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:

1
room.on('disconnected', (room, error) => {
2
  assert.equal(room.state, 'disconnected');
3
  if (error.code === 20104) {
4
    console.log('Signaling reconnection failed due to expired AccessToken!');
5
  } else if (error.code === 53000) {
6
    console.log('Signaling reconnection attempts exhausted!');
7
  } else if (error.code === 53002) {
8
    console.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:

1
remoteParticipant.on('reconnecting', () => {
2
  assert.equal(remoteParticipant.state, 'reconnecting');
3
  console.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.

1
room.on('participantReconnecting', remoteParticipant => {
2
  assert.equals(remoteParticipant.state, 'reconnecting');
3
  console.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:

1
remoteParticipant.on('reconnected', () => {
2
  assert.equals(remoteParticipant.state, 'connected');
3
  console.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.

1
room.on('participantReconnected', remoteParticipant => {
2
  assert.equals(remoteParticipant.state, 'connected');
3
  console.log(`${remoteParticipant.identity} has reconnected the signaling connection to the Room!`);
4
  /* Update the RemoteParticipant UI here */
5
});

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.

1
const AccessToken = require('twilio').jwt.AccessToken;
2

3
/**
4
 * Create an AccessToken that is valid for 24 hours.
5
 */
6
const token = new AccessToken(
7
  'your_twilio_account_sid',
8
  'your_twilio_api_key',
9
  'your_twilio_api_secret',
10
  { ttl: 86400 });
11

12
/**
13
 * Scope the AccessToken to a particular identity.
14
 */
15
token.identity = 'alice';
16

17
/**
18
 * Scope the AccessToken to a particular Room.
19
 */
20
token.addGrant(new VideoGrant({
21
  room: 'my-room'
22
}));

When a Participant closes the tab/browser or navigates away from your application, we recommend that you disconnect from the Room so that other Participants are immediately notified. You can achieve this as follows:

1
window.addEventListener('beforeunload', () => {
2
  room.disconnect();
3
});