Skip to main content

​
Persistent video rooms — create, re-open, embed

A persistent video room is a long-lived room on Orbit Media that you create once and reuse indefinitely. Unlike a standard scheduled room, which expires four hours after creation unless it is extended, a persistent room carries a 10-year expiry and re-opens automatically when the next participant joins. Use a persistent room for fixed destinations such as:
  • an embedded “video call us” button on your website
  • a permanent sales or support queue
  • a department drop-in room that agents and visitors reuse throughout the day

​
What makes a room persistent

A room becomes persistent when settings.persistent is set to true. This happens in two places:
  • the Create Room toggle in the dashboard under Voice → Video → Rooms
  • POST /api/v1/video/rooms-scheduled with persistent: true
When a room is created as persistent, the platform applies these rules: The 10-year expiry keeps the expires_at column non-NULL, which the re-open gate requires. The sweeper does not treat the room as abandoned when it empties; it marks the room ended with reason room_finished, which the join route recognizes as reversible.

​
Create a persistent room from the dashboard

  1. Open Voice → Video → Rooms.
  2. Click New room.
  3. Fill in the room name and any other settings — waiting room, recording, participant cap.
  4. Toggle Persistent room.
  5. Save the room.
The room appears in the Rooms list with the persistent badge. It is immediately available for joins and widget assignment.

​
Create a persistent room over the API

The response returns the room object, including expires_at set 10 years in the future. You cannot set max_duration_minutes or recurrence_rule on the same request; the API returns a 422 if either is present.

​
Re-open after the room empties

When the last participant leaves a persistent room, the SFU closes the media room after five minutes of emptiness. The platform expiry sweeper may also mark the database row ended with reason room_finished. Either way, the next call to POST /api/v1/video/rooms-scheduled/:id/join re-opens the room lazily. The join route checks endedRoomIsReopenable and, when the room is persistent and within its expires_at headroom, recreates the media room and admits the participant. Existing guest invites and the widget continue to work across re-opens.

​
Wire the room into the consultation widget

The Voice → Video → Widget builder only lists persistent rooms. This is intentional: a drop-in “video call us” button needs a room that survives between calls.
  1. Open Voice → Video → Widget.
  2. Pick a preset — queued visitor for a waiting-room flow, or direct drop-in for immediate join.
  3. Under Room, select one of your persistent rooms.
  4. Copy the generated iframe or script snippet and paste it into your site.
For the full embed flow, see Embed a video consultation button.

​
Lifecycle on the SFU

  • While participants are present, the media room stays live.
  • When the room becomes empty, the SFU reclaims the media room after a 5 min empty timeout.
  • The database row may become ended with reason room_finished.
  • The next join regenerates the access token, lazily recreates the media room, and places the participant according to the room’s waiting-room and tier settings.
This means a persistent room consumes SFU resources only while it is active, not for the full 10-year lifetime.

​
API reference

  • POST /api/v1/video/rooms-scheduled — create a persistent room with persistent: true
  • POST /api/v1/video/rooms-scheduled/:id/join — join or re-open a persistent room
  • Video API reference — full scheduled-room endpoint surface