Issue

Twilio Programmable Video rooms offer several parameters to control room lifecycles, such as unusedRoomTimeout and emptyRoomTimeout. However, some developers notice that rooms can remain active for the full maxParticipantDuration when only a single participant is present, leading to unexpected charges or resource usage. This article explains why this happens, clarifies the difference between timeout parameters, and offers best practices for managing single-participant rooms.

Symptoms

• A Video room remains active for the full maxParticipantDuration (e.g., 90 minutes) when only one participant is present.
• The room does not end automatically after a period of inactivity with a single participant.
• The unusedRoomTimeout and emptyRoomTimeout parameters do not appear to close the room in this scenario.
  
   

Product

Programmable Video

 

Environment

Twilio Console

 

Cause

Parameter Behavior

• unusedRoomTimeout: This parameter determines how long a room will remain open if no participants ever join. If at least one participant joins within the timeout window, this parameter is not triggered.
• emptyRoomTimeout: This parameter controls how long a room stays open after the last participant leaves. If a participant remains in the room, this timeout is not triggered.
• maxParticipantDuration: This is the maximum time a participant can remain in the room. If a single participant stays connected, the room will remain active until this duration is reached.

Key Point:
If a single participant joins and remains in the room, neither unusedRoomTimeout nor emptyRoomTimeout will end the room. The room will only close when the participant leaves or when maxParticipantDuration is reached.

Example

Suppose you create a room with the following parameters:

{
  "unusedRoomTimeout": 1,
  "emptyRoomTimeout": 1,
  "maxParticipantDuration": 5400
}

• If no one joins, the room closes after 1 minute (unusedRoomTimeout).
• If all participants leave, the room closes after 1 minute (emptyRoomTimeout).
• If one participant joins and stays, the room remains open for up to 90 minutes (maxParticipantDuration), regardless of the other timeout settings.

Resolution

• Monitor Room Status: Use Room Status Callback Events to track participant activity in real time.
• Programmatic Room Closure: If your use case requires closing rooms with only one participant after a certain period, implement logic in your application to:
  • Detect when only one participant is present (via status callbacks).
  • Use the Rooms REST API to programmatically complete the room after your desired timeout.
• Automated Jobs: Consider running a scheduled job (cron) to check for and close single-participant rooms that have been active beyond your preferred threshold.

Additional Information

• unusedRoomTimeout and emptyRoomTimeout do not close a room with a single, continuously connected participant.
• To control room duration in this scenario, use maxParticipantDuration or implement custom logic to close rooms as needed.
• Twilio is considering enhancements to support automatic single-participant room timeouts.

Below you will find references to useful documents:

• Twilio Video Rooms Resource Documentation
• Room Status Callback Events
• Understanding Video Rooms

Feature Request

Twilio is aware that some customers would benefit from a built-in single-participant timeout feature. If this is important for your use case, please let Twilio Support know so your feedback can be added to the feature request.