Skip to main content

​
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 instead — see 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 (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 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 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.