> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Create a persistent video room that stays open for up to 10 years, re-opens automatically after it empties, and powers the embedded consultation widget.

# 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:

| Property | Standard room | Persistent room |
| - | - | - |
| Default `expires_at` | `NOW() + 4 hours` | `NOW() + 10 years` |
| Auto-end bound | `max_duration_minutes`, if set | none — cannot be combined with `max_duration_minutes` |
| Recurring meetings | allowed via `recurrence_rule` | not allowed |
| Ends by operator | permanent | permanent |
| Ends by sweeper when empty | `timeout` (terminal) | `room_finished` (re-openable) |

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

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/video/rooms-scheduled" \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support queue",
    "persistent": true,
    "waiting_room": true,
    "recording_enabled": true
  }'
```

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](/guides/embed-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](/api-reference/video) — full scheduled-room endpoint surface

## Related

* [Video meetings and conferences](/guides/video-meetings) — scheduled rooms, invites, and registration
* [Video room consoles](/guides/video-room-consoles) — Sessions, Widget, Templates, and Live
* [Embed a video consultation button](/guides/embed-video-consultation-button) — end-to-end widget walkthrough
* [Video room access tokens](/guides/video-room-access-tokens) — what the join token grants


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.