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

# Consultation widget console

> Ship a 'video call us' button from the dashboard — pick a queued-visitor or direct drop-in preset, bind it to a persistent room, copy the ready-built embed snippet, and read the recording retention window.

# Consultation widget console

The dashboard ships a dedicated console for the "video call us" pattern at
**Voice → Video → Widget** (`/voice/video/widget`). It consolidates the whole
embed workflow into one page: pick a consultation preset, tie it to one of
your persistent rooms, copy the resulting embed snippet, and check the
recording retention window — a loop that was previously spread across the
Rooms list, the lobby panel, and the retention settings shard.

Use the console when you want a working button with the least hand-assembled
markup. When you need your own token-mint backend or a custom UI, use the
[embed guide](/guides/embed-video-consultation-button) instead — see
[When not to use the console](#7-when-not-to-use-the-console).

## 1. Quick verification

Open the console before you wire anything:

1. Navigate to **Voice → Video → Widget** in the dashboard.
2. Confirm the two preset cards render — **Queued visitor (waiting room)** and
   **Direct drop-in (no lobby)**.
3. If the preset cards render, the console is live for your workspace.

## 2. Prerequisites

* **Role the API accepts:** `owner`, `admin`, or `developer`. Every action on
  this page (selecting a room, generating the snippet) needs write access to
  video, and that route is restricted to those roles, so view-only members
  will not load the page.
* **One persistent video room.** The consultation button mints join tokens
  against a single long-lived room ("the support room", "the sales team
  room"). Create it from the
  [video meetings hub](/guides/video-meetings) (**Rooms → New room**) if none
  of your rooms show up. The page renders an empty state pointing back at the
  hub until at least one scheduled room exists.

## 3. The two presets

Choosing a preset is the first decision — it re-derives the snippet options,
the cue chips under the card, and the waiting-room guidance:

### Queued visitor (waiting room)

Holds every new join in the lobby so a host (agent) admits them from the
roster. This is the default preset for a shared support queue — agents answer
in order and nobody lands mid-conversation. The page pre-arms the
**waiting-room + host-admit** cues, starts visitors audio-only until they
open their camera, and recommends arming the room's waiting room from the
host moderation panel.

### Direct drop-in (no lobby)

The visitor joins immediately with no lobby gate. Use this when the button is
already gated by your own routing — for example, only rendered during
business hours, or behind your own queue UI.

Both presets carry the same **recording enabled** and **read the retention
window** cues — only the lobby behavior differs between them.

## 4. Room binding

The widget needs **one persistent room behind it** — pick it in the first
card ("Pick the room behind the button"). The picker lists your scheduled
rooms with a filter field; the hint under the card stays visible until a room
is selected.

Lobby state interacts with the preset here:

* If you pick the **queued** preset, the page tells you to arm the room's
  waiting room from the host moderation panel (the toggle in the in-call
  view).
* If the room already has its waiting room enabled, the lobby state readout
  confirms it — the direct preset will bypass the lobby for that room's
  visitors anyway.

The agent routing panel stays shared with every other consultation flow —
joins are routed by the waiting-room gate plus the host roster, not by any
widget-specific queue.

## 5. Copy the auto-built embed snippet

The console builds the snippet for you across three tabs that mirror the
video-room embed dialog's breakdown:

* **Element** — the `<orbit-video-room>` web component with the preset's
  attributes pre-filled.
* **JavaScript** — `OrbitVideoRoom.init(...)` with the same options.
* **Server** — a ready-built `curl` that calls the join endpoint with the
  selected room's ID, so your backend mints tokens per click against a real
  room, not a placeholder you have to fill in later.

The copy button only activates **when the snippet is runnable**: with no room
selected the room ID is substituted with a placeholder and the page keeps the
pick-a-room hint visible, so you cannot accidentally copy an un-runnable
snippet. Copying shows the check icon briefly and resets; if the clipboard
API is unavailable the page prompts you to select and copy manually.

Under the snippet, the four-step panel reminds you of the runtime contract:

1. The visitor's browser loads the snippet and mounts the room behind the
   button only when clicked.
2. Your backend calls `POST /api/v1/video/rooms-scheduled/:id/join` per
   click to mint the join token.
3. New joins hold in the waiting room (when armed) until a host admits.
4. Recordings land under your tenant-controlled retention window.

## 6. Retention readout

The **Recording retention** card is **read-only on this page**. It renders
the effective window for video-room recordings — sessions whose `ended_at` is
older than the window soft-delete, and after a further **14-day grace** they
hard-delete. Until your workspace overrides it, the **default is 90 days**
(plus the 14-day grace).

To change the window, use the **Open the retention editor** link — it jumps
to the tenant-level retention shard under **Settings → Compliance →
Retention**, where `owner` and `admin` can set `video_room_retention_days`.
The console never writes retention; it only reads the resolved value so an
operator can confirm the window before shipping the button. See the
[BYO-storage recording guide](/guides/video-recording-byo-storage) for how
the window interacts with your own storage.

## 7. When not to use the console

The console exists for the common button shapes. Reach for the
[embed guide](/guides/embed-video-consultation-button) instead when:

* you build a **custom UI** on top of the SDK events rather than the prebuilt
  `OrbitVideoRoom` surface, or you mint tokens on your own backend with
  custom auth or per-visitor room allocation;
* you need the lobby / record / retain behavior composed differently from
  the two presets.

## Related guides

* [Video meetings](/guides/video-meetings) — create and manage the rooms
  behind the button
* [Video room access tokens](/guides/video-room-access-tokens) — the join
  token contract the Server tab snippet calls
* [Video recording to your own storage](/guides/video-recording-byo-storage)
* [Embed a video consultation button](/guides/embed-video-consultation-button)
  — the SDK-level path when the console presets do not fit